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 NEW IN THIS VERSION:
   9  o Race conditions and other bugs fixed
  10
  11 INTRODUCTION:
  12
  13 This is a driver for the OV511, a USB-only chip used in many "webcam" devices.
  14 Any camera using the OV511/OV511+ and the OV7610/20/20AE CCD should work.It
  15 supports streaming and capture of color or monochrome video via the Video4Linux
  16 API. Most V4L apps are compatible with it, but a few videoconferencing programs
  17 do not work yet. The following resolutions are supported: 640x480, 448x336,
  18 384x288, 352x288, and 320x240.
  19
  20 WHAT YOU NEED:
  21
  22 - If you want to help with the development, get the chip's specification docs at
  23   http://www.ovt.com/omniusbp.html
  24
  25 - A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv)
  26     vidcat is part of the w3cam package:  http://www.hdk-berlin.de/~rasca/w3cam/
  27     xawtv is available at:  http://www.in-berlin.de/User/kraxel/xawtv.html
  28
  29 HOW TO USE IT:
  30
  31 You must have first compiled USB support, support for your specific USB host
  32 controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend
  33 making them modules.)
  34
  35 Next, (as root) from your appropriate modules directory (lib/modules/2.3.XX):
  36
  37         insmod usb/usbcore.o
  38         insmod usb/usb-uhci.o  <OR>  insmod usb/ohci-hcd.o
  39         insmod misc/videodev.o
  40         insmod usb/ov511.o
  41
  42 If it is not already there (it usually is), create the video device:
  43
  44         mknod /dev/video c 81 0
  45
  46 Sometimes /dev/video is a symlink to /dev/video0
  47
  48 You will have to set permissions on this device to allow you to read/write
  49 from it:
  50
  51         chmod 666 /dev/video
  52         chmod 666 /dev/video0 (if necessary)
  53
  54 Now you are ready to run a video app! Both vidcat and xawtv work well for me
  55 at 640x480.
  56
  57 [Using vidcat:]
  58
  59         vidcat -s 640x480 > test.jpg
  60         xview test.jpg
  61
  62 [Using xawtv:]
  63
  64 You must make some modifications to the source and compile it before you use it.
  65 (Note: this may not be applicable to versions other than 3.06)
  66
  67 In src/Xawtv.ad, change xawtv.tv.width to 640 and xawtv.tv.height to 480. Next,
  68 in src/grab-v4l.c, change SYNC_TIMEOUT from 1 to 2. Then, from the main xawtv
  69 directory:
  70
  71         make clean
  72         ./configure
  73         make
  74         make install
  75
  76 Now you should be able to run xawtv. Right click for the options dialog. If
  77 you get a scrambled image it is likely that you made a mistake in Xawtv.ad.
  78 Try setting the size to 320x240 if all else fails.
  79
  80 FAQ:
  81 Q: "Why does the picture have noise and look grainy"
  82 A: This is a problem at low light levels, and may be also due to subtle bugs in
  83    the code. The cause is most likely the OV7610 settings we are currently
  84    using. I am looking into this problem.
  85
  86 Q: "The driver sometimes says `Failed to read OV7610 ID.' What is the deal?"
  87 A: The I2C code that allows the OV511 to communicate with the camera chip is a
  88    bit flaky right now. This message means that the I2C bus never got
  89    initialized properly, and the camera will most likely not work even if you
  90    disable this warning. Try unloading/reloading the driver or unplugging/re-
  91    plugging the camera if this happens. Also try increasing the i2c_detect_tries
  92    parameter (see below).
  93
  94 Q: "Why do you bother with this phony camera detection crap? It doesn't do
  95     anything useful!"
  96 A: The main purpose of only supporting known camera models is to force people
  97    with new camera models to tell me about them, so I can assemble the list
  98    above, and so the code can know what CCD chip you have. Right now, nearly all
  99    of the cameras use the OV7610 and consequently I have not put support for
 100    other ones in, so the value of the detection code is questionable. Eventually
 101    though, new CCDs might appear and we will be fortunate to have the detection.
 102
 103 MODULE PARAMETERS:
 104
 105   You can set these with:  insmod ov511 NAME=VALUE
 106   There is currently no way to set these on a per-camera basis.
 107
 108   NAME: autoadjust
 109   TYPE: integer (boolean)
 110   DEFAULT: 1
 111   DESC: The camera normally adjusts exposure, gain, and hue automatically. This
 112         can be set to 0 to disable this automatic adjustment. Note that there is
 113         currently no way to set these parameters manually once autoadjust is
 114         disabled.
 115
 116   NAME: debug
 117   TYPE: integer (0-6)
 118   DEFAULT: 3
 119   DESC: Sets the threshold for printing debug messages. The higher the value,
 120         the more is printed. The levels are cumulative, and are as follows:
 121           0=no debug messages
 122           1=init/detection/unload and other significant messages
 123           2=some warning messages
 124           3=config/control function calls
 125           4=most function calls and data parsing messages
 126           5=highly repetitive mesgs
 127
 128   NAME: fix_rgb_offset
 129   TYPE: integer (boolean)
 130   DEFAULT: 0
 131   DESC: Some people have reported that the blue component of the image is one
 132         or so lines higher than the red component. This is only apparent in
 133         images with white objects on black backgrounds at 640x480. Setting this
 134         to 1 will realign the color planes correctly. NOTE: This is still
 135         experimental and very buggy. You will likely need a fast (500 Mhz) CPU.
 136
 137   NAME: snapshot
 138   TYPE: integer (boolean)
 139   DEFAULT: 0
 140   DESC: Set to 1 to enable snapshot mode. read() will block until the snapshot
 141         button is pressed. Note that this does not yet work with most apps,
 142         including xawtv and vidcat. NOTE: See the section "TODO" for more info.
 143
 144   NAME: sensor
 145   TYPE: integer ([0, 1, 3])
 146   DEFAULT: [varies]
 147   DESC: If you know that your camera sensor is not detected correctly, set this
 148         parameter. This is a global option for all attached OV511 cameras. You
 149         will probably never need to set this, but if you do, valid values are:
 150                 0 for OV7620
 151                 1 for OV7620AE
 152                 3 for OV7610
 153
 154   NAME: i2c_detect_tries
 155   TYPE: integer (don't set it insanely high!)
 156   DEFAULT: 5
 157   DESC: This is the number of times the driver will try to sync and detect the
 158         internal i2c bus (which connects the OV511 and sensor). If you are
 159         getting intermittant detection failures ("Failed to read sensor ID...")
 160         you should increase this by a modest amount. If setting it to 20 or so
 161         doesn't fix things, look elsewhere for the cause of the problem.
 162
 163   NAME: aperture
 164   TYPE: integer (0 - 15)
 165   DEFAULT: [varies by sensor]
 166   DESC: For legal values, see the OV7610/7620 specs under register Common F.
 167         This setting affects the upper nybble of that reg (bits 4-7). This is
 168         for if you want to play with the camera's pixel saturation.
 169
 170   NAME: force_rgb
 171   TYPE: integer (boolean)
 172   DEFAULT: 0
 173   DESC: Force image to be read in RGB instead of BGR. This option allow
 174         programs that expect RGB data (e.g. gqcam) to work with this driver. If
 175         your colors look VERY wrong, you may want to change this.
 176
 177 WORKING FEATURES:
 178  o Color streaming/capture at 640x480, 448x336, 384x288, 352x288, and 320x240
 179  o YUV420 color
 180  o Monochrome
 181  o Setting/getting of saturation, contrast and brightness (no hue yet; only
 182    works with OV7610, not the OV7620 or OV7620AE)
 183  o proc status reporting
 184
 185 EXPERIMENTAL FEATURES:
 186  o fix_rgb_offset: Sometimes works, but other times causes errors with xawtv and
 187    corrupted frames. If you have a very fast CPU, you can try it.
 188  o Snapshot mode (only works with some read() based apps; see below for more)
 189  o read() support
 190
 191 TODO:
 192  o Fix the noise / grainy image problem.
 193  o Get compression working. It would be a nice addition as it improves
 194    frame rate quite a bit. OmniVision wouldn't tell me how the algorithm works,
 195    so we can't really work on that yet. Please kindly inform OmniVision that you
 196    would like them to release their specifications to the Linux community.
 197  o Get 160x120 working
 198  o YUV422 (and other color modes)
 199  o Get snapshot mode working with mmap().
 200  o Fix fixFrameRGBoffset(). It is not stable yet with streaming video.
 201  o Get hue (red/blue channel balance) adjustment working (in ov511_get_picture()
 202    and ov511_set_picture())
 203  o Get autoadjust disable working
 204  o V4L2 support (Probably not until it goes into the kernel)
 205  o Fix I2C initialization. Some people are reporting problems with reading the
 206    7610 registers. This could be due to timing differences, an excessive I2C
 207    clock rate, or a problem with ov511_i2c_read().
 208  o Get rid of the memory management functions (put them in videodev.c??)
 209  o Setting of contrast and brightness not working with 7620
 210  o Driver/camera state save/restore for when USB supports suspend/resume
 211  o Multiple cameras reportedly do not work simultaneously
 212  o Problems with OHCI
 213
 214 HOW TO CONTACT ME:
 215
 216 You can email me at mmcclelland@delphi.com . Please prefix the subject line
 217 with "OV511: " so that I am certain to notice your message.
 218
 219 CREDITS:
 220
 221 The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 222 Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 223 and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and
 224 image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio
 225 Matsuoka for their work as well.