linux/Documentation/video4linux/ov511.txt
<<
>>
Prefs
   1-------------------------------------------------------------------------------
   2Readme for Linux device driver for the OmniVision OV511 USB to camera bridge IC
   3-------------------------------------------------------------------------------
   4
   5Author: Mark McClelland
   6Homepage: http://alpha.dyndns.org/ov511
   7
   8INTRODUCTION:
   9
  10This is a driver for the OV511, a USB-only chip used in many "webcam" devices.
  11Any camera using the OV511/OV511+ and the OV6620/OV7610/20/20AE should work.
  12Video capture devices that use the Philips SAA7111A decoder also work. It
  13supports streaming and capture of color or monochrome video via the Video4Linux
  14API. Most V4L apps are compatible with it. Most resolutions with a width and
  15height that are a multiple of 8 are supported.
  16
  17If you need more information, please visit the OV511 homepage at the above URL.
  18
  19WHAT 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://mpx.freeshell.net/
  26    xawtv is available at:  http://linux.bytesex.org/xawtv/
  27
  28HOW TO USE IT:
  29
  30Note: These are simplified instructions. For complete instructions see:
  31        http://alpha.dyndns.org/ov511/install.html
  32
  33You must have first compiled USB support, support for your specific USB host
  34controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend
  35making them modules.) Make sure "Enforce bandwidth allocation" is NOT enabled.
  36
  37Next, (as root):
  38
  39        modprobe usbcore
  40        modprobe usb-uhci  <OR>  modprobe usb-ohci
  41        modprobe videodev
  42        modprobe ov511
  43
  44If it is not already there (it usually is), create the video device:
  45
  46        mknod /dev/video0 c 81 0
  47
  48Optionally, symlink /dev/video to /dev/video0
  49
  50You will have to set permissions on this device to allow you to read/write
  51from it:
  52
  53        chmod 666 /dev/video
  54        chmod 666 /dev/video0 (if necessary)
  55
  56Now you are ready to run a video app! Both vidcat and xawtv work well for me
  57at 640x480.
  58
  59[Using vidcat:]
  60
  61        vidcat -s 640x480 -p c > test.jpg
  62        xview test.jpg
  63
  64[Using xawtv:]
  65
  66From the main xawtv directory:
  67
  68        make clean
  69        ./configure
  70        make
  71        make install
  72
  73Now you should be able to run xawtv. Right click for the options dialog.
  74
  75MODULE 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
 267WORKING 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
 277HOW TO CONTACT ME:
 278
 279You can email me at mark@alpha.dyndns.org . Please prefix the subject line
 280with "OV511: " so that I am certain to notice your message.
 281
 282CREDITS:
 283
 284The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 285Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 286and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and
 287image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio
 288Matsuoka for their work as well.
 289
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.