IBM C-it USB Camera Driver for Linux
IBM C-it USB Camera Driver for Linux |
|
|
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.
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.
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 |
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.
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.
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.
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:To clarify, he refers to this patch inBefore 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 unknownlsmod 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=352x240dmesg:
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
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.
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.
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.
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):
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.
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 :-(
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.
| 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 | - |
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.
There are no separators or markers of lines; the only marker is the frame marker (see above).
Figure 5. 320x240 and above data formats of Models 2 and 4.
Figure 6. 128x96 data format of Model 4 camera.
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.
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.
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).
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:
| 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.