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