PageRenderTime 26ms CodeModel.GetById 10ms app.highlight 5ms RepoModel.GetById 2ms app.codeStats 0ms

Plain Text | 324 lines | 260 code | 64 blank | 0 comment | 0 complexity | 3499b648cb6dc81701a1a87c3b26b388 MD5 | raw file
  1README for Linux device driver for the IBM "C-It" USB video camera
  5This driver does not use all features known to exist in
  6the IBM camera. However most of needed features work well.
  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.
 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.
 28Xirlink "C-It" camera, also known as "IBM PC Camera".
 29The device uses proprietary ASIC (and compression method);
 30it is manufactured by Xirlink. See
 31 or for
 32details and pictures.
 34This very chipset ("X Chip", as marked at the factory)
 35is used in several other cameras, and they are supported
 36as well:
 38- IBM NetCamera
 39- Veo Stingray
 41The Linux driver was developed with camera with following
 42model number (or FCC ID): KSX-XVP510. This camera has three
 43interfaces, each with one endpoint (control, iso, iso). This
 44type of cameras is referred to as "model 1". These cameras are
 45no longer manufactured.
 47Xirlink now manufactures new cameras which are somewhat different.
 48In particular, following models [FCC ID] belong to that category:
 50XVP300 [KSX-X9903]
 51XVP600 [KSX-X9902]
 52XVP610 [KSX-X9902]
 54(see for updates, they refer
 55to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
 56These cameras have two interfaces, one endpoint in each (iso, bulk).
 57Such type of cameras is referred to as "model 2". They are supported
 58(with exception of 352x288 native mode).
 60Some IBM NetCameras (Model 4) are made to generate only compressed
 61video streams. This is great for performance, but unfortunately
 62nobody knows how to decompress the stream :-( Therefore, these
 63cameras are *unsupported* and if you try to use one of those, all
 64you get is random colored horizontal streaks, not the image!
 65If you have one of those cameras, you probably should return it
 66to the store and get something that is supported.
 68Tell me more about all that "model" business
 71I just invented model numbers to uniquely identify flavors of the
 72hardware/firmware that were sold. It was very confusing to use
 73brand names or some other internal numbering schemes. So I found
 74by experimentation that all Xirlink chipsets fall into four big
 75classes, and I called them "models". Each model is programmed in
 76its own way, and each model sends back the video in its own way.
 78Quirks of Model 2 cameras:
 81Model 2 does not have hardware contrast control. Corresponding V4L
 82control is implemented in software, which is not very nice to your
 83CPU, but at least it works.
 85This driver provides 352x288 mode by switching the camera into
 86quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
 87this mode to 10 frames per second or less, in ideal conditions on
 88the bus (USB is shared, after all). The frame rate
 89has to be programmed very conservatively. Additional concern is that
 90frame rate depends on brightness setting; therefore the picture can
 91be good at one brightness and broken at another! I did not want to fix
 92the frame rate at slowest setting, but I had to move it pretty much down
 93the scale (so that framerate option barely matters). I also noticed that
 94camera after first powering up produces frames slightly faster than during
 95consecutive uses. All this means that if you use 352x288 (which is
 96default), be warned - you may encounter broken picture on first connect;
 97try to adjust brightness - brighter image is slower, so USB will be able
 98to send all data. However if you regularly use Model 2 cameras you may
 99prefer 176x144 which makes perfectly good I420, with no scaling and
100lesser demands on USB (300 Kbits per second, or 26 frames per second).
102Another strange effect of 352x288 mode is the fine vertical grid visible
103on some colored surfaces. I am sure it is caused by me not understanding
104what the camera is trying to say. Blame trade secrets for that.
106The camera that I had also has a hardware quirk: if disconnected,
107it needs few minutes to "relax" before it can be plugged in again
108(poorly designed USB processor reset circuit?)
110[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
111observed this particular flaw in it.]
113Model 2 camera can be programmed for very high sensitivity (even starlight
114may be enough), this makes it convenient for tinkering with. The driver
115code has enough comments to help a programmer to tweak the camera
116as s/he feels necessary.
120- A supported IBM PC (C-it) camera (model 1 or 2)
122- A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)
124- A Video4Linux compatible frame grabber program such as xawtv.
128You need to compile the driver only if you are a developer
129or if you want to make changes to the code. Most distributions
130precompile all modules, so you can go directly to the next
131section "HOW TO USE THE DRIVER".
133The ibmcam driver uses usbvideo helper library (module),
134so if you are studying the ibmcam code you will be led there.
136The driver itself consists of only one file in usb/ directory:
137ibmcam.c. This file is included into the Linux kernel build
138process if you configure the kernel for CONFIG_USB_IBMCAM.
139Run "make xconfig" and in USB section you will find the IBM
140camera driver. Select it, save the configuration and recompile.
144I recommend to compile driver as a module. This gives you an
145easier access to its configuration. The camera has many more
146settings than V4L can operate, so some settings are done using
147module options.
149To begin with, on most modern Linux distributions the driver
150will be automatically loaded whenever you plug the supported
151camera in. Therefore, you don't need to do anything. However
152if you want to experiment with some module parameters then
153you can load and unload the driver manually, with camera
154plugged in or unplugged.
156Typically module is installed with command 'modprobe', like this:
158# modprobe ibmcam framerate=1
160Alternatively you can use 'insmod' in similar fashion:
162# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
164Module can be inserted with camera connected or disconnected.
166The driver can have options, though some defaults are provided.
168Driver options: (* indicates that option is model-dependent)
170Name            Type            Range [default] Example
171--------------  --------------  --------------  ------------------
172debug           Integer         0-9 [0]         debug=1
173flags           Integer         0-0xFF [0]      flags=0x0d
174framerate       Integer         0-6 [2]         framerate=1
175hue_correction  Integer         0-255 [128]     hue_correction=115
176init_brightness Integer         0-255 [128]     init_brightness=100
177init_contrast   Integer         0-255 [192]     init_contrast=200
178init_color      Integer         0-255 [128]     init_color=130
179init_hue        Integer         0-255 [128]     init_hue=115
180lighting        Integer         0-2* [1]        lighting=2
181sharpness       Integer         0-6* [4]        sharpness=3
182size            Integer         0-2* [2]        size=1
184Options for Model 2 only:
186Name            Type            Range [default] Example
187--------------  --------------  --------------  ------------------
188init_model2_rg  Integer         0..255 [0x70]   init_model2_rg=128
189init_model2_rg2 Integer         0..255 [0x2f]   init_model2_rg2=50
190init_model2_sat Integer         0..255 [0x34]   init_model2_sat=65
191init_model2_yb  Integer         0..255 [0xa0]   init_model2_yb=200
193debug           You don't need this option unless you are a developer.
194                If you are a developer then you will see in the code
195                what values do what. 0=off.
197flags           This is a bit mask, and you can combine any number of
198                bits to produce what you want. Usually you don't want
199                any of extra features this option provides:
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.
231framerate       This setting controls frame rate of the camera. This is
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.
238hue_correction  This highly optional setting allows to adjust the
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.
248init_brightness These settings specify _initial_ values which will be
249init_contrast   used to set up the camera. If your V4L application has
250init_color      its own controls to adjust the picture then these
251init_hue        controls will be used too. These options allow you to
252                preconfigure the camera when it gets connected, before
253                any V4L application connects to it. Good for webcams.
255init_model2_rg  These initial settings alter color balance of the
256init_model2_rg2 camera on hardware level. All four settings may be used
257init_model2_sat to tune the camera to specific lighting conditions. These
258init_model2_yb  settings only apply to Model 2 cameras.
260lighting        This option selects one of three hardware-defined
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.
269sharpness       This option controls smoothing (noise reduction)
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.
276size            This setting chooses one of several image sizes that are
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:
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)
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.
299For more information and the Troubleshooting FAQ visit this URL:
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?
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).
315- Some flavors of Model 4 NetCameras produce only compressed video
316  streams, and I don't know how to decode them.
320The code is based in no small part on the CPiA driver by Johannes Erdfelt,
321Randy Dunlap, and others. Big thanks to them for their pioneering work on that
322and the USB stack.
324I also thank John Lightsey for his donation of the Veo Stingray camera.