Documentation/usb/philips.txt

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