/drivers/media/video/pwc/philips.txt

  1This file contains some additional information for the Philips and OEM webcams.
  2E-mail: webcam@smcc.demon.nl                        Last updated: 2004-01-19
  3Site: http://www.smcc.demon.nl/webcam/
  4
  5As of this moment, the following cameras are supported:
  6 * Philips PCA645
  7 * Philips PCA646
  8 * Philips PCVC675
  9 * Philips PCVC680
 10 * Philips PCVC690
 11 * Philips PCVC720/40
 12 * Philips PCVC730
 13 * Philips PCVC740
 14 * Philips PCVC750
 15 * Askey VC010
 16 * Creative Labs Webcam 5
 17 * Creative Labs Webcam Pro Ex
 18 * Logitech QuickCam 3000 Pro
 19 * Logitech QuickCam 4000 Pro
 20 * Logitech QuickCam Notebook Pro
 21 * Logitech QuickCam Zoom
 22 * Logitech QuickCam Orbit
 23 * Logitech QuickCam Sphere
 24 * Samsung MPC-C10
 25 * Samsung MPC-C30
 26 * Sotec Afina Eye
 27 * AME CU-001
 28 * Visionite VCS-UM100
 29 * Visionite VCS-UC300
 30
 31The main webpage for the Philips driver is at the address above. It contains
 32a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin
 33contains decompression routines that allow you to use higher image sizes and
 34framerates; in addition the webcam uses less bandwidth on the USB bus (handy
 35if you want to run more than 1 camera simultaneously). These routines fall
 36under a NDA, and may therefore not be distributed as source; however, its use
 37is completely optional.
 38
 39You can build this code either into your kernel, or as a module. I recommend
 40the latter, since it makes troubleshooting a lot easier. The built-in
 41microphone is supported through the USB Audio class.
 42
 43When you load the module you can set some default settings for the
 44camera; some programs depend on a particular image-size or -format and
 45don't know how to set it properly in the driver. The options are:
 46
 47size
 48   Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or
 49   'vga', for an image size of resp. 128x96, 160x120, 176x144,
 50   320x240, 352x288 and 640x480 (of course, only for those cameras that
 51   support these resolutions).
 52
 53fps
 54   Specifies the desired framerate. Is an integer in the range of 4-30.
 55
 56fbufs
 57   This parameter specifies the number of internal buffers to use for storing
 58   frames from the cam. This will help if the process that reads images from
 59   the cam is a bit slow or momentarily busy. However, on slow machines it
 60   only introduces lag, so choose carefully. The default is 3, which is
 61   reasonable. You can set it between 2 and 5.
 62
 63mbufs
 64   This is an integer between 1 and 10. It will tell the module the number of
 65   buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.
 66   The default is 2, which is adequate for most applications (double
 67   buffering).
 68
 69   Should you experience a lot of 'Dumping frame...' messages during
 70   grabbing with a tool that uses mmap(), you might want to increase if.
 71   However, it doesn't really buffer images, it just gives you a bit more
 72   slack when your program is behind. But you need a multi-threaded or
 73   forked program to really take advantage of these buffers.
 74
 75   The absolute maximum is 10, but don't set it too high!  Every buffer takes
 76   up 460 KB of RAM, so unless you have a lot of memory setting this to
 77   something more than 4 is an absolute waste.  This memory is only
 78   allocated during open(), so nothing is wasted when the camera is not in
 79   use.
 80
 81power_save
 82   When power_save is enabled (set to 1), the module will try to shut down
 83   the cam on close() and re-activate on open(). This will save power and
 84   turn off the LED. Not all cameras support this though (the 645 and 646
 85   don't have power saving at all), and some models don't work either (they
 86   will shut down, but never wake up). Consider this experimental. By
 87   default this option is disabled.
 88
 89compression (only useful with the plugin)
 90   With this option you can control the compression factor that the camera
 91   uses to squeeze the image through the USB bus. You can set the
 92   parameter between 0 and 3:
 93     0 = prefer uncompressed images; if the requested mode is not available
 94	 in an uncompressed format, the driver will silently switch to low
 95	 compression.
 96     1 = low compression.
 97     2 = medium compression.
 98     3 = high compression.
 99
100   High compression takes less bandwidth of course, but it could also
101   introduce some unwanted artefacts. The default is 2, medium compression.
102   See the FAQ on the website for an overview of which modes require
103   compression.
104
105   The compression parameter does not apply to the 645 and 646 cameras
106   and OEM models derived from those (only a few). Most cams honour this
107   parameter.
108
109leds
110   This settings takes 2 integers, that define the on/off time for the LED
111   (in milliseconds). One of the interesting things that you can do with
112   this is let the LED blink while the camera is in use. This:
113
114     leds=500,500
115
116   will blink the LED once every second. But with:
117
118     leds=0,0
119
120   the LED never goes on, making it suitable for silent surveillance.
121
122   By default the camera's LED is on solid while in use, and turned off
123   when the camera is not used anymore.
124
125   This parameter works only with the ToUCam range of cameras (720, 730, 740,
126   750) and OEMs. For other cameras this command is silently ignored, and
127   the LED cannot be controlled.
128
129   Finally: this parameters does not take effect UNTIL the first time you
130   open the camera device. Until then, the LED remains on.
131
132dev_hint
133   A long standing problem with USB devices is their dynamic nature: you
134   never know what device a camera gets assigned; it depends on module load
135   order, the hub configuration, the order in which devices are plugged in,
136   and the phase of the moon (i.e. it can be random). With this option you
137   can give the driver a hint as to what video device node (/dev/videoX) it
138   should use with a specific camera. This is also handy if you have two
139   cameras of the same model.
140
141   A camera is specified by its type (the number from the camera model,
142   like PCA645, PCVC750VC, etc) and optionally the serial number (visible
143   in /proc/bus/usb/devices). A hint consists of a string with the following
144   format:
145
146      [type[.serialnumber]:]node
147
148   The square brackets mean that both the type and the serialnumber are
149   optional, but a serialnumber cannot be specified without a type (which
150   would be rather pointless). The serialnumber is separated from the type
151   by a '.'; the node number by a ':'.
152
153   This somewhat cryptic syntax is best explained by a few examples:
154
155     dev_hint=3,5              The first detected cam gets assigned
156			       /dev/video3, the second /dev/video5. Any
157			       other cameras will get the first free
158			       available slot (see below).
159
160     dev_hint=645:1,680:2      The PCA645 camera will get /dev/video1,
161			       and a PCVC680 /dev/video2.
162
163     dev_hint=645.0123:3,645.4567:0	The PCA645 camera with serialnumber
164					0123 goes to /dev/video3, the same
165					camera model with the 4567 serial
166					gets /dev/video0.
167
168     dev_hint=750:1,4,5,6       The PCVC750 camera will get /dev/video1, the
169				next 3 Philips cams will use /dev/video4
170				through /dev/video6.
171
172   Some points worth knowing:
173   - Serialnumbers are case sensitive and must be written full, including
174     leading zeroes (it's treated as a string).
175   - If a device node is already occupied, registration will fail and
176     the webcam is not available.
177   - You can have up to 64 video devices; be sure to make enough device
178     nodes in /dev if you want to spread the numbers.
179     After /dev/video9 comes /dev/video10 (not /dev/videoA).
180   - If a camera does not match any dev_hint, it will simply get assigned
181     the first available device node, just as it used to be.
182
183trace
184   In order to better detect problems, it is now possible to turn on a
185   'trace' of some of the calls the module makes; it logs all items in your
186   kernel log at debug level.
187
188   The trace variable is a bitmask; each bit represents a certain feature.
189   If you want to trace something, look up the bit value(s) in the table
190   below, add the values together and supply that to the trace variable.
191
192   Value  Value   Description					   Default
193   (dec)  (hex)
194       1    0x1   Module initialization; this will log messages       On
195		  while loading and unloading the module
196
197       2    0x2   probe() and disconnect() traces                     On
198
199       4    0x4   Trace open() and close() calls                      Off
200
201       8    0x8   read(), mmap() and associated ioctl() calls         Off
202
203      16   0x10   Memory allocation of buffers, etc.                  Off
204
205      32   0x20   Showing underflow, overflow and Dumping frame       On
206		  messages
207
208      64   0x40   Show viewport and image sizes                       Off
209
210     128   0x80   PWCX debugging                                      Off
211
212   For example, to trace the open() & read() functions, sum 8 + 4 = 12,
213   so you would supply trace=12 during insmod or modprobe. If
214   you want to turn the initialization and probing tracing off, set trace=0.
215   The default value for trace is 35 (0x23).
216
217
218
219Example:
220
221     # modprobe pwc size=cif fps=15 power_save=1
222
223The fbufs, mbufs and trace parameters are global and apply to all connected
224cameras. Each camera has its own set of buffers.
225
226size and fps only specify defaults when you open() the device; this is to
227accommodate some tools that don't set the size. You can change these
228settings after open() with the Video4Linux ioctl() calls. The default of
229defaults is QCIF size at 10 fps.
230
231The compression parameter is semiglobal; it sets the initial compression
232preference for all camera's, but this parameter can be set per camera with
233the VIDIOCPWCSCQUAL ioctl() call.
234
235All parameters are optional.
236