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 details and pictures.
  33This very chipset ("X Chip", as marked at the factory)
  34is used in several other cameras, and they are supported
  35as well:
  37- IBM NetCamera
  38- Veo Stingray
  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.
  46Xirlink now manufactures new cameras which are somewhat different.
  47In particular, following models [FCC ID] belong to that category:
  49XVP300 [KSX-X9903]
  50XVP600 [KSX-X9902]
  51XVP610 [KSX-X9902]
  53(see 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).
  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.
  67Tell me more about all that "model" business
  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.
  77Quirks of Model 2 cameras:
  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.
  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).
 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.
 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?)
 109[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
 110observed this particular flaw in it.]
 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.
 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.
 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".
 132The ibmcam driver uses usbvideo helper library (module),
 133so if you are studying the ibmcam code you will be led there.
 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.
 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.
 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.
 155Typically module is installed with command 'modprobe', like this:
 157# modprobe ibmcam framerate=1
 159Alternatively you can use 'insmod' in similar fashion:
 161# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
 163Module can be inserted with camera connected or disconnected.
 165The driver can have options, though some defaults are provided.
 167Driver options: (* indicates that option is model-dependent)
 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
 183Options for Model 2 only:
 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
 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.
 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:
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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:
 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.
 298For more information and the Troubleshooting FAQ visit this URL:
 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.
 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.
 323I also thank John Lightsey for his donation of the Veo Stingray camera.
 324 kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.