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 preliminary version of my OV511 Linux device driver. Currently, it can
  11 grab a frame in color (YUV420) at 640x480 or 320x240 using either vidcat or
  12 xawtv. Other utilities may work but have not yet been tested.
  13
  14 NEW IN THIS VERSION:
  15  o Preliminary snapshot support
  16  o Experimental red-blue misalignment fixes
  17  o Better YUV420 color conversion
  18  o Module options
  19  o Finer-grained debug message control
  20  o Support for new cameras (4, 36)
  21  o Uses initcalls
  22
  23 SUPPORTED CAMERAS:
  24 _________________________________________________________
  25 Manufacturer     | Model           | Custom ID | Status
  26 -----------------+-----------------+-----------+---------
  27 MediaForte       | MV300           | 0         | Working
  28 Aiptek           | HyperVCam ?     | 0         | Working
  29 NetView          | NV300M          | 0         | Working
  30 D-Link           | DSB-C300        | 3         | Working
  31 Hawking Tech.    | ???             | 3         | Working
  32 ???              | Generic         | 4         | Untested
  33 Puretek          | PT-6007         | 5         | Working
  34 Creative Labs    | WebCam 3        | 21        | Working
  35 ???              | Koala-Cam       | 36        | Untested
  36 Lifeview         | RoboCam         | 100       | Untested
  37 AverMedia        | InterCam Elite  | 102       | Working
  38 MediaForte       | MV300           | 112       | Working
  39 Omnivision       | OV7110 EV board | 112       | Working*
  40 ---------------------------------------------------------
  41 (*) uses OV7110 (monochrome)
  42
  43 Any camera using the OV511 and the OV7610 CCD should work with this driver. The
  44 driver only detects known cameras though, based on their custom id number. If
  45 you have a currently unsupported camera, the ID number should be reported to you
  46 in the kernel logs. Please send me the model, manufacturer and ID number and I
  47 will add it to the detection code. In the meantime, you can add to the code
  48 yourself in the function ov511_probe().
  49
  50 WHAT YOU NEED:
  51
  52 - If you want to help with the development, get the chip's specification docs at
  53   http://www.ovt.com/omniusbp.html
  54
  55 - A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv)
  56     vidcat is part of the w3cam package:  http://www.hdk-berlin.de/~rasca/w3cam/
  57     xawtv is available at:  http://www.in-berlin.de/User/kraxel/xawtv.html
  58
  59 HOW TO USE IT:
  60
  61 You must have first compiled USB support, support for your specific USB host
  62 controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend
  63 making them modules.)
  64
  65 Next, (as root) from your appropriate modules directory (lib/modules/2.3.XX):
  66
  67         insmod usb/usbcore.o
  68         insmod usb/usb-uhci.o  <OR>  insmod usb/ohci-hcd.o
  69         insmod misc/videodev.o
  70         insmod usb/ov511.o
  71
  72 If it is not already there (it usually is), create the video device:
  73
  74         mknod /dev/video c 81 0
  75
  76 Sometimes /dev/video is a symlink to /dev/video0
  77
  78 You will have to set permissions on this device to allow you to read/write
  79 from it:
  80
  81         chmod 666 /dev/video
  82         chmod 666 /dev/video0 (if necessary)
  83
  84 Now you are ready to run a video app! Both vidcat and xawtv work well for me
  85 at 640x480.
  86
  87 [Using vidcat:]
  88
  89         vidcat -s 640x480 > test.jpg
  90         xview test.jpg
  91
  92 [Using xawtv:]
  93
  94 You must make some modifications to the source and compile it before you use it.
  95 (Note: this may not be applicable to versions other than 3.06)
  96
  97 In src/Xawtv.ad, change xawtv.tv.width to 640 and xawtv.tv.height to 480. Next,
  98 in src/grab-v4l.c, change SYNC_TIMEOUT from 1 to 2. Then, from the main xawtv
  99 directory:
 100
 101         make clean
 102         ./configure
 103         make
 104         make install
 105
 106 Now you should be able to run xawtv. Right click for the options dialog. If
 107 you get a scrambled image it is likely that you made a mistake in Xawtv.ad.
 108 Try setting the size to 320x240 if all else fails.
 109
 110 FAQ:
 111 Q: "Why does the picture have noise and look grainy"
 112 A: This is a problem at low light levels, and may be also due to subtle bugs in
 113    the code. The cause is most likely the OV7610 settings we are currently
 114    using. I am looking into this problem.
 115
 116 Q: "The driver sometimes says `Failed to read OV7610 ID.' What is the deal?"
 117 A: The I2C code that allows the OV511 to communicate with the camera chip is a
 118    bit flaky right now. This message means that the I2C bus never got
 119    initialized properly, and the camera will most likely not work even if you
 120    disable this warning. Try unloading/reloading the driver or unplugging/re-
 121    plugging the camera if this happens.
 122
 123 Q: "Why do you bother with this phony camera detection crap? It doesn't do
 124     anything useful!"
 125 A: The main purpose of only supporting known camera models is to force people
 126    with new camera models to tell me about them, so I can assemble the list
 127    above, and so the code can know what CCD chip you have. Right now, nearly all
 128    of the cameras use the OV7610 and consequently I have not put support for
 129    other ones in, so the value of the detection code is questionable. Eventually
 130    though, new CCDs might appear and we will be fortunate to have the detection.
 131
 132 MODULE PARAMETERS:
 133
 134   You can set these with:  insmod ov511 NAME=VALUE
 135   There is currently no way to set these on a per-camera basis.
 136
 137   NAME: autoadjust
 138   TYPE: integer (boolean)
 139   DEFAULT: 1
 140   DESC: The camera normally adjusts exposure, gain, and hue automatically. This
 141         can be set to 0 to disable this automatic adjustment. Note that there is
 142         currently no way to set these parameters manually once autoadjust is
 143         disabled. (This feature is not working yet)
 144
 145   NAME: debug
 146   TYPE: integer (0-6)
 147   DEFAULT: 3
 148   DESC: Sets the threshold for printing debug messages. The higher the value,
 149         the more is printed. The levels are cumulative, and are as follows:
 150           0=no debug messages
 151           1=init/detection/unload and other significant messages
 152           2=some warning messages
 153           3=config/control function calls
 154           4=most function calls and data parsing messages
 155           5=highly repetitive mesgs
 156
 157   NAME: fix_rgb_offset
 158   TYPE: integer (boolean)
 159   DEFAULT: 0
 160   DESC: Some people have reported that the blue component of the image is one
 161         or so lines higher than the red component. This is only apparent in
 162         images with white objects on black backgrounds at 640x480. Setting this
 163         to 1 will realign the color planes correctly. NOTE: This is still
 164         experimental and very buggy.
 165
 166   NAME: snapshot
 167   TYPE: integer (boolean)
 168   DEFAULT: 0
 169   DESC: Set to 1 to enable snapshot mode. read() will block until the snapshot
 170         button is pressed. Note that this does not yet work with most apps,
 171         including xawtv and vidcat. NOTE: See the section "TODO" for more info.
 172
 173 WORKING FEATURES:
 174  o Color streaming/capture at 640x480 and 320x240
 175  o YUV420 color
 176  o Monochrome
 177  o Setting/getting of saturation, contrast and brightness (no color yet)
 178
 179 EXPERIMENTAL FEATURES:
 180  o fix_rgb_offset: Sometimes works, but other times causes errors with xawtv and
 181    corrupted frames.
 182  o Snapshot mode (only works with some read() based apps; see below for more)
 183
 184 TODO:
 185  o Fix the noise / grainy image problem.
 186  o Get compression working. It would be a nice addition as it improves
 187    frame rate quite a bit. OmniVision wouldn't tell me how the algorithm works,
 188    so we can't really work on that yet. Please kindly inform OmniVision that you
 189    would like them to release their specifications to the Linux community.
 190  o Get 160x120 working
 191  o YUV422 (and other color modes)
 192  o Fix read(). It only works right now if you run an mmap() based app like xawtv
 193    or vidcat after loading the module and before using read(). Apparently there
 194    are some initialization issues.
 195  o Get snapshot mode working with mmap().
 196  o Fix fixFrameRGBoffset(). It is not stable yet with streaming video.
 197  o Get hue (red/blue channel balance) adjustment working (in ov511_get_picture()
 198    and ov511_set_picture())
 199  o Get autoadjust disable working
 200  o Devise some clean way to support different types of CCDs (based on Custom ID)
 201  o OV511A support
 202  o V4L2 support (Probably not until it goes into the kernel)
 203  o Fix I2C initialization. Some people are reporting problems with reading the
 204    7610 registers. This could be due to timing differences, an excessive I2C
 205    clock rate, or a problem with ov511_i2c_read().
 206  o Get rid of the memory management functions (put them in videodev.c??)
 207
 208 HOW TO CONTACT ME:
 209
 210 You can email me at mmcclelland@delphi.com . Please prefix the subject line
 211 with "OV511: " so that I am certain to notice your message.
 212
 213 CREDITS:
 214
 215 The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 216 Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 217 and the USB stack. Thanks to Bret Wallach for getting camera reg IO , ISOC, and
 218 image capture working. Thanks to Orion Sky Lawlor and Kevin Moore for their
 219 work as well.