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
