| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
Philips webcams (pwc driver) |
| 4 |
============================ |
| 5 |
|
| 6 |
This file contains some additional information for the Philips and OEM webcams. |
| 7 |
E-mail: [email protected] Last updated: 2004-01-19 |
| 8 |
Site: http://www.smcc.demon.nl/webcam/ |
| 9 |
|
| 10 |
As 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 |
|
| 37 |
The main webpage for the Philips driver is at the address above. It contains |
| 38 |
a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin |
| 39 |
contains decompression routines that allow you to use higher image sizes and |
| 40 |
framerates; in addition the webcam uses less bandwidth on the USB bus (handy |
| 41 |
if you want to run more than 1 camera simultaneously). These routines fall |
| 42 |
under a NDA, and may therefore not be distributed as source; however, its use |
| 43 |
is completely optional. |
| 44 |
|
| 45 |
You can build this code either into your kernel, or as a module. I recommend |
| 46 |
the latter, since it makes troubleshooting a lot easier. The built-in |
| 47 |
microphone is supported through the USB Audio class. |
| 48 |
|
| 49 |
When you load the module you can set some default settings for the |
| 50 |
camera; some programs depend on a particular image-size or -format and |
| 51 |
don't know how to set it properly in the driver. The options are: |
| 52 |
|
| 53 |
size |
| 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 |
|
| 59 |
fps |
| 60 |
Specifies the desired framerate. Is an integer in the range of 4-30. |
| 61 |
|
| 62 |
fbufs |
| 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 |
|
| 69 |
mbufs |
| 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 |
|
| 87 |
power_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 |
|
| 95 |
compression (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 |
|
| 116 |
leds |
| 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 |
|
| 139 |
dev_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 |
|
| 191 |
trace |
| 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 |
|
| 230 |
Example:: |
| 231 |
|
| 232 |
# modprobe pwc size=cif fps=15 power_save=1 |
| 233 |
|
| 234 |
The fbufs, mbufs and trace parameters are global and apply to all connected |
| 235 |
cameras. Each camera has its own set of buffers. |
| 236 |
|
| 237 |
size and fps only specify defaults when you open() the device; this is to |
| 238 |
accommodate some tools that don't set the size. You can change these |
| 239 |
settings after open() with the Video4Linux ioctl() calls. The default of |
| 240 |
defaults is QCIF size at 10 fps. |
| 241 |
|
| 242 |
The compression parameter is semiglobal; it sets the initial compression |
| 243 |
preference for all camera's, but this parameter can be set per camera with |
| 244 |
the VIDIOCPWCSCQUAL ioctl() call. |
| 245 |
|
| 246 |
All parameters are optional. |
| 247 |
|