| blob | a51055211e624e4a36d8e5e78f5887c81bb01676 |
1 README for Linux device driver for the IBM "C-It" USB video camera
3 INTRODUCTION:
5 This driver does not use all features known to exist in
6 the IBM camera. However most of needed features work well.
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.
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,
24 default picture settings, sharpness.
26 SUPPORTED CAMERAS:
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://xirlinkwebcam.sourceforge.net,
31 http://www.ibmpccamera.com, or http://www.c-itnow.com/ for details and pictures.
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:
37 - IBM NetCamera
38 - Veo Stingray
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.
46 Xirlink now manufactures new cameras which are somewhat different.
47 In particular, following models [FCC ID] belong to that category:
49 XVP300 [KSX-X9903]
50 XVP600 [KSX-X9902]
51 XVP610 [KSX-X9902]
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).
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.
67 Tell me more about all that "model" business
68 --------------------------------------------
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.
77 Quirks of Model 2 cameras:
78 -------------------------
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.
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).
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.
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?)
109 [Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
110 observed this particular flaw in it.]
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.
117 WHAT YOU NEED:
119 - A supported IBM PC (C-it) camera (model 1 or 2)
121 - A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)
123 - A Video4Linux compatible frame grabber program such as xawtv.
125 HOW TO COMPILE THE DRIVER:
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".
132 The ibmcam driver uses usbvideo helper library (module),
133 so if you are studying the ibmcam code you will be led there.
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.
141 HOW TO USE THE DRIVER:
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.
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.
155 Typically module is installed with command 'modprobe', like this:
157 # modprobe ibmcam framerate=1
159 Alternatively you can use 'insmod' in similar fashion:
161 # insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
163 Module can be inserted with camera connected or disconnected.
165 The driver can have options, though some defaults are provided.
167 Driver options: (* indicates that option is model-dependent)
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
183 Options for Model 2 only:
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
192 debug You don't need this option unless you are a developer.
193 If you are a developer then you will see in the code
194 what values do what. 0=off.
196 flags This is a bit mask, and you can combine any number of
197 bits to produce what you want. Usually you don't want
198 any of extra features this option provides:
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.
230 framerate This setting controls frame rate of the camera. This is
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.
237 hue_correction This highly optional setting allows to adjust the
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.
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
251 preconfigure the camera when it gets connected, before
252 any V4L application connects to it. Good for webcams.
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.
259 lighting This option selects one of three hardware-defined
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.
268 sharpness This option controls smoothing (noise reduction)
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.
275 size This setting chooses one of several image sizes that are
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:
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)
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.
298 For more information and the Troubleshooting FAQ visit this URL:
300 http://www.linux-usb.org/ibmcam/
302 WHAT NEEDS TO BE DONE:
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?
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).
314 - Some flavors of Model 4 NetCameras produce only compressed video
315 streams, and I don't know how to decode them.
317 CREDITS:
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.
323 I also thank John Lightsey for his donation of the Veo Stingray camera.