Documentation/usb/ov511.txt

   1 -------------------------------------------------------------------------------
   2 Readme for Linux device driver for the OmniVision OV511 USB to camera bridge IC
   3 -------------------------------------------------------------------------------
   4
   5 Author: Mark McClelland
   6 Homepage: http://alpha.dyndns.org/ov511
   7
   8 INTRODUCTION:
   9
  10 This is a driver for the OV511, a USB-only chip used in many "webcam" devices.
  11 Any camera using the OV511/OV511+ and the OV6620/OV7610/20/20AE should work.
  12 Video capture devices that use the Philips SAA7111A decoder also work. It
  13 supports streaming and capture of color or monochrome video via the Video4Linux
  14 API. Most V4L apps are compatible with it. Most resolutions with a width and
  15 height that are a multiple of 8 are supported.
  16
  17 If you need more information, please visit the OV511 homepage at the above URL.
  18
  19 WHAT YOU NEED:
  20
  21 - If you want to help with the development, get the chip's specification docs at
  22   http://www.ovt.com/omniusbp.html
  23
  24 - A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv)
  25     vidcat is part of the w3cam package:  http://www.hdk-berlin.de/~rasca/w3cam/
  26     xawtv is available at:  http://www.in-berlin.de/User/kraxel/xawtv.html
  27
  28 HOW TO USE IT:
  29
  30 Note: These are simplified instructions. For complete instructions see:
  31         http://alpha.dyndns.org/ov511/install.html
  32
  33 You must have first compiled USB support, support for your specific USB host
  34 controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend
  35 making them modules.) Make sure "Enforce bandwidth allocation" is NOT enabled.
  36
  37 Next, (as root):
  38
  39         modprobe usbcore
  40         modprobe usb-uhci  <OR>  modprobe usb-ohci
  41         modprobe videodev
  42         modprobe ov511
  43
  44 If it is not already there (it usually is), create the video device:
  45
  46         mknod /dev/video0 c 81 0
  47
  48 Optionally, symlink /dev/video to /dev/video0
  49
  50 You will have to set permissions on this device to allow you to read/write
  51 from it:
  52
  53         chmod 666 /dev/video
  54         chmod 666 /dev/video0 (if necessary)
  55
  56 Now you are ready to run a video app! Both vidcat and xawtv work well for me
  57 at 640x480.
  58
  59 [Using vidcat:]
  60
  61         vidcat -s 640x480 -p c > test.jpg
  62         xview test.jpg
  63
  64 [Using xawtv:]
  65
  66 From the main xawtv directory:
  67
  68         make clean
  69         ./configure
  70         make
  71         make install
  72
  73 Now you should be able to run xawtv. Right click for the options dialog.
  74
  75 MODULE PARAMETERS:
  76
  77   You can set these with:  insmod ov511 NAME=VALUE
  78   There is currently no way to set these on a per-camera basis.
  79
  80   NAME: autobright
  81   TYPE: integer (Boolean)
  82   DEFAULT: 1
  83   DESC: Brightness is normally under automatic control and can't be set
  84         manually by the video app. Set to 0 for manual control.
  85
  86   NAME: autogain
  87   TYPE: integer (Boolean)
  88   DEFAULT: 1
  89   DESC: Auto Gain Control enable. This feature is not yet implemented.
  90
  91   NAME: autoexp
  92   TYPE: integer (Boolean)
  93   DEFAULT: 1
  94   DESC: Auto Exposure Control enable. This feature is not yet implemented.
  95
  96   NAME: debug
  97   TYPE: integer (0-6)
  98   DEFAULT: 3
  99   DESC: Sets the threshold for printing debug messages. The higher the value,
 100         the more is printed. The levels are cumulative, and are as follows:
 101           0=no debug messages
 102           1=init/detection/unload and other significant messages
 103           2=some warning messages
 104           3=config/control function calls
 105           4=most function calls and data parsing messages
 106           5=highly repetitive mesgs
 107
 108   NAME: snapshot
 109   TYPE: integer (Boolean)
 110   DEFAULT: 0
 111   DESC: Set to 1 to enable snapshot mode. read()/VIDIOCSYNC will block until
 112         the snapshot button is pressed. Note: enabling this mode disables
 113         /proc/video/ov511/<minor#>/button
 114
 115   NAME: cams
 116   TYPE: integer (1-4 for OV511, 1-31 for OV511+)
 117   DEFAULT: 1
 118   DESC: Number of cameras allowed to stream simultaneously on a single bus.
 119         Values higher than 1 reduce the data rate of each camera, allowing two
 120         or more to be used at once. If you have a complicated setup involving
 121         both OV511 and OV511+ cameras, trial-and-error may be necessary for
 122         finding the optimum setting.
 123
 124   NAME: compress
 125   TYPE: integer (Boolean)
 126   DEFAULT: 0
 127   DESC: Set this to 1 to turn on the camera's compression engine. This can
 128         potentially increase the frame rate at the expense of quality, if you
 129         have a fast CPU. You must load the proper compression module for your
 130         camera before starting your application (ov511_decomp or ov518_decomp).
 131
 132   NAME: testpat
 133   TYPE: integer (Boolean)
 134   DEFAULT: 0
 135   DESC: This configures the camera's sensor to transmit a colored test-pattern
 136         instead of an image. This does not work correctly yet.
 137
 138   NAME: dumppix
 139   TYPE: integer (0-2)
 140   DEFAULT: 0
 141   DESC: Dumps raw pixel data and skips post-processing and format conversion.
 142         It is for debugging purposes only. Options are:
 143                 0: Disable (default)
 144                 1: Dump raw data from camera, excluding headers and trailers
 145                 2: Dumps data exactly as received from camera
 146
 147   NAME: led
 148   TYPE: integer (0-2)
 149   DEFAULT: 1 (Always on)
 150   DESC: Controls whether the LED (the little light) on the front of the camera
 151         is always off (0), always on (1), or only on when driver is open (2).
 152         This is not supported with the OV511, and might only work with certain
 153         cameras (ones that actually have the LED wired to the control pin, and
 154         not just hard-wired to be on all the time).
 155
 156   NAME: dump_bridge
 157   TYPE: integer (Boolean)
 158   DEFAULT: 0
 159   DESC: Dumps the bridge (OV511[+] or OV518[+]) register values to the system
 160         log. Only useful for serious debugging/development purposes.
 161
 162   NAME: dump_sensor
 163   TYPE: integer (Boolean)
 164   DEFAULT: 0
 165   DESC: Dumps the sensor register values to the system log. Only useful for
 166         serious debugging/development purposes.
 167
 168   NAME: printph
 169   TYPE: integer (Boolean)
 170   DEFAULT: 0
 171   DESC: Setting this to 1 will dump the first 12 bytes of each isoc frame. This
 172         is only useful if you are trying to debug problems with the isoc data
 173         stream (i.e.: camera initializes, but vidcat hangs until Ctrl-C). Be
 174         warned that this dumps a large number of messages to your kernel log.
 175
 176   NAME: phy, phuv, pvy, pvuv, qhy, qhuv, qvy, qvuv
 177   TYPE: integer (0-63 for phy and phuv, 0-255 for rest)
 178   DEFAULT: OV511 default values
 179   DESC: These are registers 70h - 77h of the OV511, which control the
 180         prediction ranges and quantization thresholds of the compressor, for
 181         the Y and UV channels in the horizontal and vertical directions. See
 182         the OV511 or OV511+ data sheet for more detailed descriptions. These
 183         normally do not need to be changed.
 184
 185   NAME: lightfreq
 186   TYPE: integer (0, 50, or 60)
 187   DEFAULT: 0 (use sensor default)
 188   DESC: Sets the sensor to match your lighting frequency. This can reduce the
 189         appearance of "banding", i.e. horizontal lines or waves of light and
 190         dark that are often caused by artificial lighting. Valid values are:
 191                 0 - Use default (depends on sensor, most likely 60 Hz)
 192                 50 - For European and Asian 50 Hz power
 193                 60 - For American 60 Hz power
 194
 195   NAME: bandingfilter
 196   TYPE: integer (Boolean)
 197   DEFAULT: 0 (off)
 198   DESC: Enables the sensor´s banding filter exposure algorithm. This reduces
 199         or stabilizes the "banding" caused by some artificial light sources
 200         (especially fluorescent). You might have to set lightfreq correctly for
 201         this to work right. As an added bonus, this sometimes makes it
 202         possible to capture your monitor´s output.
 203
 204   NAME: fastset
 205   TYPE: integer (Boolean)
 206   DEFAULT: 0 (off)
 207   DESC: Allows picture settings (brightness, contrast, color, and hue) to take
 208         effect immediately, even in the middle of a frame. This reduces the
 209         time to change settings, but can ruin frames during the change. Only
 210         affects OmniVision sensors.
 211
 212   NAME: force_palette
 213   TYPE: integer (Boolean)
 214   DEFAULT: 0 (off)
 215   DESC: Forces the palette (color format) to a specific value. If an
 216         application requests a different palette, it will be rejected, thereby
 217         forcing it to try others until it succeeds. This is useful for forcing
 218         greyscale mode with a color camera, for example. Supported modes are:
 219                 0                           (Allows all the following formats)
 220                 1   VIDEO_PALETTE_GREY      (Linear greyscale)
 221                 10  VIDEO_PALETTE_YUV420    (YUV 4:2:0 Planar)
 222                 15  VIDEO_PALETTE_YUV420P   (YUV 4:2:0 Planar, same as 10)
 223
 224   NAME: backlight
 225   TYPE: integer (Boolean)
 226   DEFAULT: 0 (off)
 227   DESC: Setting this flag changes the exposure algorithm for OmniVision sensors
 228         such that objects in the camera's view (i.e. your head) can be clearly
 229         seen when they are illuminated from behind. It reduces or eliminates
 230         the sensor's auto-exposure function, so it should only be used when
 231         needed. Additionally, it is only supported with the OV6620 and OV7620.
 232
 233   NAME: unit_video
 234   TYPE: Up to 16 comma-separated integers
 235   DEFAULT: 0,0,0... (automatically assign the next available minor(s))
 236   DESC: You can specify up to 16 minor numbers to be assigned to ov511 devices.
 237         For example, "unit_video=1,3" will make the driver use /dev/video1 and
 238         /dev/video3 for the first two devices it detects. Additional devices
 239         will be assigned automatically starting at the first available device
 240         node (/dev/video0 in this case). Note that you cannot specify 0 as a
 241         minor number. This feature requires kernel version 2.4.5 or higher.
 242
 243   NAME: remove_zeros
 244   TYPE: integer (Boolean)
 245   DEFAULT: 0 (do not skip any incoming data)
 246   DESC: Setting this to 1 will remove zero-padding from incoming data. This
 247         will compensate for the blocks of corruption that can appear when the
 248         camera cannot keep up with the speed of the USB bus (eg. at low frame
 249         resolutions). This feature is always enabled when compression is on.
 250
 251   NAME: mirror
 252   TYPE: integer (Boolean)
 253   DEFAULT: 0 (off)
 254   DESC: Setting this to 1 will reverse ("mirror") the image horizontally. This
 255         might be necessary if your camera has a custom lens assembly. This has
 256         no effect with video capture devices.
 257
 258   NAME: ov518_color
 259   TYPE: integer (Boolean)
 260   DEFAULT: 0 (off)
 261   DESC: Enable OV518 color support. This is off by default since it doesn't
 262         work most of the time. If you want to try it, you must also load
 263         ov518_decomp with the "nouv=0" parameter. If you get improper colors or
 264         diagonal lines through the image, restart your video app and try again.
 265         Repeat as necessary.
 266
 267 WORKING FEATURES:
 268  o Color streaming/capture at most widths and heights that are multiples of 8.
 269  o Monochrome (use force_palette=1 to enable)
 270  o Setting/getting of saturation, contrast, brightness, and hue (only some of
 271    them work the OV7620 and OV7620AE)
 272  o /proc status reporting
 273  o SAA7111A video capture support at 320x240 and 640x480
 274  o Compression support
 275  o SMP compatibility
 276
 277 HOW TO CONTACT ME:
 278
 279 You can email me at mark@alpha.dyndns.org . Please prefix the subject line
 280 with "OV511: " so that I am certain to notice your message.
 281
 282 CREDITS:
 283
 284 The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 285 Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 286 and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and
 287 image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio
 288 Matsuoka for their work as well.
 289