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