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