path: root/Documentation/usb/ibmcam.txt

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:

IBM "C-It" camera, also known as "Xirlink 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.

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).

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

Model 2 does not have hardware contrast control. Corresponding V4L
control is not used at the moment. It may be possible to implement
contrast control in software, at cost of extra processor cycles.

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 videosize=2 (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 videosize=1 which makes perfectly good I420, with no scaling and
lesser demands on USB (300 Kbits per second, or 26 frames per second).

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?)

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 driver consists of two files in usb/ directory:
ibmcam.c and ibmcam.h These files are 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.

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

Module can be inserted with camera connected or disconnected.

The driver can have options, though some defaults are provided.

Driver options: (* indicates that option is model-dependent)

Name            Type            Range [default] Example
--------------  --------------  --------------  ------------------
debug           Integer         0-9 [0]         debug=1
flags           Integer         0-0xFF [0]      flags=0x0d
framerate       Integer         0-6 [2]         framerate=1
hue_correction  Integer         0-255 [128]     hue_correction=115
init_brightness Integer         0-255 [128]     init_brightness=100
init_contrast   Integer         0-255 [192]     init_contrast=200
init_color      Integer         0-255 [128]     init_color=130
init_hue        Integer         0-255 [128]     init_hue=115
lighting        Integer         0-2* [1]        lighting=2
sharpness       Integer         0-6* [4]        sharpness=3
videosize       Integer         0-2* [2]        videosize=1

Options for Model 2 only:

Name            Type            Range [default] Example
--------------  --------------  --------------  ------------------
init_model2_rg  Integer         0..255 [0x70]   init_model2_rg=128
init_model2_rg2 Integer         0..255 [0x2f]   init_model2_rg2=50
init_model2_sat Integer         0..255 [0x34]   init_model2_sat=65
init_model2_yb  Integer         0..255 [0xa0]   init_model2_yb=200

debug           You don't need this option unless you are a developer.
                If you are a developer then you will see in the code
                what values do what. 0=off.

flags           This is a bit mask, and you can combine any number of
                bits to produce what you want. Usually you don't want
                any of extra features this option provides:

                FLAGS_RETRY_VIDIOCSYNC  1  This bit allows to retry failed
                                           VIDIOCSYNC ioctls without failing.
                                           Will work with xawtv, will not
                                           with xrealproducer. Default is
                                           not set.
                FLAGS_MONOCHROME        2  Activates monochrome (b/w) mode.
                FLAGS_DISPLAY_HINTS     4  Shows colored pixels which have
                                           magic meaning to developers.
                FLAGS_OVERLAY_STATS     8  Shows tiny numbers on screen,
                                           useful only for debugging.
                FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers.
                FLAGS_SEPARATE_FRAMES   32 Shows each frame separately, as
                                           it was received from the camera.
                                           Default (not set) is to mix the
                                           preceding frame in to compensate
                                           for occasional loss of Isoc data
                                           on high frame rates.
                FLAGS_CLEAN_FRAMES      64 Forces "cleanup" of each frame
                                           prior to use; relevant only if
                                           FLAGS_SEPARATE_FRAMES is set.
                                           Default is not to clean frames,
                                           this is a little faster but may
                                           produce flicker if frame rate is
                                           too high and Isoc data gets lost.

framerate       This setting controls frame rate of the camera. This is
                an approximate setting (in terms of "worst" ... "best")
                because camera changes frame rate depending on amount
                of light available. Setting 0 is slowest, 6 is fastest.
                Beware - fast settings are very demanding and may not
                work well with all video sizes. Be conservative.

hue_correction  This highly optional setting allows to adjust the
                hue of the image in a way slightly different from
                what usual "hue" control does. Both controls affect
                YUV colorspace: regular "hue" control adjusts only
                U component, and this "hue_correction" option similarly
                adjusts only V component. However usually it is enough
                to tweak only U or V to compensate for colored light or
                color temperature; this option simply allows more
                complicated correction when and if it is necessary.

init_brightness These settings specify _initial_ values which will be
init_contrast   used to set up the camera. If your V4L application has
init_color      its own controls to adjust the picture then these
init_hue        controls will be used too. These options allow you to
                preconfigure the camera when it gets connected, before
                any V4L application connects to it. Good for webcams.

init_model2_rg  These initial settings alter color balance of the
init_model2_rg2 camera on hardware level. All four settings may be used
init_model2_sat to tune the camera to specific lighting conditions. These
init_model2_yb  settings only apply to Model 2 cameras.

lighting        This option selects one of three hardware-defined
                photosensitivity settings of the camera. 0=bright light,
                1=Medium (default), 2=Low light. This setting affects
                frame rate: the dimmer the lighting the lower the frame
                rate (because longer exposition time is needed). The
                Model 2 cameras allow values more than 2 for this option,
                thus enabling extremely high sensitivity at cost of frame
                rate, color saturation and imaging sensor noise.

sharpness       This option controls smoothing (noise reduction)
                made by camera. Setting 0 is most smooth, setting 6
                is most sharp. Be aware that CMOS sensor used in the
                camera is pretty noisy, so if you choose 6 you will
                be greeted with "snowy" image. Default is 4. Model 2
                cameras do not support this feature.

videosize       This setting chooses one if three image sizes that are
                supported by this driver. Camera supports more, but
                it's difficult to reverse-engineer all formats.
                Following video sizes are supported:

                videosize=0     128x96  (Model 1 only)
                videosize=1     176x144
                videosize=2     352x288
                videosize=3     320x240 (Model 2 only)
                videosize=4     352x240 (Model 2 only)

                The last one (352x288) is the native size of the sensor
                array, so it's the best resolution camera (Model 1) can
                yield. The best resolution of Model 2 is 176x144, and
                larger images are produced by stretching the bitmap.
                Choose the image size you need. The smaller image can
                support faster frame rate. Default is 352x288.

WHAT NEEDS TO BE DONE:

- The box freezes if camera is unplugged after being used (OHCI).
  Workaround: remove usb-ohci module first.
- On occasion camera (model 1) does not start properly (xawtv reports
  errors), or camera produces negative image (funny colors.)
  Workaround: reload the driver module. Reason: [1].
- The button on the camera is not used. I don't know how to get to it.
  I know now how to read button on Model 2, but what to do with it?

[1]
- Camera reports its status back to the driver; however I don't know
  what returned data means. If camera fails at some initialization
  stage then something should be done, and I don't do that because
  I don't even know that some command failed. This is mostly Model 1
  concern because Model 2 uses different commands which do not return
  status (and seem to complete successfully every time).

VIDEO SIZE AND IMAGE SIZE

Camera produces picture X by Y pixels. This is camera-specific and can be
altered by programming the camera accordingly. This image is placed onto
larger (or equal) area W by H, this is V4L image. At this time the driver
uses V4L image size (W by H) 352x288 pixels because many programs (such
as xawtv) expect quite specific sizes and don't want to deal with arbitrary,
camera-specific sizes. However this approach "hides" real image size, and
application always sees the camera as producing only 352x288 image. It is
possible to change the V4L image size to 128x96, and then if camera is
switched to 128x96 mode then xawtv will correctly accept this image size. But
many other popular sizes (such as 176x144) will not be welcomed. This is the
reason why all camera images are at this time placed onto 352x288 "canvas",
and size of that canvas (V4L) is reported to applications. It will be easy
to add options to control the canvas size, but it will be application-
specific because not all applications are ready to work with variety of
camera-specific sizes.

CREDITS:

The code is based in no small part on the CPiA driver by Johannes Erdfelt,
Randy Dunlap, and others. Big thanks to them for their pioneering work on that
and the USB stack.