Linux-2.6.12-rc2
[linux-3.10.git] / Documentation / usb / ov511.txt
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