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 237