ibmcam.txt

Linux Kernel 2.6.9 for OMAP1710

README for Linux device driver for the IBM "C-It" USB video camera

INTRODUCTION:

This driver does not use all features known to exist in
the IBM camera. However most of needed features work well.

This driver was developed using logs of observed USB traffic
which was produced by standard Windows driver (c-it98.sys).
I did not have data sheets from Xirlink.

Video formats:
      128x96  [model 1]
      176x144
      320x240 [model 2]
      352x240 [model 2]
      352x288
Frame rate: 3 - 30 frames per second (FPS)
External interface: USB
Internal interface: Video For Linux (V4L)
Supported controls:
- by V4L: Contrast,  Brightness, Color, Hue
- by driver options: frame rate, lighting conditions, video format,
                     default picture settings, sharpness.

SUPPORTED CAMERAS:

Xirlink "C-It" camera, also known as "IBM PC Camera".
The device uses proprietary ASIC (and compression method);
it is manufactured by Xirlink. See http://www.xirlink.com/
http://www.ibmpccamera.com or http://www.c-itnow.com/ for
details and pictures.

This very chipset ("X Chip", as marked at the factory)
is used in several other cameras, and they are supported
as well:

- IBM NetCamera
- Veo Stingray

The Linux driver was developed with camera with following
model number (or FCC ID): KSX-XVP510. This camera has three
interfaces, each with one endpoint (control, iso, iso). This
type of cameras is referred to as "model 1". These cameras are
no longer manufactured.

Xirlink now manufactures new cameras which are somewhat different.
In particular, following models [FCC ID] belong to that category:

XVP300 [KSX-X9903]
XVP600 [KSX-X9902]
XVP610 [KSX-X9902]

(see http://www.xirlink.com/ibmpccamera/ for updates, they refer
to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
These cameras have two interfaces, one endpoint in each (iso, bulk).
Such type of cameras is referred to as "model 2". They are supported
(with exception of 352x288 native mode).

Some IBM NetCameras (Model 4) are made to generate only compressed
video streams. This is great for performance, but unfortunately
nobody knows how to decompress the stream :-( Therefore, these
cameras are *unsupported* and if you try to use one of those, all
you get is random colored horizontal streaks, not the image!
If you have one of those cameras, you probably should return it
to the store and get something that is supported.

Tell me more about all that "model" business
--------------------------------------------

I just invented model numbers to uniquely identify flavors of the
hardware/firmware that were sold. It was very confusing to use
brand names or some other internal numbering schemes. So I found
by experimentation that all Xirlink chipsets fall into four big
classes, and I called them "models". Each model is programmed in
its own way, and each model sends back the video in its own way.

Quirks of Model 2 cameras:
-------------------------

Model 2 does not have hardware contrast control. Corresponding V4L
control is implemented in software, which is not very nice to your
CPU, but at least it works.

This driver provides 352x288 mode by switching the camera into
quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
this mode to 10 frames per second or less, in ideal conditions on
the bus (USB is shared, after all). The frame rate
has to be programmed very conservatively. Additional concern is that
frame rate depends on brightness setting; therefore the picture can
be good at one brightness and broken at another! I did not want to fix
the frame rate at slowest setting, but I had to move it pretty much down
the scale (so that framerate option barely matters). I also noticed that
camera after first powering up produces frames slightly faster than during
consecutive uses. All this means that if you use 352x288 (which is
default), be warned - you may encounter broken picture on first connect;
try to adjust brightness - brighter image is slower, so USB will be able
to send all data. However if you regularly use Model 2 cameras you may
prefer 176x144 which makes perfectly good I420, with no scaling and
lesser demands on USB (300 Kbits per second, or 26 frames per second).

Another strange effect of 352x288 mode is the fine vertical grid visible
on some colored surfaces. I am sure it is caused by me not understanding
what the camera is trying to say. Blame trade secrets for that.

The camera that I had also has a hardware quirk: if disconnected,
it needs few minutes to "relax" before it can be plugged in again
(poorly designed USB processor reset circuit?)

[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
observed this particular flaw in it.]

Model 2 camera can be programmed for very high sensitivity (even starlight
may be enough), this makes it convenient for tinkering with. The driver
code has enough comments to help a programmer to tweak the camera
as s/he feels necessary.

WHAT YOU NEED:

- A supported IBM PC (C-it) camera (model 1 or 2)

- A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)

- A Video4Linux compatible frame grabber program such as xawtv.
  
HOW TO COMPILE THE DRIVER:

You need to compile the driver only if you are a developer
or if you want to make changes to the code. Most distributions
precompile all modules, so you can go directly to the next
section "HOW TO USE THE DRIVER".

The ibmcam driver uses usbvideo helper library (module),
so if you are studying the ibmcam code you will be led there.

The driver itself consists of only one file in usb/ directory:
ibmcam.c. This file is included into the Linux kernel build
process if you configure the kernel for CONFIG_USB_IBMCAM.
Run "make xconfig" and in USB section you will find the IBM
camera driver. Select it, save the configuration and recompile.

HOW TO USE THE DRIVER:

I recommend to compile driver as a module. This gives you an
easier access to its configuration. The camera has many more
settings than V4L can operate, so some settings are done using
module options.

To begin with, on most modern Linux distributions the driver
will be automatically loaded whenever you plug the supported
camera in. Therefore, you don't need to do anything. However
if you want to experiment with some module parameters then
you can load and unload the driver manually, with camera
plugged in or unplugged.

Typically module is installed with command 'modprobe', like this:

# modprobe ibmcam framerate=1

Alternatively you can use 'insmod' in similar fashion:

# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1