blob: a7fc0432bff1a406b1dc385a4d4912b96d567a3d [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001-------------------------------------------------------------------------------
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)
Randy Dunlap98766fb2005-11-21 21:32:31 -080025 vidcat is part of the w3cam package: http://mpx.freeshell.net/
26 xawtv is available at: http://linux.bytesex.org/xawtv/
Linus Torvalds1da177e2005-04-16 15:20:36 -070027
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