| 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://xirlinkwebcam.sourceforge.net, |
| 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 |
| |
| 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 |
| size Integer 0-2* [2] size=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. |
| FLAGS_NO_DECODING 128 This flag turns the video stream |
| decoder off, and dumps the raw |
| Isoc data from the camera into |
| the reading process. Useful to |
| developers, but not to users. |
| |
| 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. |
| |
| size This setting chooses one of several image sizes that are |
| supported by this driver. Cameras may support more, but |
| it's difficult to reverse-engineer all formats. |
| Following video sizes are supported: |
| |
| size=0 128x96 (Model 1 only) |
| size=1 160x120 |
| size=2 176x144 |
| size=3 320x240 (Model 2 only) |
| size=4 352x240 (Model 2 only) |
| size=5 352x288 |
| size=6 640x480 (Model 3 only) |
| |
| The 352x288 is the native size of the Model 1 sensor |
| array, so it's the best resolution the camera can |
| yield. The best resolution of Model 2 is 176x144, and |
| larger images are produced by stretching the bitmap. |
| Model 3 has sensor with 640x480 grid, and it works too, |
| but the frame rate will be exceptionally low (1-2 FPS); |
| it may be still OK for some applications, like security. |
| Choose the image size you need. The smaller image can |
| support faster frame rate. Default is 352x288. |
| |
| For more information and the Troubleshooting FAQ visit this URL: |
| |
| http://www.linux-usb.org/ibmcam/ |
| |
| WHAT NEEDS TO BE DONE: |
| |
| - 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? |
| |
| - 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). |
| |
| - Some flavors of Model 4 NetCameras produce only compressed video |
| streams, and I don't know how to decode them. |
| |
| 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. |
| |
| I also thank John Lightsey for his donation of the Veo Stingray camera. |