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