1-------------------------------------------------------------------------------- 2Readme for Linux device driver for the OmniVision OV51x USB to camera bridge ICs 3-------------------------------------------------------------------------------- 4 5Author: Mark McClelland 6Homepage: http://alpha.dyndns.org/ov511 7Support for OV519, OV8610: Joerg Heckenbach 8 9 10INTRODUCTION: 11 12This is a driver for the OV51x series, USB-only chips used in many "webcam" devices. 13Any camera using the OV51x/OV51x+ and the OV6620/OV7610/20/20AE/8610 should work. 14Video capture devices that use the Philips SAA7111A decoder also work. It 15supports streaming and capture of color or monochrome video via the Video4Linux 16API. Most V4L apps are compatible with it. Most resolutions with a width and 17height that are a multiple of 8 are supported. 18 19If you need more information, please visit the OV51x homepage at the above URL or 20contact Joerg Heckenbach <joerg@heckenbach-aw.de>. 21 22WHAT YOU NEED: 23 24- Kernel support for Video4Linux and USB 25 26- A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv) 27 vidcat is part of the w3cam package: http://www.hdk-berlin.de/~rasca/w3cam/ 28 xawtv is available at: http://www.in-berlin.de/User/kraxel/xawtv.html 29 30HOW TO USE IT: 31 32Note: These are simplified instructions. For complete instructions see: 33 http://alpha.dyndns.org/ov511/install.html 34 35You must have first compiled USB support, support for your specific USB host 36controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend 37making them modules.) Make sure "Enforce bandwidth allocation" is NOT enabled. 38 39Next, (as root): 40 41 modprobe usbcore 42 modprobe usb-uhci <OR> modprobe usb-ohci (for 2.2 & 2.4 kernels) 43 modprobe uhci-hcd <OR> modprobe ohci-hcd (for 2.5 kernels) 44 modprobe videodev 45 modprobe ov51x 46 47If it is not already there (it usually is), create the video device: 48 49 mknod /dev/video0 c 81 0 50 51You will have to set permissions on this device to allow you to read/write 52from it: 53 54 chmod 660 /dev/video0 55 chown user.group /dev/video0 (substitute your user and group) 56 57Now you are ready to run a video app! Both vidcat and xawtv work well for me with ov511 58and ov518 devices. For ov519 you can use getjpeg (ov51x/test directory). 59(NOTE: vidcat might not work with cameras that have an OV6620 or OV6630 sensor) 60 61[Using vidcat:] 62 63 vidcat -s 352x288 -p y -d /dev/video0 > test.jpg 64 xview test.jpg 65 66[Using xawtv:] 67 68From the main xawtv directory: 69 70 make clean 71 ./configure 72 make 73 make install 74 75Now you should be able to run "xawtv -c /dev/video0". Right click for the 76options dialog. 77 78[using getjpeg (OV519)] 79 80 getjpeg -s 800x600 -n 1 -d /dev/video0 -o image 81 xview image-00.jpg 82 83MODULE PARAMETERS: 84 85 You can set these with: insmod ov51x NAME=VALUE 86 There is currently no way to set these on a per-camera basis. 87 88 NAME: autobright 89 TYPE: integer (Boolean) 90 DEFAULT: 1 91 DESC: Brightness is normally under automatic control and can't be set 92 manually by the video app. Set to 0 for manual control. 93 94 NAME: autogain 95 TYPE: integer (Boolean) 96 DEFAULT: 1 97 DESC: Auto Gain Control enable. This feature is not yet implemented. 98 99 NAME: autoexp 100 TYPE: integer (Boolean) 101 DEFAULT: 1 102 DESC: Auto Exposure Control enable. This feature is not yet implemented. 103 104 NAME: debug 105 TYPE: integer (0-6) 106 DEFAULT: 3 107 DESC: Sets the threshold for printing debug messages. The higher the value, 108 the more is printed. The levels are cumulative, and are as follows: 109 0=no debug messages 110 1=init/detection/unload and other significant messages 111 2=some warning messages 112 3=config/control function calls 113 4=most function calls and data parsing messages 114 5=highly repetitive mesgs 115 116 NAME: fix_rgb_offset 117 TYPE: integer (Boolean) 118 DEFAULT: 0 119 DESC: Some people have reported that the blue component of the image is one 120 or so lines higher than the red component. This is only apparent in 121 images with white objects on black backgrounds at 640x480. Setting this 122 to 1 will realign the color planes correctly. NOTE: You will likely 123 need a fast (500 MHz) CPU. 124 125 NAME: snapshot 126 TYPE: integer (Boolean) 127 DEFAULT: 0 128 DESC: Set to 1 to enable snapshot mode. read()/VIDIOCSYNC will block until 129 the snapshot button is pressed. Note: enabling this mode disables 130 /proc/video/ov51x/<minor#>/button 131 132 NAME: force_rgb (Deprecated; may be removed in the future) 133 TYPE: integer (Boolean) 134 DEFAULT: 0 135 DESC: Force image to be read in RGB instead of BGR. This option allow 136 programs that expect RGB data (e.g. gqcam) to work with this driver. If 137 your colors look VERY wrong, you may want to change this. 138 139 NAME: cams 140 TYPE: integer (1-4 for OV511, 1-31 for OV511+) 141 DEFAULT: 1 142 DESC: Number of cameras allowed to stream simultaneously on a single bus. 143 Values higher than 1 reduce the data rate of each camera, allowing two 144 or more to be used at once. If you have a complicated setup involving 145 both OV511 and OV511+ cameras, trial-and-error may be necessary for 146 finding the optimum setting. 147 148 NAME: compress 149 TYPE: integer (Boolean) 150 DEFAULT: 0 151 DESC: Set this to 1 to turn on the camera's compression engine. This can 152 potentially increase the frame rate at the expense of quality, if you 153 have a fast CPU. You must load the proper compression module for your 154 camera before starting your application (ov511_decomp or ov518_decomp). 155 156 NAME: testpat 157 TYPE: integer (Boolean) 158 DEFAULT: 0 159 DESC: This configures the camera's sensor to transmit a colored test-pattern 160 instead of an image. This does not work correctly yet. 161 162 NAME: dumppix 163 TYPE: integer (0-2) 164 DEFAULT: 0 165 DESC: Dumps raw pixel data and skips post-processing and format conversion. 166 It is for debugging purposes only. Options are: 167 0: Disable (default) 168 1: Dump raw data from camera, excluding headers and trailers 169 2: Dumps data exactly as received from camera 170 171 NAME: led 172 TYPE: integer (0-2) 173 DEFAULT: 1 (Always on) 174 DESC: Controls whether the LED (the little light) on the front of the camera 175 is always off (0), always on (1), or only on when driver is open (2). 176 This is not supported with the OV511, and might only work with certain 177 cameras (ones that actually have the LED wired to the control pin, and 178 not just hard-wired to be on all the time). 179 180 NAME: dump_bridge 181 TYPE: integer (Boolean) 182 DEFAULT: 0 183 DESC: Dumps the bridge (OV511[+] or OV518[+]) register values to the system 184 log. Only useful for serious debugging/development purposes. 185 186 NAME: dump_sensor 187 TYPE: integer (Boolean) 188 DEFAULT: 0 189 DESC: Dumps the sensor register values to the system log. Only useful for 190 serious debugging/development purposes. 191 192 NAME: printph 193 TYPE: integer (Boolean) 194 DEFAULT: 0 195 DESC: Setting this to 1 will dump the first 12 bytes of each isoc frame. This 196 is only useful if you are trying to debug problems with the isoc data 197 stream (i.e.: camera initializes, but vidcat hangs until Ctrl-C). Be 198 warned that this dumps a large number of messages to your kernel log. 199 200 NAME: phy, phuv, pvy, pvuv, qhy, qhuv, qvy, qvuv 201 TYPE: integer (0-63 for phy and phuv, 0-255 for rest) 202 DEFAULT: OV511 default values 203 DESC: These are registers 70h - 77h of the OV511, which control the 204 prediction ranges and quantization thresholds of the compressor, for 205 the Y and UV channels in the horizontal and vertical directions. See 206 the OV511 or OV511+ data sheet for more detailed descriptions. These 207 normally do not need to be changed. 208 209 NAME: lightfreq 210 TYPE: integer (0, 50, or 60) 211 DEFAULT: 0 (use sensor default) 212 DESC: Sets the sensor to match your lighting frequency. This can reduce the 213 appearance of "banding", i.e. horizontal lines or waves of light and 214 dark that are often caused by artificial lighting. Valid values are: 215 0 - Use default (depends on sensor, most likely 60 Hz) 216 50 - For European and Asian 50 Hz power 217 60 - For American 60 Hz power 218 219 NAME: bandingfilter 220 TYPE: integer (Boolean) 221 DEFAULT: 0 (off) 222 DESC: Enables the sensor�s banding filter exposure algorithm. This reduces 223 or stabilizes the "banding" caused by some artificial light sources 224 (especially fluorescent). You might have to set lightfreq correctly for 225 this to work right. As an added bonus, this sometimes makes it 226 possible to capture your monitor�s output. 227 228 NAME: fastset 229 TYPE: integer (Boolean) 230 DEFAULT: 0 (off) 231 DESC: Allows picture settings (brightness, contrast, color, and hue) to take 232 effect immediately, even in the middle of a frame. This reduces the 233 time to change settings, but can ruin frames during the change. Only 234 affects OmniVision sensors. 235 236 NAME: force_palette 237 TYPE: integer 238 DEFAULT: 0 (off) 239 DESC: Forces the palette (color format) to a specific value. If an 240 application requests a different palette, it will be rejected, thereby 241 forcing it to try others until it succeeds. This is useful for forcing 242 greyscale mode with a color camera, for example. Supported modes are: 243 0 (Allows all the following formats) 244 1 VIDEO_PALETTE_GREY (Linear greyscale) 245 3 VIDEO_PALETTE_RGB565 (565 16 bit RGB) 246 4 VIDEO_PALETTE_RGB24 (24bit RGB) 247 7 VIDEO_PALETTE_YUV422 (YUV422 capture) 248 8 VIDEO_PALETTE_YUYV (YUV422 capture; same as 7) 249 10 VIDEO_PALETTE_YUV420 (YUV 4:2:0 Planar) 250 13 VIDEO_PALETTE_YUV422P (YUV 4:2:2 Planar) 251 15 VIDEO_PALETTE_YUV420P (YUV 4:2:0 Planar, same as 10) 252 253 NAME: backlight 254 TYPE: integer (Boolean) 255 DEFAULT: 0 (off) 256 DESC: Setting this flag changes the exposure algorithm for OmniVision sensors 257 such that objects in the camera's view (i.e. your head) can be clearly 258 seen when they are illuminated from behind. It reduces or eliminates 259 the sensor's auto-exposure function, so it should only be used when 260 needed. Additionally, it is only supported with the OV6620 and OV7620. 261 262 NAME: unit_video 263 TYPE: Up to 16 comma-separated integers 264 DEFAULT: 0,0,0... (automatically assign the next available minor(s)) 265 DESC: You can specify up to 16 minor numbers to be assigned to ov51x devices. 266 For example, "unit_video=1,3" will make the driver use /dev/video1 and 267 /dev/video3 for the first two devices it detects. Additional devices 268 will be assigned automatically starting at the first available device 269 node (/dev/video0 in this case). Note that you cannot specify 0 as a 270 minor number. This feature requires kernel version 2.4.5 or higher. 271 272 NAME: remove_zeros 273 TYPE: integer (Boolean) 274 DEFAULT: 0 (do not skip any incoming data) 275 DESC: Setting this to 1 will remove zero-padding from incoming data. This 276 will compensate for the blocks of corruption that can appear when the 277 camera cannot keep up with the speed of the USB bus (eg. at low frame 278 resolutions). This feature is always enabled when compression is on. 279 280 NAME: mirror 281 TYPE: integer (Boolean) 282 DEFAULT: 0 (off) 283 DESC: Setting this to 1 will reverse ("mirror") the image horizontally. This 284 might be necessary if your camera has a custom lens assembly. This has 285 no effect with video capture devices. 286 287 NAME: ov518_color 288 TYPE: integer (Boolean) 289 DEFAULT: 0 (off) 290 DESC: Enable OV518 color support. This is off by default since it doesn't 291 work most of the time. If you want to try it, you must also load 292 ov518_decomp with the "nouv=0" parameter. If you get improper colors or 293 diagonal lines through the image, restart your video app and try again. 294 Repeat as necessary. 295 296 NAME: framerate 297 TYPE: integer 298 DEFAULT: 15 (fps) 299 DESC: Force a specific internal framerate for ov519 devices. Useful values 300 are 5, 10 or 15. 301 302 NAME: jpeginfo 303 TYPE: integer (Boolean) 304 DEFAULT: 1 305 DESC: Force information on JPEG size in first two bytes of frame buffer for 306 ov519 devices. The size of the JPEG is 8 times the unsigned short (u16) of 307 the first two bytes in little endian byte ordering. 308 309WORKING FEATURES: 310 311 o Color streaming/capture at most widths and heights that are multiples of 8. 312 o RGB24, RGB565, YUV420/YUV420P, YUV422/YUYV, and YUV422P color 313 o Monochrome (use force_palette=1 to enable) 314 o Setting/getting of saturation, contrast, brightness, and hue (only some of 315 them work the OV7620 and OV7620AE) 316 o /proc status reporting 317 o SAA7111A video capture support at 320x240 and 640x480 318 o Compression support 319 o SMP compatibility 320 321HOW TO CONTACT ME: 322 323You can email me at mark@alpha.dyndns.org . Please prefix the subject line 324with "OV511: " so that I am certain to notice your message. 325 326CREDITS: 327 328The code is based in no small part on the CPiA driver by Johannes Erdfelt, 329Randy Dunlap, and others. Big thanks to them for their pioneering work on that 330and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and 331image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio 332Matsuoka for their work as well. 333 334
