Root/Documentation/video4linux/ibmcam.txt

1README for Linux device driver for the IBM "C-It" USB video camera
2
3INTRODUCTION:
4
5This driver does not use all features known to exist in
6the IBM camera. However most of needed features work well.
7
8This driver was developed using logs of observed USB traffic
9which was produced by standard Windows driver (c-it98.sys).
10I did not have data sheets from Xirlink.
11
12Video formats:
13      128x96 [model 1]
14      176x144
15      320x240 [model 2]
16      352x240 [model 2]
17      352x288
18Frame rate: 3 - 30 frames per second (FPS)
19External interface: USB
20Internal interface: Video For Linux (V4L)
21Supported controls:
22- by V4L: Contrast, Brightness, Color, Hue
23- by driver options: frame rate, lighting conditions, video format,
24             default picture settings, sharpness.
25
26SUPPORTED CAMERAS:
27
28Xirlink "C-It" camera, also known as "IBM PC Camera".
29The device uses proprietary ASIC (and compression method);
30it is manufactured by Xirlink. See http://xirlinkwebcam.sourceforge.net,
31http://www.ibmpccamera.com, or http://www.c-itnow.com/ for details and pictures.
32
33This very chipset ("X Chip", as marked at the factory)
34is used in several other cameras, and they are supported
35as well:
36
37- IBM NetCamera
38- Veo Stingray
39
40The Linux driver was developed with camera with following
41model number (or FCC ID): KSX-XVP510. This camera has three
42interfaces, each with one endpoint (control, iso, iso). This
43type of cameras is referred to as "model 1". These cameras are
44no longer manufactured.
45
46Xirlink now manufactures new cameras which are somewhat different.
47In particular, following models [FCC ID] belong to that category:
48
49XVP300 [KSX-X9903]
50XVP600 [KSX-X9902]
51XVP610 [KSX-X9902]
52
53(see http://www.xirlink.com/ibmpccamera/ for updates, they refer
54to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
55These cameras have two interfaces, one endpoint in each (iso, bulk).
56Such type of cameras is referred to as "model 2". They are supported
57(with exception of 352x288 native mode).
58
59Some IBM NetCameras (Model 4) are made to generate only compressed
60video streams. This is great for performance, but unfortunately
61nobody knows how to decompress the stream :-( Therefore, these
62cameras are *unsupported* and if you try to use one of those, all
63you get is random colored horizontal streaks, not the image!
64If you have one of those cameras, you probably should return it
65to the store and get something that is supported.
66
67Tell me more about all that "model" business
68--------------------------------------------
69
70I just invented model numbers to uniquely identify flavors of the
71hardware/firmware that were sold. It was very confusing to use
72brand names or some other internal numbering schemes. So I found
73by experimentation that all Xirlink chipsets fall into four big
74classes, and I called them "models". Each model is programmed in
75its own way, and each model sends back the video in its own way.
76
77Quirks of Model 2 cameras:
78-------------------------
79
80Model 2 does not have hardware contrast control. Corresponding V4L
81control is implemented in software, which is not very nice to your
82CPU, but at least it works.
83
84This driver provides 352x288 mode by switching the camera into
85quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
86this mode to 10 frames per second or less, in ideal conditions on
87the bus (USB is shared, after all). The frame rate
88has to be programmed very conservatively. Additional concern is that
89frame rate depends on brightness setting; therefore the picture can
90be good at one brightness and broken at another! I did not want to fix
91the frame rate at slowest setting, but I had to move it pretty much down
92the scale (so that framerate option barely matters). I also noticed that
93camera after first powering up produces frames slightly faster than during
94consecutive uses. All this means that if you use 352x288 (which is
95default), be warned - you may encounter broken picture on first connect;
96try to adjust brightness - brighter image is slower, so USB will be able
97to send all data. However if you regularly use Model 2 cameras you may
98prefer 176x144 which makes perfectly good I420, with no scaling and
99lesser demands on USB (300 Kbits per second, or 26 frames per second).
100
101Another strange effect of 352x288 mode is the fine vertical grid visible
102on some colored surfaces. I am sure it is caused by me not understanding
103what the camera is trying to say. Blame trade secrets for that.
104
105The camera that I had also has a hardware quirk: if disconnected,
106it 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
110observed this particular flaw in it.]
111
112Model 2 camera can be programmed for very high sensitivity (even starlight
113may be enough), this makes it convenient for tinkering with. The driver
114code has enough comments to help a programmer to tweak the camera
115as s/he feels necessary.
116
117WHAT 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.
124
125HOW TO COMPILE THE DRIVER:
126
127You need to compile the driver only if you are a developer
128or if you want to make changes to the code. Most distributions
129precompile all modules, so you can go directly to the next
130section "HOW TO USE THE DRIVER".
131
132The ibmcam driver uses usbvideo helper library (module),
133so if you are studying the ibmcam code you will be led there.
134
135The driver itself consists of only one file in usb/ directory:
136ibmcam.c. This file is included into the Linux kernel build
137process if you configure the kernel for CONFIG_USB_IBMCAM.
138Run "make xconfig" and in USB section you will find the IBM
139camera driver. Select it, save the configuration and recompile.
140
141HOW TO USE THE DRIVER:
142
143I recommend to compile driver as a module. This gives you an
144easier access to its configuration. The camera has many more
145settings than V4L can operate, so some settings are done using
146module options.
147
148To begin with, on most modern Linux distributions the driver
149will be automatically loaded whenever you plug the supported
150camera in. Therefore, you don't need to do anything. However
151if you want to experiment with some module parameters then
152you can load and unload the driver manually, with camera
153plugged in or unplugged.
154
155Typically module is installed with command 'modprobe', like this:
156
157# modprobe ibmcam framerate=1
158
159Alternatively you can use 'insmod' in similar fashion:
160
161# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
162
163Module can be inserted with camera connected or disconnected.
164
165The driver can have options, though some defaults are provided.
166
167Driver options: (* indicates that option is model-dependent)
168
169Name Type Range [default] Example
170-------------- -------------- -------------- ------------------
171debug Integer 0-9 [0] debug=1
172flags Integer 0-0xFF [0] flags=0x0d
173framerate Integer 0-6 [2] framerate=1
174hue_correction Integer 0-255 [128] hue_correction=115
175init_brightness Integer 0-255 [128] init_brightness=100
176init_contrast Integer 0-255 [192] init_contrast=200
177init_color Integer 0-255 [128] init_color=130
178init_hue Integer 0-255 [128] init_hue=115
179lighting Integer 0-2* [1] lighting=2
180sharpness Integer 0-6* [4] sharpness=3
181size Integer 0-2* [2] size=1
182
183Options for Model 2 only:
184
185Name Type Range [default] Example
186-------------- -------------- -------------- ------------------
187init_model2_rg Integer 0..255 [0x70] init_model2_rg=128
188init_model2_rg2 Integer 0..255 [0x2f] init_model2_rg2=50
189init_model2_sat Integer 0..255 [0x34] init_model2_sat=65
190init_model2_yb Integer 0..255 [0xa0] init_model2_yb=200
191
192debug 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.
195
196flags 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:
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.
229
230framerate 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.
236
237hue_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.
246
247init_brightness These settings specify _initial_ values which will be
248init_contrast used to set up the camera. If your V4L application has
249init_color its own controls to adjust the picture then these
250init_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.
253
254init_model2_rg These initial settings alter color balance of the
255init_model2_rg2 camera on hardware level. All four settings may be used
256init_model2_sat to tune the camera to specific lighting conditions. These
257init_model2_yb settings only apply to Model 2 cameras.
258
259lighting 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.
267
268sharpness 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.
274
275size 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:
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.
297
298For more information and the Troubleshooting FAQ visit this URL:
299
300        http://www.linux-usb.org/ibmcam/
301
302WHAT 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
317CREDITS:
318
319The code is based in no small part on the CPiA driver by Johannes Erdfelt,
320Randy Dunlap, and others. Big thanks to them for their pioneering work on that
321and the USB stack.
322
323I also thank John Lightsey for his donation of the Veo Stingray camera.
324

Archive Download this file



interactive