Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | This file contains some additional information for the Philips and OEM webcams. |
2 | E-mail: webcam@smcc.demon.nl Last updated: 2004-01-19 | |
3 | Site: http://www.smcc.demon.nl/webcam/ | |
4 | ||
5 | As 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 | ||
31 | The main webpage for the Philips driver is at the address above. It contains | |
32 | a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin | |
33 | contains decompression routines that allow you to use higher image sizes and | |
34 | framerates; in addition the webcam uses less bandwidth on the USB bus (handy | |
35 | if you want to run more than 1 camera simultaneously). These routines fall | |
36 | under a NDA, and may therefor not be distributed as source; however, its use | |
37 | is completely optional. | |
38 | ||
39 | You can build this code either into your kernel, or as a module. I recommend | |
40 | the latter, since it makes troubleshooting a lot easier. The built-in | |
41 | microphone is supported through the USB Audio class. | |
42 | ||
43 | When you load the module you can set some default settings for the | |
44 | camera; some programs depend on a particular image-size or -format and | |
45 | don't know how to set it properly in the driver. The options are: | |
46 | ||
47 | size | |
48 | Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or | |
49 | 'vga', for an image size of resp. 128x96, 160x120, 176x144, | |
d56410e0 | 50 | 320x240, 352x288 and 640x480 (of course, only for those cameras that |
1da177e4 LT |
51 | support these resolutions). |
52 | ||
53 | fps | |
54 | Specifies the desired framerate. Is an integer in the range of 4-30. | |
55 | ||
56 | fbufs | |
a982ac06 | 57 | This parameter specifies the number of internal buffers to use for storing |
d56410e0 | 58 | frames from the cam. This will help if the process that reads images from |
a982ac06 | 59 | the cam is a bit slow or momentarily busy. However, on slow machines it |
d56410e0 | 60 | only introduces lag, so choose carefully. The default is 3, which is |
1da177e4 LT |
61 | reasonable. You can set it between 2 and 5. |
62 | ||
63 | mbufs | |
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). | |
d56410e0 | 68 | |
1da177e4 | 69 | Should you experience a lot of 'Dumping frame...' messages during |
d56410e0 | 70 | grabbing with a tool that uses mmap(), you might want to increase if. |
1da177e4 LT |
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 | ||
81 | power_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 | ||
89 | compression (only useful with the plugin) | |
90 | With this option you can control the compression factor that the camera | |
d56410e0 | 91 | uses to squeeze the image through the USB bus. You can set the |
1da177e4 LT |
92 | parameter between 0 and 3: |
93 | 0 = prefer uncompressed images; if the requested mode is not available | |
d56410e0 MCC |
94 | in an uncompressed format, the driver will silently switch to low |
95 | compression. | |
1da177e4 LT |
96 | 1 = low compression. |
97 | 2 = medium compression. | |
98 | 3 = high compression. | |
d56410e0 | 99 | |
1da177e4 LT |
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 | ||
109 | leds | |
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 | |
d56410e0 | 115 | |
1da177e4 LT |
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, | |
d56410e0 | 126 | 750) and OEMs. For other cameras this command is silently ignored, and |
1da177e4 LT |
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 | ||
132 | dev_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 | |
d56410e0 | 147 | |
1da177e4 LT |
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 ':'. | |
d56410e0 | 152 | |
1da177e4 LT |
153 | This somewhat cryptic syntax is best explained by a few examples: |
154 | ||
155 | dev_hint=3,5 The first detected cam gets assigned | |
d56410e0 MCC |
156 | /dev/video3, the second /dev/video5. Any |
157 | other cameras will get the first free | |
158 | available slot (see below). | |
1da177e4 LT |
159 | |
160 | dev_hint=645:1,680:2 The PCA645 camera will get /dev/video1, | |
d56410e0 MCC |
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. | |
1da177e4 | 167 | |
d56410e0 MCC |
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. | |
1da177e4 LT |
171 | |
172 | Some points worth knowing: | |
d56410e0 | 173 | - Serialnumbers are case sensitive and must be written full, including |
1da177e4 | 174 | leading zeroes (it's treated as a string). |
d56410e0 | 175 | - If a device node is already occupied, registration will fail and |
1da177e4 LT |
176 | the webcam is not available. |
177 | - You can have up to 64 video devices; be sure to make enough device | |
bf6ee0ae AB |
178 | nodes in /dev if you want to spread the numbers. |
179 | After /dev/video9 comes /dev/video10 (not /dev/videoA). | |
1da177e4 LT |
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 | ||
183 | trace | |
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. | |
d56410e0 | 189 | If you want to trace something, look up the bit value(s) in the table |
1da177e4 LT |
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 | |
d56410e0 | 195 | while loading and unloading the module |
1da177e4 LT |
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 | |
d56410e0 | 206 | messages |
1da177e4 LT |
207 | |
208 | 64 0x40 Show viewport and image sizes Off | |
209 | ||
210 | 128 0x80 PWCX debugging Off | |
211 | ||
a982ac06 | 212 | For example, to trace the open() & read() functions, sum 8 + 4 = 12, |
1da177e4 LT |
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 | ||
219 | Example: | |
d56410e0 | 220 | |
1da177e4 LT |
221 | # modprobe pwc size=cif fps=15 power_save=1 |
222 | ||
223 | The fbufs, mbufs and trace parameters are global and apply to all connected | |
224 | cameras. Each camera has its own set of buffers. | |
225 | ||
226 | size and fps only specify defaults when you open() the device; this is to | |
227 | accommodate some tools that don't set the size. You can change these | |
228 | settings after open() with the Video4Linux ioctl() calls. The default of | |
229 | defaults is QCIF size at 10 fps. | |
230 | ||
231 | The compression parameter is semiglobal; it sets the initial compression | |
232 | preference for all camera's, but this parameter can be set per camera with | |
233 | the VIDIOCPWCSCQUAL ioctl() call. | |
234 | ||
235 | All parameters are optional. | |
236 |