Commit | Line | Data |
---|---|---|
1da177e4 LT |
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. | |
1864cfb1 | 12 | Video capture devices that use the Philips SAA7111A decoder also work. It |
1da177e4 LT |
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) | |
98766fbe RD |
25 | vidcat is part of the w3cam package: http://mpx.freeshell.net/ |
26 | xawtv is available at: http://linux.bytesex.org/xawtv/ | |
1da177e4 LT |
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) | |
1864cfb1 | 55 | |
1da177e4 LT |
56 | Now you are ready to run a video app! Both vidcat and xawtv work well for me |
57 | at 640x480. | |
1864cfb1 | 58 | |
1da177e4 LT |
59 | [Using vidcat:] |
60 | ||
61 | vidcat -s 640x480 -p c > test.jpg | |
62 | xview test.jpg | |
1864cfb1 | 63 | |
1da177e4 LT |
64 | [Using xawtv:] |
65 | ||
66 | From the main xawtv directory: | |
67 | ||
68 | make clean | |
69 | ./configure | |
70 | make | |
71 | make install | |
72 | ||
1864cfb1 | 73 | Now you should be able to run xawtv. Right click for the options dialog. |
1da177e4 LT |
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 | |
6e204090 | 84 | manually by the video app. Set to 0 for manual control. |
1da177e4 LT |
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, | |
6e204090 MK |
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 | |
1da177e4 LT |
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. | |
6e204090 MK |
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. | |
1da177e4 LT |
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 | |
6e204090 MK |
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). | |
1da177e4 LT |
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 | |
6e204090 | 136 | instead of an image. This does not work correctly yet. |
1da177e4 LT |
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) | |
be2a608b | 198 | DESC: Enables the sensorĀ“s banding filter exposure algorithm. This reduces |
1da177e4 LT |
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 | |
be2a608b | 202 | possible to capture your monitorĀ“s output. |
1da177e4 LT |
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. |