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