]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | README for Linux device driver for the IBM "C-It" USB video camera |
2 | ||
3 | INTRODUCTION: | |
4 | ||
5 | This driver does not use all features known to exist in | |
6 | the IBM camera. However most of needed features work well. | |
7 | ||
8 | This driver was developed using logs of observed USB traffic | |
9 | which was produced by standard Windows driver (c-it98.sys). | |
10 | I did not have data sheets from Xirlink. | |
11 | ||
12 | Video formats: | |
13 | 128x96 [model 1] | |
14 | 176x144 | |
15 | 320x240 [model 2] | |
16 | 352x240 [model 2] | |
17 | 352x288 | |
18 | Frame rate: 3 - 30 frames per second (FPS) | |
19 | External interface: USB | |
20 | Internal interface: Video For Linux (V4L) | |
21 | Supported controls: | |
22 | - by V4L: Contrast, Brightness, Color, Hue | |
23 | - by driver options: frame rate, lighting conditions, video format, | |
6e204090 | 24 | default picture settings, sharpness. |
1da177e4 LT |
25 | |
26 | SUPPORTED CAMERAS: | |
27 | ||
28 | Xirlink "C-It" camera, also known as "IBM PC Camera". | |
29 | The device uses proprietary ASIC (and compression method); | |
0ea6e611 JM |
30 | it is manufactured by Xirlink. See http://xirlinkwebcam.sourceforge.net, |
31 | http://www.ibmpccamera.com, or http://www.c-itnow.com/ for details and pictures. | |
1da177e4 LT |
32 | |
33 | This very chipset ("X Chip", as marked at the factory) | |
34 | is used in several other cameras, and they are supported | |
35 | as well: | |
36 | ||
37 | - IBM NetCamera | |
38 | - Veo Stingray | |
39 | ||
40 | The Linux driver was developed with camera with following | |
41 | model number (or FCC ID): KSX-XVP510. This camera has three | |
42 | interfaces, each with one endpoint (control, iso, iso). This | |
43 | type of cameras is referred to as "model 1". These cameras are | |
44 | no longer manufactured. | |
45 | ||
46 | Xirlink now manufactures new cameras which are somewhat different. | |
47 | In particular, following models [FCC ID] belong to that category: | |
48 | ||
49 | XVP300 [KSX-X9903] | |
50 | XVP600 [KSX-X9902] | |
51 | XVP610 [KSX-X9902] | |
52 | ||
53 | (see http://www.xirlink.com/ibmpccamera/ for updates, they refer | |
54 | to these new cameras by Windows driver dated 12-27-99, v3005 BETA) | |
55 | These cameras have two interfaces, one endpoint in each (iso, bulk). | |
56 | Such type of cameras is referred to as "model 2". They are supported | |
57 | (with exception of 352x288 native mode). | |
58 | ||
59 | Some IBM NetCameras (Model 4) are made to generate only compressed | |
60 | video streams. This is great for performance, but unfortunately | |
61 | nobody knows how to decompress the stream :-( Therefore, these | |
62 | cameras are *unsupported* and if you try to use one of those, all | |
63 | you get is random colored horizontal streaks, not the image! | |
64 | If you have one of those cameras, you probably should return it | |
65 | to the store and get something that is supported. | |
66 | ||
67 | Tell me more about all that "model" business | |
68 | -------------------------------------------- | |
69 | ||
70 | I just invented model numbers to uniquely identify flavors of the | |
71 | hardware/firmware that were sold. It was very confusing to use | |
72 | brand names or some other internal numbering schemes. So I found | |
73 | by experimentation that all Xirlink chipsets fall into four big | |
74 | classes, and I called them "models". Each model is programmed in | |
75 | its own way, and each model sends back the video in its own way. | |
76 | ||
77 | Quirks of Model 2 cameras: | |
78 | ------------------------- | |
79 | ||
80 | Model 2 does not have hardware contrast control. Corresponding V4L | |
81 | control is implemented in software, which is not very nice to your | |
82 | CPU, but at least it works. | |
83 | ||
84 | This driver provides 352x288 mode by switching the camera into | |
85 | quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting | |
86 | this mode to 10 frames per second or less, in ideal conditions on | |
87 | the bus (USB is shared, after all). The frame rate | |
88 | has to be programmed very conservatively. Additional concern is that | |
89 | frame rate depends on brightness setting; therefore the picture can | |
90 | be good at one brightness and broken at another! I did not want to fix | |
91 | the frame rate at slowest setting, but I had to move it pretty much down | |
92 | the scale (so that framerate option barely matters). I also noticed that | |
93 | camera after first powering up produces frames slightly faster than during | |
94 | consecutive uses. All this means that if you use 352x288 (which is | |
95 | default), be warned - you may encounter broken picture on first connect; | |
96 | try to adjust brightness - brighter image is slower, so USB will be able | |
97 | to send all data. However if you regularly use Model 2 cameras you may | |
98 | prefer 176x144 which makes perfectly good I420, with no scaling and | |
99 | lesser demands on USB (300 Kbits per second, or 26 frames per second). | |
100 | ||
101 | Another strange effect of 352x288 mode is the fine vertical grid visible | |
102 | on some colored surfaces. I am sure it is caused by me not understanding | |
103 | what the camera is trying to say. Blame trade secrets for that. | |
104 | ||
105 | The camera that I had also has a hardware quirk: if disconnected, | |
106 | it needs few minutes to "relax" before it can be plugged in again | |
107 | (poorly designed USB processor reset circuit?) | |
108 | ||
109 | [Veo Stingray with Product ID 0x800C is also Model 2, but I haven't | |
110 | observed this particular flaw in it.] | |
111 | ||
112 | Model 2 camera can be programmed for very high sensitivity (even starlight | |
113 | may be enough), this makes it convenient for tinkering with. The driver | |
114 | code has enough comments to help a programmer to tweak the camera | |
115 | as s/he feels necessary. | |
116 | ||
117 | WHAT YOU NEED: | |
118 | ||
119 | - A supported IBM PC (C-it) camera (model 1 or 2) | |
120 | ||
121 | - A Linux box with USB support (2.3/2.4; 2.2 w/backport may work) | |
122 | ||
123 | - A Video4Linux compatible frame grabber program such as xawtv. | |
1864cfb1 | 124 | |
1da177e4 LT |
125 | HOW TO COMPILE THE DRIVER: |
126 | ||
127 | You need to compile the driver only if you are a developer | |
128 | or if you want to make changes to the code. Most distributions | |
129 | precompile all modules, so you can go directly to the next | |
130 | section "HOW TO USE THE DRIVER". | |
131 | ||
132 | The ibmcam driver uses usbvideo helper library (module), | |
133 | so if you are studying the ibmcam code you will be led there. | |
134 | ||
135 | The driver itself consists of only one file in usb/ directory: | |
136 | ibmcam.c. This file is included into the Linux kernel build | |
137 | process if you configure the kernel for CONFIG_USB_IBMCAM. | |
138 | Run "make xconfig" and in USB section you will find the IBM | |
139 | camera driver. Select it, save the configuration and recompile. | |
140 | ||
141 | HOW TO USE THE DRIVER: | |
142 | ||
143 | I recommend to compile driver as a module. This gives you an | |
144 | easier access to its configuration. The camera has many more | |
145 | settings than V4L can operate, so some settings are done using | |
146 | module options. | |
147 | ||
148 | To begin with, on most modern Linux distributions the driver | |
149 | will be automatically loaded whenever you plug the supported | |
150 | camera in. Therefore, you don't need to do anything. However | |
151 | if you want to experiment with some module parameters then | |
152 | you can load and unload the driver manually, with camera | |
153 | plugged in or unplugged. | |
154 | ||
155 | Typically module is installed with command 'modprobe', like this: | |
156 | ||
157 | # modprobe ibmcam framerate=1 | |
158 | ||
159 | Alternatively you can use 'insmod' in similar fashion: | |
160 | ||
161 | # insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1 | |
162 | ||
163 | Module can be inserted with camera connected or disconnected. | |
164 | ||
165 | The driver can have options, though some defaults are provided. | |
166 | ||
167 | Driver options: (* indicates that option is model-dependent) | |
168 | ||
169 | Name Type Range [default] Example | |
170 | -------------- -------------- -------------- ------------------ | |
171 | debug Integer 0-9 [0] debug=1 | |
172 | flags Integer 0-0xFF [0] flags=0x0d | |
173 | framerate Integer 0-6 [2] framerate=1 | |
174 | hue_correction Integer 0-255 [128] hue_correction=115 | |
175 | init_brightness Integer 0-255 [128] init_brightness=100 | |
176 | init_contrast Integer 0-255 [192] init_contrast=200 | |
177 | init_color Integer 0-255 [128] init_color=130 | |
178 | init_hue Integer 0-255 [128] init_hue=115 | |
179 | lighting Integer 0-2* [1] lighting=2 | |
180 | sharpness Integer 0-6* [4] sharpness=3 | |
181 | size Integer 0-2* [2] size=1 | |
182 | ||
183 | Options for Model 2 only: | |
184 | ||
185 | Name Type Range [default] Example | |
186 | -------------- -------------- -------------- ------------------ | |
187 | init_model2_rg Integer 0..255 [0x70] init_model2_rg=128 | |
188 | init_model2_rg2 Integer 0..255 [0x2f] init_model2_rg2=50 | |
189 | init_model2_sat Integer 0..255 [0x34] init_model2_sat=65 | |
190 | init_model2_yb Integer 0..255 [0xa0] init_model2_yb=200 | |
191 | ||
192 | debug You don't need this option unless you are a developer. | |
6e204090 MK |
193 | If you are a developer then you will see in the code |
194 | what values do what. 0=off. | |
1da177e4 LT |
195 | |
196 | flags This is a bit mask, and you can combine any number of | |
6e204090 MK |
197 | bits to produce what you want. Usually you don't want |
198 | any of extra features this option provides: | |
199 | ||
200 | FLAGS_RETRY_VIDIOCSYNC 1 This bit allows to retry failed | |
201 | VIDIOCSYNC ioctls without failing. | |
202 | Will work with xawtv, will not | |
203 | with xrealproducer. Default is | |
204 | not set. | |
205 | FLAGS_MONOCHROME 2 Activates monochrome (b/w) mode. | |
206 | FLAGS_DISPLAY_HINTS 4 Shows colored pixels which have | |
207 | magic meaning to developers. | |
208 | FLAGS_OVERLAY_STATS 8 Shows tiny numbers on screen, | |
209 | useful only for debugging. | |
210 | FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers. | |
211 | FLAGS_SEPARATE_FRAMES 32 Shows each frame separately, as | |
212 | it was received from the camera. | |
213 | Default (not set) is to mix the | |
214 | preceding frame in to compensate | |
215 | for occasional loss of Isoc data | |
216 | on high frame rates. | |
217 | FLAGS_CLEAN_FRAMES 64 Forces "cleanup" of each frame | |
218 | prior to use; relevant only if | |
219 | FLAGS_SEPARATE_FRAMES is set. | |
220 | Default is not to clean frames, | |
221 | this is a little faster but may | |
222 | produce flicker if frame rate is | |
223 | too high and Isoc data gets lost. | |
224 | FLAGS_NO_DECODING 128 This flag turns the video stream | |
225 | decoder off, and dumps the raw | |
226 | Isoc data from the camera into | |
227 | the reading process. Useful to | |
228 | developers, but not to users. | |
1da177e4 LT |
229 | |
230 | framerate This setting controls frame rate of the camera. This is | |
6e204090 MK |
231 | an approximate setting (in terms of "worst" ... "best") |
232 | because camera changes frame rate depending on amount | |
233 | of light available. Setting 0 is slowest, 6 is fastest. | |
234 | Beware - fast settings are very demanding and may not | |
235 | work well with all video sizes. Be conservative. | |
1da177e4 LT |
236 | |
237 | hue_correction This highly optional setting allows to adjust the | |
6e204090 MK |
238 | hue of the image in a way slightly different from |
239 | what usual "hue" control does. Both controls affect | |
240 | YUV colorspace: regular "hue" control adjusts only | |
241 | U component, and this "hue_correction" option similarly | |
242 | adjusts only V component. However usually it is enough | |
243 | to tweak only U or V to compensate for colored light or | |
244 | color temperature; this option simply allows more | |
245 | complicated correction when and if it is necessary. | |
1da177e4 LT |
246 | |
247 | init_brightness These settings specify _initial_ values which will be | |
248 | init_contrast used to set up the camera. If your V4L application has | |
249 | init_color its own controls to adjust the picture then these | |
250 | init_hue controls will be used too. These options allow you to | |
6e204090 MK |
251 | preconfigure the camera when it gets connected, before |
252 | any V4L application connects to it. Good for webcams. | |
1da177e4 LT |
253 | |
254 | init_model2_rg These initial settings alter color balance of the | |
255 | init_model2_rg2 camera on hardware level. All four settings may be used | |
256 | init_model2_sat to tune the camera to specific lighting conditions. These | |
257 | init_model2_yb settings only apply to Model 2 cameras. | |
258 | ||
259 | lighting This option selects one of three hardware-defined | |
6e204090 MK |
260 | photosensitivity settings of the camera. 0=bright light, |
261 | 1=Medium (default), 2=Low light. This setting affects | |
262 | frame rate: the dimmer the lighting the lower the frame | |
263 | rate (because longer exposition time is needed). The | |
264 | Model 2 cameras allow values more than 2 for this option, | |
265 | thus enabling extremely high sensitivity at cost of frame | |
266 | rate, color saturation and imaging sensor noise. | |
1da177e4 LT |
267 | |
268 | sharpness This option controls smoothing (noise reduction) | |
6e204090 MK |
269 | made by camera. Setting 0 is most smooth, setting 6 |
270 | is most sharp. Be aware that CMOS sensor used in the | |
271 | camera is pretty noisy, so if you choose 6 you will | |
272 | be greeted with "snowy" image. Default is 4. Model 2 | |
273 | cameras do not support this feature. | |
1da177e4 LT |
274 | |
275 | size This setting chooses one of several image sizes that are | |
6e204090 MK |
276 | supported by this driver. Cameras may support more, but |
277 | it's difficult to reverse-engineer all formats. | |
278 | Following video sizes are supported: | |
279 | ||
280 | size=0 128x96 (Model 1 only) | |
281 | size=1 160x120 | |
282 | size=2 176x144 | |
283 | size=3 320x240 (Model 2 only) | |
284 | size=4 352x240 (Model 2 only) | |
285 | size=5 352x288 | |
286 | size=6 640x480 (Model 3 only) | |
287 | ||
288 | The 352x288 is the native size of the Model 1 sensor | |
289 | array, so it's the best resolution the camera can | |
290 | yield. The best resolution of Model 2 is 176x144, and | |
291 | larger images are produced by stretching the bitmap. | |
292 | Model 3 has sensor with 640x480 grid, and it works too, | |
293 | but the frame rate will be exceptionally low (1-2 FPS); | |
294 | it may be still OK for some applications, like security. | |
295 | Choose the image size you need. The smaller image can | |
296 | support faster frame rate. Default is 352x288. | |
1da177e4 LT |
297 | |
298 | For more information and the Troubleshooting FAQ visit this URL: | |
299 | ||
6e204090 | 300 | http://www.linux-usb.org/ibmcam/ |
1da177e4 LT |
301 | |
302 | WHAT NEEDS TO BE DONE: | |
303 | ||
304 | - The button on the camera is not used. I don't know how to get to it. | |
305 | I know now how to read button on Model 2, but what to do with it? | |
306 | ||
307 | - Camera reports its status back to the driver; however I don't know | |
308 | what returned data means. If camera fails at some initialization | |
309 | stage then something should be done, and I don't do that because | |
310 | I don't even know that some command failed. This is mostly Model 1 | |
311 | concern because Model 2 uses different commands which do not return | |
312 | status (and seem to complete successfully every time). | |
313 | ||
314 | - Some flavors of Model 4 NetCameras produce only compressed video | |
315 | streams, and I don't know how to decode them. | |
316 | ||
317 | CREDITS: | |
318 | ||
319 | The code is based in no small part on the CPiA driver by Johannes Erdfelt, | |
320 | Randy Dunlap, and others. Big thanks to them for their pioneering work on that | |
321 | and the USB stack. | |
322 | ||
323 | I also thank John Lightsey for his donation of the Veo Stingray camera. |