IBM C-it USB Camera Driver for Linux


Photo of the camera

1. Manufacturer of the camera

The camera is apparently manufactured by Xirlink. IBM actively resells these cameras under brand name "IBM PC CameraTM". Xirlink itself sold cameras under brand name "C-It CameraTM", but I guess now they shifted from manufacturing and sales to pure design and licensing. Xirlink's own Web site was not updated in many months, and they don't even offer latest Windows drivers there.

2. Maintainers and Projects

The most current version of the driver is in the Linux kernel tree.

Iouri Atiounkine created a new project at SourceForge as a place for development of driver for new webcams based on Veo/Xirlink chipsets.

3. Known cameras

There are many versions of C-It cameras. Below I show what models have been spotted in the wild, and which of those are supported:

Table 1. Supported cameras and their identification.
Model number
Factory codes
Vendor ID
Product ID
USB revision
Comments
Sold as
Model 1 KSX-XVP510
0x0545
0x8080
0.02
Oldest model - hard to initialize Xirlink C-It
Model 2 KSX-X9903
0x0545
0x8080
3.0a
Old, cheaper model Xirlink C-It
Model 3 KSX-X9902
0x0545
0x8080
3.01
New, up to 640x480* IBM PC Camera
Model 4 (Note) P/N 33L4889
0x0545
0x8002
3.0a
Variant of model 2 IBM NetCamera
Model 2 (not seen)
0x0545
0x800c
3.0a
Needs a hack Veo Stingray
Model 4 (not seen)
0x0545
0x800d
3.0a
New, up to 640x480, needs a hack Veo Stingray
N/A (not seen)
0x0545
0x810a
5.00
See note Veo Advanced Connect
N/A (not seen)
0x0545
0x8333
???
Compressed data only, see note Veo Stingray
N/A FCC ID 69A2S1AX036025
0x0545
0x888d
12.03
Webcam + still image combo Evision123 Digital Camera
Contents of /proc/bus/usb/devices

Factory codes are printed on a sticker on the bottom of the camera. There may be more than one factory code for each supported model of the camera because these codes reflect not only firmware changes but also insignificant (from software point of view) changes in hardware, plastic, packaging etc. The most reliable way to find out what camera you got is to plug it into Linux box and type

$ cat /proc/bus/usb/devices

You may see output similar to one shown to the right. It shows descriptor information of Model 1 camera. The Vendor ID is 0x0545, the Product ID is 0x8080 and Revision=0x0002 (often referred to just as 0.02). Following lines describe all configurations of the camera (it has only one), all interfaces of the camera (three, numbered 0, 1 and 2), alternate settings of all interfaces and all endpoints in each alternate setting.

 Important Note: 

The driver does not report true colors with Model 3 cameras. This is caused by my lack of understanding how the colors are encoded. There is a patch floating around that fixes the problem, and there is an effort underway to merge it into the kernel tree.

 Important Note: 

Some IBM NetCameras are not supported. They simply do not work. They share the same USB identification (0545:8002:030A), but something in their firmware changed. I had the earliest Model 4 camera, and it worked. I still get reports from people; they say that they have Model 4 cameras, and these cameras work for them.

Recently (as of July 2001) I started receiving messages from people who got NetCameras and they do not work at all! I went out and bought one such camera myself. Experiments show that this camera sends compressed data. Earlier versions of this very camera sent uncompressed data. I do not know how to decode this data, and as such I can't do anything with it.

This problem occurs with both "NetCamera" and "NetCamera Pro". The former is a cheaper model, usually sold for USD $40-$50. It produces the "snowy" image - random colored streaks, they apparently represent compressed image. On startup one can see part of the complete image, and then it gets replaced with that "noise". The other camera — NetCamera Pro — is more expensive and may have an RCA jack for digitizing some external audio feed. I do not have this camera. People who do all report that the camera simply does not work, streams nothing and the screen is dark.

So here is the advice: STAY AWAY FROM IBM NETCAMERAS until the driver can be written. Buy instead another camera, that is based on a chipset that is documented and supported in Linux. I think, all new NetCameras that you can now buy are of that non-working variety. I got the camera P/N 22P5084, and it does not work. The NetCamera Pro has a very similar part number.

This driver for IBM cameras is not intended to endorse purchase of IBM/Xirlink cameras anyway. It is only a last hope for people who already have this camera and have no option of returning it to the store. This driver is based on reverse-engineering of the communication protocol and is full of guesswork. Do not buy any of IBM/Xirlink cameras by choice.

Veo Stingray support

This camera suddenly appeared on the market around October 2001. It seems to be based on the very same Xirlink chipset that is used in many IBM PC cameras.

Veo Stingray with ProductID=0x800D

The existing ibmcam driver apparently supports this camera; only one minor addition needs to be done - and that will be soon in the Linux kernel. Here is the success story I received:

Today I bought a Veo Stingray. It was only $20 and looked SO much like the Xirlink/IBMCam that I was sure it was another rebrand.

Well, it is :-)

The product id of the camera is not one listed on your page, however. It is 0x800d. I took my stock 2.4.12 kernel, and changed the product id of the IBM NetCamera to accept this new camera...

/usr/src/linux/drivers/usb/ibmcam.c:
#define NETCAM_PRODUCT_ID   0x800d   /* Quick hack for Veo Stingray */
                                ^^

I recompiled, reinstalled the module, replugged the camera... the driver picked it up right away, and I ran xawtv and had a picture immediately!

According to your website, the output of /proc/bus/usb/devices is useful, so I have included it at the end.

T:  Bus=01 Lev=00 Prnt=00 Port=00 Cnt=00 Dev#=  1 Spd=12  MxCh= 2
B:  Alloc=  0/900 us ( 0%), #Int=  0, #Iso=  0
D:  Ver= 1.00 Cls=09(hub  ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
P:  Vendor=0000 ProdID=0000 Rev= 0.00
S:  Product=USB UHCI-alt Root Hub
S:  SerialNumber=fca0
C:* #Ifs= 1 Cfg#= 1 Atr=40 MxPwr=  0mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl=255ms
T:  Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  5 Spd=12  MxCh= 0
D:  Ver= 1.01 Cls=ff(vend.) Sub=ff Prot=ff MxPS= 8 #Cfgs=  1
P:  Vendor=0545 ProdID=800d Rev= 3.0a
S:  Product=USB IMAGING DEVICE
C:* #Ifs= 2 Cfg#= 1 Atr=80 MxPwr=500mA
I:  If#= 0 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=ff Prot=ff Driver=ibmcam
E:  Ad=81(I) Atr=01(Isoc) MxPS=   0 Ivl=  1ms
I:  If#= 0 Alt= 1 #EPs= 1 Cls=ff(vend.) Sub=ff Prot=ff Driver=ibmcam
E:  Ad=81(I) Atr=01(Isoc) MxPS=1022 Ivl=  1ms
I:  If#= 1 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=ff Prot=ff Driver=(none)
E:  Ad=82(I) Atr=02(Bulk) MxPS=   0 Ivl=  1ms
I:  If#= 1 Alt= 1 #EPs= 1 Cls=ff(vend.) Sub=ff Prot=ff Driver=(none)
E:  Ad=82(I) Atr=02(Bulk) MxPS=1022 Ivl=  1ms

I don't have Veo Stingray camera, so I can not verify this observation. Hopefully, the camera will work for you.

Veo Stingray with ProductID=0x800C

This appears to be a repackaged Model 2 camera.
I have in fact gotten a Veo Stingray with the Product ID of 0x800c to work. I just modified the IBM_PRODUCT_ID define to the appropriate ID code, recompiled the driver and I ran a "modprobe ibmcam", and I was off running in xawtv. Nothing else special to do. Anyways, here's the other info for you:

Before modprobing the driver:

usb.c: USB device 3 (vend/prod 0x545/0x800c) is not claimed by any active driver.

uname:

Linux athlon 2.4.17 #7 Mon Jan 21 14:16:30 PST 2002 i686 unknown

lsmod output:

ibmcam                 39568   0
usbvideo               22144   0  [ibmcam]
videodev                2976   1  [usbvideo]
smbfs                  31728   1  (autoclean)
emu10k1                53648   1  (autoclean)
ac97_codec              9376   0  (autoclean) [emu10k1]  
sound                  53952   0  (autoclean) [emu10k1]
soundcore               3568   7  (autoclean) [emu10k1 sound]
NVdriver              816640  14  (autoclean)
vmnet                  17024   4
vmmon                  17920   0  (unused)
parport_pc             25344   1  (autoclean)
lp                      6432   0  (autoclean)
parport                23008   1  (autoclean) [parport_pc lp]
8139too                13280   1
vfat                    9648   1  (autoclean)
fat                    30272   0  (autoclean) [vfat]

/var/log/messages:

Jan 27 00:44:25 athlon kernel: hub.c: USB new device connect on bus2/1, assigned device number 4
Jan 27 00:44:25 athlon kernel: ibmcam.c: IBM USB camera found (model 2, rev. 0x030a)
Jan 27 00:44:25 athlon kernel: usbvideo.c: ibmcam on /dev/video0: canvas=352x240 videosize=352x240

dmesg:

hub.c: USB new device connect on bus2/1, assigned device number 4
ibmcam.c: IBM USB camera found (model 2, rev. 0x030a)
usbvideo.c: ibmcam on /dev/video0: canvas=352x240 videosize=352x240
To clarify, he refers to this patch in linux/drivers/usb/ibmcam.c:
--- ibmcam.c.2.4.18	Sun Jan 27 01:32:59 2002
+++ ibmcam.c	Sun Jan 27 01:33:54 2002
@@ -34,7 +34,7 @@
 #include "usbvideo.h"
 
 #define IBMCAM_VENDOR_ID	0x0545
-#define IBMCAM_PRODUCT_ID	0x8080
+#define IBMCAM_PRODUCT_ID	0x800c	/* Veo Stingray 0x800c flavor */
 #define NETCAM_PRODUCT_ID	0x8002	/* IBM NetCamera, close to model 2 */
 
 #define MAX_IBMCAM		4	/* How many devices we allow to connect */
This is NOT a complete solution because it breaks other IBM cameras. However if you have only Veo Stingray and don't care about other cameras then go ahead and make the change. I will submit a better patch to the USB stack soon.

Veo Stingray 0x0545:0x8333

Thanks to Andrew Robinson for the following observation:
I thought you might do well to post one more piece of information, though. The Veo Stingray camera ID:Model 0x0545:0x8333 is a new variant which does not appear to work with the old driver at all. Hoping that it might have the same data format, I did a partial reverse engineering job on it, and wrote a test driver for it. I was able to get it to send the isochronous data stream back to the computer and save it to disk. It sends a 128 byte header of some kind, followed by numbered frames of data from 0x80 to 0xBF, repetitively. Each frame appears to be terminated by a 0xFF. Since the frames are variable length, it is also clear that the data is compressed. I tried 640x480 and 352x288, but they are both compressed. If you know of anyone who might be able to recognize the format, I could send the test driver on to them or perhaps a sample of the data stream. I'm afraid my experience with compressed data streams is insufficient to proceed any further and I don't know if there is any way to turn the compression off in the camera itself.

4. Internals of the camera

Here you can see what's inside of the camera (model 1 shown). It consists of two PCBs - sensor board and the processor board. Lens is mounted in a plastic housing secured to the sensor board with two screws.
Sample image 352x288

5. Theory of operation

5.1. Command set specifications

Some people asked for specs but manufacturer failed to respond. The Linux driver, therefore, has to rely on observations of USB traffic generated by Windows driver. The camera uses many vendor-defined control commands, this makes it hard to understand how to control the device. However the most popular modes seem to work; this makes the camera fully usable on Linux boxen.

5.2. ViCETM compression

This is some kind of video compression that allows to improve frame rate or image size. USB bandwidth is limited to 12 Mbps; however cameras generate huge amounts of data. As far as I know, there is no published specs on ViCETM. I do not work at this time on reverse-engineering of that compression, and most likely I will not have time to do that in nearest future. The camera works “good enough” already, so ViCETM is not absolutely required, though it would be nice to have.

Note: Apparently ViCETM is supported only on some image sizes, usually only 176x144 - probably because of insufficient performance of internal DSP to work on larger images. However at such small image sizes the compression is not that necessary. So there is little advantage of having ViCETM.

5.3. Device descriptors and interfaces

5.4. Initialization sequence

5.4.1. Overview

Complicated and undocumented. Consult the driver source for details. All initialization and camera control is done via control transfers over the default (control) pipe. Most OUT commands do not use the data stage, but IN commands usually return some data. Nature of returned data is not known for sure, however observations hint that some returned fields carry white balance information in Model 4 cameras.

The bulk of initialization and control is done with OUT transfers. Three fields are defined in those control requests, besides the data buffer (which is not used):

  1. Request (one byte). Usually 0 or 1, used to determine the direction of the transfer.
  2. Value (2 bytes). Carries either a fixed or a programmable data.
  3. Index (2 bytes). Classifies the transfer. Generally, USB device can use any field for any purpose, but these cameras appear to follow the general idea of using index field for directing the value to appropriate receiver.

Those are fairly low-level transfers. Camera uses several of such transfers grouped together in packets. Some transfers make up a framing of the packet, other (inner) transfers carry data. One packet usually carries out one high-level adjustment.

The structure of packets is only my best guess, but it seems reasonably correct for models 1, 2 and 3. Model 4 has some packet structure too, but I can't figure it out. Looks like each packet has variable format and variable length, and the framing of packets in this camera is very fluid, defying analysis. Therefore I only separated one packet that is known to adjust gain in color channels and affect hue, in some way.

5.4.2. RCA Connector on some Model 3 cameras (apparently IBM PC Camera ProTM)

Some Model 3 cameras are equipped with an RCA connector which can be used to feed a standard video NTSC signal into the camera. Therefore, such camera can digitize either image produced by internal sensor or an image from an external source, such as remote CCTV camera, VCR or TV set.

I didn't have such camera. However at least one person has it, so he captured some debugging data that was enough to activate this connector and see the externally provided image. This mode may be enabled with an option init_model3_input. However this is still very experimental code. It supports only one image size, and the image is inverted (bottom up) because the standard Model 3 data format produces scan lines in reverse order, so some fix is required for that. I do not actively work on this issue at this time because it's tough to play with datastream decoders without having the camera.

22.10.2001: I have the camera now - but not the time to work on it :-(

5.5. Uncompressed datastreams

The camera supports many standards, including CIF, SIF and QCIF video formats, not exceeding 640x480 natively. Larger image formats (like 704 x 576) that may be advertised on the box are just smaller images blown up for marketing purposes. Linux driver does not scale the image up - this, if needed, can always be done in userspace.

5.5.1. Frame markers

Camera sends continuous stream of frames. Each frame is prefixed with several bytes of frame marker (which is not part of frame data). The exact marker value varies between different frame sizes and can be used to correctly parse the frame.

Table 2. Frame markers for different video sizes.
Video size Model 1 Model 2 Model 3 Model 4
Uncompressed Best quality Best frame rate
128x96 00 FF 00 06 - - - - 00 FF
160x120 - - - - - 00 FF
176x144 00 FF 00 0E 00 FF ... 00 FF 02 0A 00 FF 02 CA 00 FF 02 EA 00 FF
320x240 - 00 FF 00 FF 02 08 00 FF 02 28 00 FF 02 68 00 FF
352x240 - 00 FF - - - -
352x288 00 FF 00 00 00 FF - - - 00 FF
640x480 - - 00 FF 03 08 00 FF 03 28 00 FF 03 68 -

5.5.2. Encoding methods

IBM/Xirlink cameras use several wildly different encoding methods. Some cameras (like model 2) use YUV encoding on one set of image sizes and RGB on other set. The driver contains appropriate decoders for known encodings. The output of the driver is currently only RGB24. The usbvideo project allows drivers to offer output in any subset of known video formats; however the Linux driver supports only RGB24 at this time due to large amount of work needed to write and test decoder routines. I don't even have all models of cameras!

Some applications may require one or another video format that may be unsupported by the driver. Voxilla is one such application, it wanted YUV-packed data format and absolutely positively refused to accept RGB24. A small patch to Voxilla fixed that. Generally, a V4L driver can provide output in any number of formats. But it is very difficult to write video conversion code in kernel space, and kernel is not the place for that generic code anyway. So this driver just converts camera-specific format into one of standard formats, RGB24 in this case, and that's it. A V4L client is free to convert it (in userspace) to whatever else it wants.

5.5.3. YUV encoding

Model 1 (YUV) data format.
Figure 4. Model 1 (YUV) data format.

There are no separators or markers of lines; the only marker is the frame marker (see above).

5.5.4. RGB encodings

128x96 mode (model 4 only)
Figure 5. 320x240 and above data formats of Models 2 and 4.

128x96 mode (model 4 only)
Figure 6. 128x96 data format of Model 4 camera.

5.5.5. More on Model 2 encoding

Craig Hadady comments:
I've been playing around with a model 2 camera and have discovered that the data format for resolutions at and above 320x240 may be different than what you have documented. I believe that the pixel array in the CCD is a 'Bayer' array, arranged like this:
GRGRGRGRGR....
BGBGBGBGBGBG....
GRGRGRGRGR....
BGBGBGBGBGBG....
and that the camera sends the data as a line of 'GRGR...' followed by aline of 'BGBG...'. To calculate the RGB value for any given pel, you only 'know' the color at that pel, and must interpolate the other two colors. I hacked 'ibmcam.c', renaming the driver and file as 'ibmcamb.c' to compare the changes. This hack averages neighboring pels on the current and previous lines to linearly interpolate the unknown colors. The results are much improved, even with a simple interpolation. The vertical lines are pretty much gone! The resolution is improved too, because the data is no longer interleaved. Anyway, I hope this helps. It makes my model 2 run better. I think improvements are still possible, but I wanted to let you know what I found ASAP.

5.6. Snapshot button

Cameras have a button that can be polled by software. The driver does not use this feature because of several reasons, such as:

Nevertheless, if someone badly wants this button then it can be reverse-engineered and figured out. I haven't met such person yet :-) I can think of some specialized "camera on a rope"-style industrial application, but none materialized so far, and I wasted no time on that non-issue.

5.7. Colorspace conversion

Here is some useful information about colorspaces and encoding methods:

6. Downloads

Support for all models (1, 2, 3, 4) is included in the driver that ships with Linux kernels starting with 2.4.12.

Previously you had to build the driver from CVS, but now this is not needed (or even recommended).

7. Troubleshooting and contact information

If something does not work you should read this fairly large ibmcam FAQ.

Before reporting a problem you should read file /usr/src/linux/Documentation/usb/ibmcam.txt - this file describes options and known problems with the IBM camera driver that is included into the 2.4 kernel.

If you have a generic USB trouble, such as host controller errors, then visit Linux-USB Web site and there you will find addresses of linux-usb-users mailing list. You can ask questions there.

If you want to email me and report a problem please attach following information to your first email. Otherwise I will need to ask you about some of that data and we both just lose time. So here it is:

  1. The problem itself
  2. Kernel version (run uname -a)
  3. Version (origin) of the IBM camera driver
  4. Output of /sbin/lsmod
  5. Contents of /proc/bus/usb/devices with camera plugged in
  6. Relevant snippet from /var/log/messages from the moment you plug the camera in to the moment you detect an error and stop the test.
  7. Output of xawtv if you use it, or output of other userspace tool that you use to access the camera.
You can reach me at this email address (perform obvious anti-spamming ritual first):

d m i t r i   ( a t )   u s e r s   d o t   s o u r c e f o r g e   d o t   n e t

I will try to help you. I have Model 1, Model 2, Model 3 (with RCA input) and also a Model 4 IBM NetCamera P/N 22P5084 that does not work. I know about NetCameras that do work — and I had one — and I saw a NetCamera Pro at a store (Best Buy). But I do not own any of those two.