1 This file contains some additional information for the Philips webcams.
2 E-mail: webcam@smcc.demon.nl Last updated: 2001-09-24
4 The main webpage for the Philips driver is http://www.smcc.demon.nl/webcam/.
5 It contains a lot of extra information, a FAQ, and the binary plugin
6 'PWCX'. This plugin contains decompression routines that allow you to
7 use higher image sizes and framerates; in addition the webcam uses less
8 bandwidth on the USB bus (handy if you want to run more than 1 camera
9 simultaneously). These routines fall under an NDA, and may therefor not be
10 distributed as source; however, its use is completely optional.
12 You can build this code either into your kernel, or as a module. I recommend
13 the latter, since it makes troubleshooting a lot easier. The built-in
14 microphone is supported through the USB Audio class.
16 When you load the module you can set some default settings for the
17 camera; some programs depend on a particular image-size or -format and
18 don't know how to set it properly in the driver. The options are:
21 Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or
22 'vga', for an image size of resp. 128x96, 160x120, 176x144,
23 320x240, 352x288 and 640x480 (of course, only for those cameras that
24 support these resolutions).
27 Specifies the desired framerate. Is an integer in the range of 4-30.
30 This parameter specifies the number of internal buffers to use for storing
31 frames from the cam. This will help if the process that reads images from
32 the cam is a bit slow or momentarily busy. However, on slow machines it
33 only introduces lag, so choose carefully. The default is 3, which is
34 reasonable. You can set it between 2 and 5.
37 This is an integer between 1 and 4. It will tell the module the number of
38 buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.
39 The default is 2, which is adequate for most applications (double
42 Should you experience a lot of 'Dumping frame...' messages during
43 grabbing with a tool that uses mmap(), you might want to increase if.
44 However, it doesn't really buffer images, it just gives you a bit more
45 slack when your program is behind. But you need a multi-threaded or
46 forked program to really take advantage of these buffers.
48 The absolute maximum is 4, but don't set it too high! Every buffer takes
49 up 1.22 MB of RAM, so unless you have a lot of memory setting this to
50 something more than 2 is an absolute waste. This memory is only
51 allocated during open(), so nothing is wasted when the camera is not in
55 When power_save is enabled (set to 1), the module will try to shut down
56 the cam on close() and re-activate on open(). This will save power and
57 turn off the LED. Not all cameras support this though (the 645 and 646
58 don't have power saving at all), and some models don't work either (they
59 will shut down, but never wake up). Consider this experimental. By
60 default this option is disabled.
62 compression (only useful with the plugin)
63 With this option you can control the compression factor that the camera
64 uses to squeeze the image through the USB bus. You can set the
65 parameter between 0 and 3:
66 0 = prefer uncompressed images; if the requested mode is not available
67 in an uncompressed format, the driver will silently switch to low
70 2 = medium compression.
73 High compression takes less bandwidth of course, but it could also
74 introduce some unwanted artefacts. The default is 2, medium compression.
75 See the FAQ on the website for an overview of which modes require
78 The compression parameter only applies to the Vesta & ToUCam cameras.
79 The 645 and 646 have fixed compression parameters.
82 This settings takes 2 integers, that define the on/off time for the LED
83 (in milliseconds). One of the interesting things that you can do with
84 this is let the LED blink while the camera is in use. This:
88 will blink the LED once every second. But with:
92 the LED never goes on, making it suitable for silent survaillance.
94 By default the camera's LED is on solid while in use, and turned off
95 when the camera is not used anymore.
97 This parameter works only with the ToUCam range of cameras (730, 740,
98 750). For other cameras this command is silently ignored, and the LED
102 A long standing problem with USB devices is their dynamic nature: you
103 never know what device a camera gets assigned; it depends on module load
104 order, the hub configuration, the order in which devices are plugged in,
105 and the phase of the moon (i.e. it can be random). With this option you
106 can give the driver a hint as to what video device node (/dev/videoX) it
107 should use with a specific camera. This is also handy if you have two
108 cameras of the same model.
110 A camera is specified by its type (the number from the camera model,
111 like PCA645, PCVC750VC, etc) and optionally the serial number (visible
112 in /proc/bus/usb/devices). A hint consists of a string with the following
115 [type[.serialnumber]:]node
117 The square brackets mean that both the type and the serialnumber are
118 optional, but a serialnumber cannot be specified without a type (which
119 would be rather pointless). The serialnumber is separated from the type
120 by a '.'; the node number by a ':'.
122 This somewhat cryptic syntax is best explained by a few examples:
124 dev_hint=3,5 The first detected cam gets assigned
125 /dev/video3, the second /dev/video5. Any
126 other cameras will get the first free
127 available slot (see below).
129 dev_hint=645:1,680=2 The PCA645 camera will get /dev/video1,
130 and a PCVC680 /dev/video2.
132 dev_hint=645.0123:3,645.4567:0 The PCA645 camera with serialnumber
133 0123 goes to /dev/video3, the same
134 camera model with the 4567 serial
137 dev_hint=750:1,4,5,6 The PCVC750 camera will get /dev/video1, the
138 next 3 Philips cams will use /dev/video4
141 Some points worth knowing:
142 - Serialnumbers are case sensitive and must be written full, including
143 leading zeroes (it's treated as a string).
144 - If a device node is already occupied, registration will fail and
145 the webcam is not available.
146 - You can have up to 64 video devices; be sure to make enough device
147 nodes in /dev if you want to spread the numbers (this does not apply
148 to devfs). After /dev/video9 comes /dev/video10 (not /dev/videoA).
149 - If a camera does not match any dev_hint, it will simply get assigned
150 the first available device node, just as it used to be.
153 In order to better detect problems, it is now possible to turn on a
154 'trace' of some of the calls the module makes; it logs all items in your
155 kernel log at debug level.
157 The trace variable is a bitmask; each bit represents a certain feature.
158 If you want to trace something, look up the bit value(s) in the table
159 below, add the values together and supply that to the trace variable.
161 Value Value Description Default
163 1 0x1 Module initialization; this will log messages On
164 while loading and unloading the module
166 2 0x2 probe() and disconnect() traces On
168 4 0x4 Trace open() and close() calls Off
170 8 0x8 read(), mmap() and associated ioctl() calls Off
172 16 0x10 Memory allocation of buffers, etc. Off
174 32 0x20 Showing underflow, overflow and Dumping frame On
177 64 0x40 Show viewport and image sizes Off
180 For example, to trace the open() & read() fuctions, sum 8 + 4 = 12,
181 so you would supply trace=12 during insmod or modprobe. If
182 you want to turn the initialization and probing tracing off, set trace=0.
183 The default value for trace is 35 (0x23).
187 # modprobe pwc size=cif fps=15 power_save=1
189 The fbufs, mbufs and trace parameters are global and apply to all connected
190 cameras. Each camera has its own set of buffers.
192 size and fps only specify defaults when you open() the device; this is to
193 accommodate some tools that don't set the size. You can change these
194 settings after open() with the Video4Linux ioctl() calls. The default of
195 defaults is QCIF size at 10 fps, BGR order.
197 The compression parameter is semiglobal; it sets the initial compression
198 preference for all camera's, but this parameter can be set per camera with
199 the VIDIOCPWCSCQUAL ioctl() call.
201 All parameters are optional.