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: fix_rgb_offset
 109   TYPE: integer (Boolean)
 110   DEFAULT: 0
 111   DESC: Some people have reported that the blue component of the image is one
 112         or so lines higher than the red component. This is only apparent in
 113         images with white objects on black backgrounds at 640x480. Setting this
 114         to 1 will realign the color planes correctly. NOTE: You will likely
 115         need a fast (500 MHz) CPU.
 116
 117   NAME: snapshot
 118   TYPE: integer (Boolean)
 119   DEFAULT: 0
 120   DESC: Set to 1 to enable snapshot mode. read()/VIDIOCSYNC will block until
 121         the snapshot button is pressed. Note: enabling this mode disables
 122         /proc/video/ov511/<minor#>/button
 123
 124   NAME: force_rgb       (Deprecated; may be removed in the future)
 125   TYPE: integer (Boolean)
 126   DEFAULT: 0
 127   DESC: Force image to be read in RGB instead of BGR. This option allow
 128         programs that expect RGB data (e.g. gqcam) to work with this driver. If
 129         your colors look VERY wrong, you may want to change this.
 130
 131   NAME: cams
 132   TYPE: integer (1-4 for OV511, 1-31 for OV511+)
 133   DEFAULT: 1
 134   DESC: Number of cameras allowed to stream simultaneously on a single bus.
 135         Values higher than 1 reduce the data rate of each camera, allowing two
 136         or more to be used at once. If you have a complicated setup involving
 137         both OV511 and OV511+ cameras, trial-and-error may be necessary for
 138         finding the optimum setting.
 139
 140   NAME: compress
 141   TYPE: integer (Boolean)
 142   DEFAULT: 0
 143   DESC: Set this to 1 to turn on the camera's compression engine. This can
 144         potentially increase the frame rate at the expense of quality, if you
 145         have a fast CPU. You must load the proper compression module for your
 146         camera before starting your application (ov511_decomp or ov518_decomp).
 147
 148   NAME: testpat
 149   TYPE: integer (Boolean)
 150   DEFAULT: 0
 151   DESC: This configures the camera's sensor to transmit a colored test-pattern
 152         instead of an image. This does not work correctly yet.
 153
 154   NAME: dumppix
 155   TYPE: integer (0-2)
 156   DEFAULT: 0
 157   DESC: Dumps raw pixel data and skips post-processing and format conversion.
 158         It is for debugging purposes only. Options are:
 159                 0: Disable (default)
 160                 1: Dump raw data from camera, excluding headers and trailers
 161                 2: Dumps data exactly as received from camera
 162
 163   NAME: led
 164   TYPE: integer (0-2)
 165   DEFAULT: 1 (Always on)
 166   DESC: Controls whether the LED (the little light) on the front of the camera
 167         is always off (0), always on (1), or only on when driver is open (2).
 168         This is not supported with the OV511, and might only work with certain
 169         cameras (ones that actually have the LED wired to the control pin, and
 170         not just hard-wired to be on all the time).
 171
 172   NAME: dump_bridge
 173   TYPE: integer (Boolean)
 174   DEFAULT: 0
 175   DESC: Dumps the bridge (OV511[+] or OV518[+]) register values to the system
 176         log. Only useful for serious debugging/development purposes.
 177
 178   NAME: dump_sensor
 179   TYPE: integer (Boolean)
 180   DEFAULT: 0
 181   DESC: Dumps the sensor register values to the system log. Only useful for
 182         serious debugging/development purposes.
 183
 184   NAME: printph
 185   TYPE: integer (Boolean)
 186   DEFAULT: 0
 187   DESC: Setting this to 1 will dump the first 12 bytes of each isoc frame. This
 188         is only useful if you are trying to debug problems with the isoc data
 189         stream (i.e.: camera initializes, but vidcat hangs until Ctrl-C). Be
 190         warned that this dumps a large number of messages to your kernel log.
 191
 192   NAME: phy, phuv, pvy, pvuv, qhy, qhuv, qvy, qvuv
 193   TYPE: integer (0-63 for phy and phuv, 0-255 for rest)
 194   DEFAULT: OV511 default values
 195   DESC: These are registers 70h - 77h of the OV511, which control the
 196         prediction ranges and quantization thresholds of the compressor, for
 197         the Y and UV channels in the horizontal and vertical directions. See
 198         the OV511 or OV511+ data sheet for more detailed descriptions. These
 199         normally do not need to be changed.
 200
 201   NAME: lightfreq
 202   TYPE: integer (0, 50, or 60)
 203   DEFAULT: 0 (use sensor default)
 204   DESC: Sets the sensor to match your lighting frequency. This can reduce the
 205         appearance of "banding", i.e. horizontal lines or waves of light and
 206         dark that are often caused by artificial lighting. Valid values are:
 207                 0 - Use default (depends on sensor, most likely 60 Hz)
 208                 50 - For European and Asian 50 Hz power
 209                 60 - For American 60 Hz power
 210
 211   NAME: bandingfilter
 212   TYPE: integer (Boolean)
 213   DEFAULT: 0 (off)
 214   DESC: Enables the sensor´s banding filter exposure algorithm. This reduces
 215         or stabilizes the "banding" caused by some artificial light sources
 216         (especially fluorescent). You might have to set lightfreq correctly for
 217         this to work right. As an added bonus, this sometimes makes it
 218         possible to capture your monitor´s output.
 219
 220   NAME: fastset
 221   TYPE: integer (Boolean)
 222   DEFAULT: 0 (off)
 223   DESC: Allows picture settings (brightness, contrast, color, and hue) to take
 224         effect immediately, even in the middle of a frame. This reduces the
 225         time to change settings, but can ruin frames during the change. Only
 226         affects OmniVision sensors.
 227
 228   NAME: force_palette
 229   TYPE: integer (Boolean)
 230   DEFAULT: 0 (off)
 231   DESC: Forces the palette (color format) to a specific value. If an
 232         application requests a different palette, it will be rejected, thereby
 233         forcing it to try others until it succeeds. This is useful for forcing
 234         greyscale mode with a color camera, for example. Supported modes are:
 235                 0                           (Allows all the following formats)
 236                 1   VIDEO_PALETTE_GREY      (Linear greyscale)
 237                 3   VIDEO_PALETTE_RGB565    (565 16 bit RGB)
 238                 4   VIDEO_PALETTE_RGB24     (24bit RGB)
 239                 7   VIDEO_PALETTE_YUV422    (YUV422 capture)
 240                 8   VIDEO_PALETTE_YUYV      (YUV422 capture; same as 7)
 241                 10  VIDEO_PALETTE_YUV420    (YUV 4:2:0 Planar)
 242                 13  VIDEO_PALETTE_YUV422P   (YUV 4:2:2 Planar)
 243                 15  VIDEO_PALETTE_YUV420P   (YUV 4:2:0 Planar, same as 10)
 244
 245   NAME: backlight
 246   TYPE: integer (Boolean)
 247   DEFAULT: 0 (off)
 248   DESC: Setting this flag changes the exposure algorithm for OmniVision sensors
 249         such that objects in the camera's view (i.e. your head) can be clearly
 250         seen when they are illuminated from behind. It reduces or eliminates
 251         the sensor's auto-exposure function, so it should only be used when
 252         needed. Additionally, it is only supported with the OV6620 and OV7620.
 253
 254   NAME: unit_video
 255   TYPE: Up to 16 comma-separated integers
 256   DEFAULT: 0,0,0... (automatically assign the next available minor(s))
 257   DESC: You can specify up to 16 minor numbers to be assigned to ov511 devices.
 258         For example, "unit_video=1,3" will make the driver use /dev/video1 and
 259         /dev/video3 for the first two devices it detects. Additional devices
 260         will be assigned automatically starting at the first available device
 261         node (/dev/video0 in this case). Note that you cannot specify 0 as a
 262         minor number. This feature requires kernel version 2.4.5 or higher.
 263
 264   NAME: remove_zeros
 265   TYPE: integer (Boolean)
 266   DEFAULT: 0 (do not skip any incoming data)
 267   DESC: Setting this to 1 will remove zero-padding from incoming data. This
 268         will compensate for the blocks of corruption that can appear when the
 269         camera cannot keep up with the speed of the USB bus (eg. at low frame
 270         resolutions). This feature is always enabled when compression is on.
 271
 272   NAME: mirror
 273   TYPE: integer (Boolean)
 274   DEFAULT: 0 (off)
 275   DESC: Setting this to 1 will reverse ("mirror") the image horizontally. This
 276         might be necessary if your camera has a custom lens assembly. This has
 277         no effect with video capture devices.
 278
 279   NAME: ov518_color
 280   TYPE: integer (Boolean)
 281   DEFAULT: 0 (off)
 282   DESC: Enable OV518 color support. This is off by default since it doesn't
 283         work most of the time. If you want to try it, you must also load
 284         ov518_decomp with the "nouv=0" parameter. If you get improper colors or
 285         diagonal lines through the image, restart your video app and try again.
 286         Repeat as necessary.
 287
 288 WORKING FEATURES:
 289  o Color streaming/capture at most widths and heights that are multiples of 8.
 290  o RGB24, RGB565, YUV420/YUV420P, YUV422/YUYV, and YUV422P color
 291  o Monochrome (use force_palette=1 to enable)
 292  o Setting/getting of saturation, contrast, brightness, and hue (only some of
 293    them work the OV7620 and OV7620AE)
 294  o /proc status reporting
 295  o SAA7111A video capture support at 320x240 and 640x480
 296  o Compression support
 297  o SMP compatibility
 298
 299 HOW TO CONTACT ME:
 300
 301 You can email me at mark@alpha.dyndns.org . Please prefix the subject line
 302 with "OV511: " so that I am certain to notice your message.
 303
 304 CREDITS:
 305
 306 The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 307 Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 308 and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and
 309 image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio
 310 Matsuoka for their work as well.
 311