1README for Linux device driver for the IBM "C-It" USB video camera 2 3INTRODUCTION: 4 5This driver does not use all features known to exist in 6the IBM camera. However most of needed features work well. 7 8This driver was developed using logs of observed USB traffic 9which was produced by standard Windows driver (c-it98.sys). 10I did not have data sheets from Xirlink. 11 12Video formats: 13 128x96 [model 1] 14 176x144 15 320x240 [model 2] 16 352x240 [model 2] 17 352x288 18Frame rate: 3 - 30 frames per second (FPS) 19External interface: USB 20Internal interface: Video For Linux (V4L) 21Supported controls: 22- by V4L: Contrast, Brightness, Color, Hue 23- by driver options: frame rate, lighting conditions, video format, 24 default picture settings, sharpness. 25 26SUPPORTED CAMERAS: 27 28Xirlink "C-It" camera, also known as "IBM PC Camera". 29The device uses proprietary ASIC (and compression method); 30it is manufactured by Xirlink. See http://xirlinkwebcam.sourceforge.net, 31http://www.ibmpccamera.com, or http://www.c-itnow.com/ for details and pictures. 32 33This very chipset ("X Chip", as marked at the factory) 34is used in several other cameras, and they are supported 35as well: 36 37- IBM NetCamera 38- Veo Stingray 39 40The Linux driver was developed with camera with following 41model number (or FCC ID): KSX-XVP510. This camera has three 42interfaces, each with one endpoint (control, iso, iso). This 43type of cameras is referred to as "model 1". These cameras are 44no longer manufactured. 45 46Xirlink now manufactures new cameras which are somewhat different. 47In particular, following models [FCC ID] belong to that category: 48 49XVP300 [KSX-X9903] 50XVP600 [KSX-X9902] 51XVP610 [KSX-X9902] 52 53(see http://www.xirlink.com/ibmpccamera/ for updates, they refer 54to these new cameras by Windows driver dated 12-27-99, v3005 BETA) 55These cameras have two interfaces, one endpoint in each (iso, bulk). 56Such type of cameras is referred to as "model 2". They are supported 57(with exception of 352x288 native mode). 58 59Some IBM NetCameras (Model 4) are made to generate only compressed 60video streams. This is great for performance, but unfortunately 61nobody knows how to decompress the stream :-( Therefore, these 62cameras are *unsupported* and if you try to use one of those, all 63you get is random colored horizontal streaks, not the image! 64If you have one of those cameras, you probably should return it 65to the store and get something that is supported. 66 67Tell me more about all that "model" business 68-------------------------------------------- 69 70I just invented model numbers to uniquely identify flavors of the 71hardware/firmware that were sold. It was very confusing to use 72brand names or some other internal numbering schemes. So I found 73by experimentation that all Xirlink chipsets fall into four big 74classes, and I called them "models". Each model is programmed in 75its own way, and each model sends back the video in its own way. 76 77Quirks of Model 2 cameras: 78------------------------- 79 80Model 2 does not have hardware contrast control. Corresponding V4L 81control is implemented in software, which is not very nice to your 82CPU, but at least it works. 83 84This driver provides 352x288 mode by switching the camera into 85quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting 86this mode to 10 frames per second or less, in ideal conditions on 87the bus (USB is shared, after all). The frame rate 88has to be programmed very conservatively. Additional concern is that 89frame rate depends on brightness setting; therefore the picture can 90be good at one brightness and broken at another! I did not want to fix 91the frame rate at slowest setting, but I had to move it pretty much down 92the scale (so that framerate option barely matters). I also noticed that 93camera after first powering up produces frames slightly faster than during 94consecutive uses. All this means that if you use 352x288 (which is 95default), be warned - you may encounter broken picture on first connect; 96try to adjust brightness - brighter image is slower, so USB will be able 97to send all data. However if you regularly use Model 2 cameras you may 98prefer 176x144 which makes perfectly good I420, with no scaling and 99lesser demands on USB (300 Kbits per second, or 26 frames per second). 100 101Another strange effect of 352x288 mode is the fine vertical grid visible 102on some colored surfaces. I am sure it is caused by me not understanding 103what the camera is trying to say. Blame trade secrets for that. 104 105The camera that I had also has a hardware quirk: if disconnected, 106it needs few minutes to "relax" before it can be plugged in again 107(poorly designed USB processor reset circuit?) 108 109[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't 110observed this particular flaw in it.] 111 112Model 2 camera can be programmed for very high sensitivity (even starlight 113may be enough), this makes it convenient for tinkering with. The driver 114code has enough comments to help a programmer to tweak the camera 115as s/he feels necessary. 116 117WHAT YOU NEED: 118 119- A supported IBM PC (C-it) camera (model 1 or 2) 120 121- A Linux box with USB support (2.3/2.4; 2.2 w/backport may work) 122 123- A Video4Linux compatible frame grabber program such as xawtv. 124 125HOW TO COMPILE THE DRIVER: 126 127You need to compile the driver only if you are a developer 128or if you want to make changes to the code. Most distributions 129precompile all modules, so you can go directly to the next 130section "HOW TO USE THE DRIVER". 131 132The ibmcam driver uses usbvideo helper library (module), 133so if you are studying the ibmcam code you will be led there. 134 135The driver itself consists of only one file in usb/ directory: 136ibmcam.c. This file is included into the Linux kernel build 137process if you configure the kernel for CONFIG_USB_IBMCAM. 138Run "make xconfig" and in USB section you will find the IBM 139camera driver. Select it, save the configuration and recompile. 140 141HOW TO USE THE DRIVER: 142 143I recommend to compile driver as a module. This gives you an 144easier access to its configuration. The camera has many more 145settings than V4L can operate, so some settings are done using 146module options. 147 148To begin with, on most modern Linux distributions the driver 149will be automatically loaded whenever you plug the supported 150camera in. Therefore, you don't need to do anything. However 151if you want to experiment with some module parameters then 152you can load and unload the driver manually, with camera 153plugged in or unplugged. 154 155Typically module is installed with command 'modprobe', like this: 156 157# modprobe ibmcam framerate=1 158 159Alternatively you can use 'insmod' in similar fashion: 160 161# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1 162 163Module can be inserted with camera connected or disconnected. 164 165The driver can have options, though some defaults are provided. 166 167Driver options: (* indicates that option is model-dependent) 168 169Name Type Range [default] Example 170-------------- -------------- -------------- ------------------ 171debug Integer 0-9 [0] debug=1 172flags Integer 0-0xFF [0] flags=0x0d 173framerate Integer 0-6 [2] framerate=1 174hue_correction Integer 0-255 [128] hue_correction=115 175init_brightness Integer 0-255 [128] init_brightness=100 176init_contrast Integer 0-255 [192] init_contrast=200 177init_color Integer 0-255 [128] init_color=130 178init_hue Integer 0-255 [128] init_hue=115 179lighting Integer 0-2* [1] lighting=2 180sharpness Integer 0-6* [4] sharpness=3 181size Integer 0-2* [2] size=1 182 183Options for Model 2 only: 184 185Name Type Range [default] Example 186-------------- -------------- -------------- ------------------ 187init_model2_rg Integer 0..255 [0x70] init_model2_rg=128 188init_model2_rg2 Integer 0..255 [0x2f] init_model2_rg2=50 189init_model2_sat Integer 0..255 [0x34] init_model2_sat=65 190init_model2_yb Integer 0..255 [0xa0] init_model2_yb=200 191 192debug You don't need this option unless you are a developer. 193 If you are a developer then you will see in the code 194 what values do what. 0=off. 195 196flags This is a bit mask, and you can combine any number of 197 bits to produce what you want. Usually you don't want 198 any of extra features this option provides: 199 200 FLAGS_RETRY_VIDIOCSYNC 1 This bit allows to retry failed 201 VIDIOCSYNC ioctls without failing. 202 Will work with xawtv, will not 203 with xrealproducer. Default is 204 not set. 205 FLAGS_MONOCHROME 2 Activates monochrome (b/w) mode. 206 FLAGS_DISPLAY_HINTS 4 Shows colored pixels which have 207 magic meaning to developers. 208 FLAGS_OVERLAY_STATS 8 Shows tiny numbers on screen, 209 useful only for debugging. 210 FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers. 211 FLAGS_SEPARATE_FRAMES 32 Shows each frame separately, as 212 it was received from the camera. 213 Default (not set) is to mix the 214 preceding frame in to compensate 215 for occasional loss of Isoc data 216 on high frame rates. 217 FLAGS_CLEAN_FRAMES 64 Forces "cleanup" of each frame 218 prior to use; relevant only if 219 FLAGS_SEPARATE_FRAMES is set. 220 Default is not to clean frames, 221 this is a little faster but may 222 produce flicker if frame rate is 223 too high and Isoc data gets lost. 224 FLAGS_NO_DECODING 128 This flag turns the video stream 225 decoder off, and dumps the raw 226 Isoc data from the camera into 227 the reading process. Useful to 228 developers, but not to users. 229 230framerate This setting controls frame rate of the camera. This is 231 an approximate setting (in terms of "worst" ... "best") 232 because camera changes frame rate depending on amount 233 of light available. Setting 0 is slowest, 6 is fastest. 234 Beware - fast settings are very demanding and may not 235 work well with all video sizes. Be conservative. 236 237hue_correction This highly optional setting allows to adjust the 238 hue of the image in a way slightly different from 239 what usual "hue" control does. Both controls affect 240 YUV colorspace: regular "hue" control adjusts only 241 U component, and this "hue_correction" option similarly 242 adjusts only V component. However usually it is enough 243 to tweak only U or V to compensate for colored light or 244 color temperature; this option simply allows more 245 complicated correction when and if it is necessary. 246 247init_brightness These settings specify _initial_ values which will be 248init_contrast used to set up the camera. If your V4L application has 249init_color its own controls to adjust the picture then these 250init_hue controls will be used too. These options allow you to 251 preconfigure the camera when it gets connected, before 252 any V4L application connects to it. Good for webcams. 253 254init_model2_rg These initial settings alter color balance of the 255init_model2_rg2 camera on hardware level. All four settings may be used 256init_model2_sat to tune the camera to specific lighting conditions. These 257init_model2_yb settings only apply to Model 2 cameras. 258 259lighting This option selects one of three hardware-defined 260 photosensitivity settings of the camera. 0=bright light, 261 1=Medium (default), 2=Low light. This setting affects 262 frame rate: the dimmer the lighting the lower the frame 263 rate (because longer exposition time is needed). The 264 Model 2 cameras allow values more than 2 for this option, 265 thus enabling extremely high sensitivity at cost of frame 266 rate, color saturation and imaging sensor noise. 267 268sharpness This option controls smoothing (noise reduction) 269 made by camera. Setting 0 is most smooth, setting 6 270 is most sharp. Be aware that CMOS sensor used in the 271 camera is pretty noisy, so if you choose 6 you will 272 be greeted with "snowy" image. Default is 4. Model 2 273 cameras do not support this feature. 274 275size This setting chooses one of several image sizes that are 276 supported by this driver. Cameras may support more, but 277 it's difficult to reverse-engineer all formats. 278 Following video sizes are supported: 279 280 size=0 128x96 (Model 1 only) 281 size=1 160x120 282 size=2 176x144 283 size=3 320x240 (Model 2 only) 284 size=4 352x240 (Model 2 only) 285 size=5 352x288 286 size=6 640x480 (Model 3 only) 287 288 The 352x288 is the native size of the Model 1 sensor 289 array, so it's the best resolution the camera can 290 yield. The best resolution of Model 2 is 176x144, and 291 larger images are produced by stretching the bitmap. 292 Model 3 has sensor with 640x480 grid, and it works too, 293 but the frame rate will be exceptionally low (1-2 FPS); 294 it may be still OK for some applications, like security. 295 Choose the image size you need. The smaller image can 296 support faster frame rate. Default is 352x288. 297 298For more information and the Troubleshooting FAQ visit this URL: 299 300 http://www.linux-usb.org/ibmcam/ 301 302WHAT NEEDS TO BE DONE: 303 304- The button on the camera is not used. I don't know how to get to it. 305 I know now how to read button on Model 2, but what to do with it? 306 307- Camera reports its status back to the driver; however I don't know 308 what returned data means. If camera fails at some initialization 309 stage then something should be done, and I don't do that because 310 I don't even know that some command failed. This is mostly Model 1 311 concern because Model 2 uses different commands which do not return 312 status (and seem to complete successfully every time). 313 314- Some flavors of Model 4 NetCameras produce only compressed video 315 streams, and I don't know how to decode them. 316 317CREDITS: 318 319The code is based in no small part on the CPiA driver by Johannes Erdfelt, 320Randy Dunlap, and others. Big thanks to them for their pioneering work on that 321and the USB stack. 322 323I also thank John Lightsey for his donation of the Veo Stingray camera. 324