0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 Philips webcams (pwc driver)
0004 ============================
0005
0006 This file contains some additional information for the Philips and OEM webcams.
0007 E-mail: webcam@smcc.demon.nl Last updated: 2004-01-19
0008 Site: http://www.smcc.demon.nl/webcam/
0009
0010 As of this moment, the following cameras are supported:
0011
0012 * Philips PCA645
0013 * Philips PCA646
0014 * Philips PCVC675
0015 * Philips PCVC680
0016 * Philips PCVC690
0017 * Philips PCVC720/40
0018 * Philips PCVC730
0019 * Philips PCVC740
0020 * Philips PCVC750
0021 * Askey VC010
0022 * Creative Labs Webcam 5
0023 * Creative Labs Webcam Pro Ex
0024 * Logitech QuickCam 3000 Pro
0025 * Logitech QuickCam 4000 Pro
0026 * Logitech QuickCam Notebook Pro
0027 * Logitech QuickCam Zoom
0028 * Logitech QuickCam Orbit
0029 * Logitech QuickCam Sphere
0030 * Samsung MPC-C10
0031 * Samsung MPC-C30
0032 * Sotec Afina Eye
0033 * AME CU-001
0034 * Visionite VCS-UM100
0035 * Visionite VCS-UC300
0036
0037 The main webpage for the Philips driver is at the address above. It contains
0038 a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin
0039 contains decompression routines that allow you to use higher image sizes and
0040 framerates; in addition the webcam uses less bandwidth on the USB bus (handy
0041 if you want to run more than 1 camera simultaneously). These routines fall
0042 under a NDA, and may therefore not be distributed as source; however, its use
0043 is completely optional.
0044
0045 You can build this code either into your kernel, or as a module. I recommend
0046 the latter, since it makes troubleshooting a lot easier. The built-in
0047 microphone is supported through the USB Audio class.
0048
0049 When you load the module you can set some default settings for the
0050 camera; some programs depend on a particular image-size or -format and
0051 don't know how to set it properly in the driver. The options are:
0052
0053 size
0054 Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or
0055 'vga', for an image size of resp. 128x96, 160x120, 176x144,
0056 320x240, 352x288 and 640x480 (of course, only for those cameras that
0057 support these resolutions).
0058
0059 fps
0060 Specifies the desired framerate. Is an integer in the range of 4-30.
0061
0062 fbufs
0063 This parameter specifies the number of internal buffers to use for storing
0064 frames from the cam. This will help if the process that reads images from
0065 the cam is a bit slow or momentarily busy. However, on slow machines it
0066 only introduces lag, so choose carefully. The default is 3, which is
0067 reasonable. You can set it between 2 and 5.
0068
0069 mbufs
0070 This is an integer between 1 and 10. It will tell the module the number of
0071 buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.
0072 The default is 2, which is adequate for most applications (double
0073 buffering).
0074
0075 Should you experience a lot of 'Dumping frame...' messages during
0076 grabbing with a tool that uses mmap(), you might want to increase if.
0077 However, it doesn't really buffer images, it just gives you a bit more
0078 slack when your program is behind. But you need a multi-threaded or
0079 forked program to really take advantage of these buffers.
0080
0081 The absolute maximum is 10, but don't set it too high! Every buffer takes
0082 up 460 KB of RAM, so unless you have a lot of memory setting this to
0083 something more than 4 is an absolute waste. This memory is only
0084 allocated during open(), so nothing is wasted when the camera is not in
0085 use.
0086
0087 power_save
0088 When power_save is enabled (set to 1), the module will try to shut down
0089 the cam on close() and re-activate on open(). This will save power and
0090 turn off the LED. Not all cameras support this though (the 645 and 646
0091 don't have power saving at all), and some models don't work either (they
0092 will shut down, but never wake up). Consider this experimental. By
0093 default this option is disabled.
0094
0095 compression (only useful with the plugin)
0096 With this option you can control the compression factor that the camera
0097 uses to squeeze the image through the USB bus. You can set the
0098 parameter between 0 and 3::
0099
0100 0 = prefer uncompressed images; if the requested mode is not available
0101 in an uncompressed format, the driver will silently switch to low
0102 compression.
0103 1 = low compression.
0104 2 = medium compression.
0105 3 = high compression.
0106
0107 High compression takes less bandwidth of course, but it could also
0108 introduce some unwanted artefacts. The default is 2, medium compression.
0109 See the FAQ on the website for an overview of which modes require
0110 compression.
0111
0112 The compression parameter does not apply to the 645 and 646 cameras
0113 and OEM models derived from those (only a few). Most cams honour this
0114 parameter.
0115
0116 leds
0117 This settings takes 2 integers, that define the on/off time for the LED
0118 (in milliseconds). One of the interesting things that you can do with
0119 this is let the LED blink while the camera is in use. This::
0120
0121 leds=500,500
0122
0123 will blink the LED once every second. But with::
0124
0125 leds=0,0
0126
0127 the LED never goes on, making it suitable for silent surveillance.
0128
0129 By default the camera's LED is on solid while in use, and turned off
0130 when the camera is not used anymore.
0131
0132 This parameter works only with the ToUCam range of cameras (720, 730, 740,
0133 750) and OEMs. For other cameras this command is silently ignored, and
0134 the LED cannot be controlled.
0135
0136 Finally: this parameters does not take effect UNTIL the first time you
0137 open the camera device. Until then, the LED remains on.
0138
0139 dev_hint
0140 A long standing problem with USB devices is their dynamic nature: you
0141 never know what device a camera gets assigned; it depends on module load
0142 order, the hub configuration, the order in which devices are plugged in,
0143 and the phase of the moon (i.e. it can be random). With this option you
0144 can give the driver a hint as to what video device node (/dev/videoX) it
0145 should use with a specific camera. This is also handy if you have two
0146 cameras of the same model.
0147
0148 A camera is specified by its type (the number from the camera model,
0149 like PCA645, PCVC750VC, etc) and optionally the serial number (visible
0150 in /sys/kernel/debug/usb/devices). A hint consists of a string with the
0151 following format::
0152
0153 [type[.serialnumber]:]node
0154
0155 The square brackets mean that both the type and the serialnumber are
0156 optional, but a serialnumber cannot be specified without a type (which
0157 would be rather pointless). The serialnumber is separated from the type
0158 by a '.'; the node number by a ':'.
0159
0160 This somewhat cryptic syntax is best explained by a few examples::
0161
0162 dev_hint=3,5 The first detected cam gets assigned
0163 /dev/video3, the second /dev/video5. Any
0164 other cameras will get the first free
0165 available slot (see below).
0166
0167 dev_hint=645:1,680:2 The PCA645 camera will get /dev/video1,
0168 and a PCVC680 /dev/video2.
0169
0170 dev_hint=645.0123:3,645.4567:0 The PCA645 camera with serialnumber
0171 0123 goes to /dev/video3, the same
0172 camera model with the 4567 serial
0173 gets /dev/video0.
0174
0175 dev_hint=750:1,4,5,6 The PCVC750 camera will get /dev/video1, the
0176 next 3 Philips cams will use /dev/video4
0177 through /dev/video6.
0178
0179 Some points worth knowing:
0180
0181 - Serialnumbers are case sensitive and must be written full, including
0182 leading zeroes (it's treated as a string).
0183 - If a device node is already occupied, registration will fail and
0184 the webcam is not available.
0185 - You can have up to 64 video devices; be sure to make enough device
0186 nodes in /dev if you want to spread the numbers.
0187 After /dev/video9 comes /dev/video10 (not /dev/videoA).
0188 - If a camera does not match any dev_hint, it will simply get assigned
0189 the first available device node, just as it used to be.
0190
0191 trace
0192 In order to better detect problems, it is now possible to turn on a
0193 'trace' of some of the calls the module makes; it logs all items in your
0194 kernel log at debug level.
0195
0196 The trace variable is a bitmask; each bit represents a certain feature.
0197 If you want to trace something, look up the bit value(s) in the table
0198 below, add the values together and supply that to the trace variable.
0199
0200 ====== ======= ================================================ =======
0201 Value Value Description Default
0202 (dec) (hex)
0203 ====== ======= ================================================ =======
0204 1 0x1 Module initialization; this will log messages On
0205 while loading and unloading the module
0206
0207 2 0x2 probe() and disconnect() traces On
0208
0209 4 0x4 Trace open() and close() calls Off
0210
0211 8 0x8 read(), mmap() and associated ioctl() calls Off
0212
0213 16 0x10 Memory allocation of buffers, etc. Off
0214
0215 32 0x20 Showing underflow, overflow and Dumping frame On
0216 messages
0217
0218 64 0x40 Show viewport and image sizes Off
0219
0220 128 0x80 PWCX debugging Off
0221 ====== ======= ================================================ =======
0222
0223 For example, to trace the open() & read() functions, sum 8 + 4 = 12,
0224 so you would supply trace=12 during insmod or modprobe. If
0225 you want to turn the initialization and probing tracing off, set trace=0.
0226 The default value for trace is 35 (0x23).
0227
0228
0229
0230 Example::
0231
0232 # modprobe pwc size=cif fps=15 power_save=1
0233
0234 The fbufs, mbufs and trace parameters are global and apply to all connected
0235 cameras. Each camera has its own set of buffers.
0236
0237 size and fps only specify defaults when you open() the device; this is to
0238 accommodate some tools that don't set the size. You can change these
0239 settings after open() with the Video4Linux ioctl() calls. The default of
0240 defaults is QCIF size at 10 fps.
0241
0242 The compression parameter is semiglobal; it sets the initial compression
0243 preference for all camera's, but this parameter can be set per camera with
0244 the VIDIOCPWCSCQUAL ioctl() call.
0245
0246 All parameters are optional.
0247
