blob: d38dd791511e16bf2f74d9509b869d0ac9373a2d [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001This 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
Daniel Mack3ad2f3f2010-02-03 08:01:28 +080036under a NDA, and may therefore not be distributed as source; however, its use
Linus Torvalds1da177e2005-04-16 15:20:36 -070037is 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,
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030050 320x240, 352x288 and 640x480 (of course, only for those cameras that
Linus Torvalds1da177e2005-04-16 15:20:36 -070051 support these resolutions).
52
53fps
54 Specifies the desired framerate. Is an integer in the range of 4-30.
55
56fbufs
Matt LaPlantea982ac02007-05-09 07:35:06 +020057 This parameter specifies the number of internal buffers to use for storing
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030058 frames from the cam. This will help if the process that reads images from
Matt LaPlantea982ac02007-05-09 07:35:06 +020059 the cam is a bit slow or momentarily busy. However, on slow machines it
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030060 only introduces lag, so choose carefully. The default is 3, which is
Linus Torvalds1da177e2005-04-16 15:20:36 -070061 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).
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030068
Linus Torvalds1da177e2005-04-16 15:20:36 -070069 Should you experience a lot of 'Dumping frame...' messages during
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030070 grabbing with a tool that uses mmap(), you might want to increase if.
Linus Torvalds1da177e2005-04-16 15:20:36 -070071 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
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030091 uses to squeeze the image through the USB bus. You can set the
Linus Torvalds1da177e2005-04-16 15:20:36 -070092 parameter between 0 and 3:
93 0 = prefer uncompressed images; if the requested mode is not available
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030094 in an uncompressed format, the driver will silently switch to low
95 compression.
Linus Torvalds1da177e2005-04-16 15:20:36 -070096 1 = low compression.
97 2 = medium compression.
98 3 = high compression.
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -030099
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100 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
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300115
Linus Torvalds1da177e2005-04-16 15:20:36 -0700116 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,
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300126 750) and OEMs. For other cameras this command is silently ignored, and
Linus Torvalds1da177e2005-04-16 15:20:36 -0700127 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
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300147
Linus Torvalds1da177e2005-04-16 15:20:36 -0700148 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 ':'.
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300152
Linus Torvalds1da177e2005-04-16 15:20:36 -0700153 This somewhat cryptic syntax is best explained by a few examples:
154
155 dev_hint=3,5 The first detected cam gets assigned
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300156 /dev/video3, the second /dev/video5. Any
157 other cameras will get the first free
158 available slot (see below).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700159
160 dev_hint=645:1,680:2 The PCA645 camera will get /dev/video1,
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300161 and a PCVC680 /dev/video2.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700162
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300163 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700171
172 Some points worth knowing:
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300173 - Serialnumbers are case sensitive and must be written full, including
Linus Torvalds1da177e2005-04-16 15:20:36 -0700174 leading zeroes (it's treated as a string).
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300175 - If a device node is already occupied, registration will fail and
Linus Torvalds1da177e2005-04-16 15:20:36 -0700176 the webcam is not available.
177 - You can have up to 64 video devices; be sure to make enough device
Adrian Bunkbf6ee0a2006-10-03 22:17:48 +0200178 nodes in /dev if you want to spread the numbers.
179 After /dev/video9 comes /dev/video10 (not /dev/videoA).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700180 - 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.
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300189 If you want to trace something, look up the bit value(s) in the table
Linus Torvalds1da177e2005-04-16 15:20:36 -0700190 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
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300195 while loading and unloading the module
Linus Torvalds1da177e2005-04-16 15:20:36 -0700196
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
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300206 messages
Linus Torvalds1da177e2005-04-16 15:20:36 -0700207
208 64 0x40 Show viewport and image sizes Off
209
210 128 0x80 PWCX debugging Off
211
Matt LaPlantea982ac02007-05-09 07:35:06 +0200212 For example, to trace the open() & read() functions, sum 8 + 4 = 12,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700213 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:
Mauro Carvalho Chehabd56410e2006-03-25 09:19:53 -0300220
Linus Torvalds1da177e2005-04-16 15:20:36 -0700221 # 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