Documentation/usb/ibmcam.txt

   1 README for Linux device driver for the IBM "C-It" USB video camera
   2
   3 INTRODUCTION:
   4
   5 This driver does not use all features known to exist in
   6 the IBM camera. However most of needed features work well.
   7
   8 This driver was developed using logs of observed USB traffic
   9 which was produced by standard Windows driver (c-it98.sys).
  10 I did not have data sheets from Xirlink.
  11
  12 Video formats:
  13       128x96  [model 1]
  14       176x144
  15       320x240 [model 2]
  16       352x240 [model 2]
  17       352x288
  18 Frame rate: 3 - 30 frames per second (FPS)
  19 External interface: USB
  20 Internal interface: Video For Linux (V4L)
  21 Supported controls:
  22 - by V4L: Contrast,  Brightness, Color, Hue
  23 - by driver options: frame rate, lighting conditions, video format,
  24                      default picture settings, sharpness.
  25
  26 SUPPORTED CAMERAS:
  27
  28 Xirlink "C-It" camera, also known as "IBM PC Camera".
  29 The device uses proprietary ASIC (and compression method);
  30 it is manufactured by Xirlink. See http://www.xirlink.com/
  31 http://www.ibmpccamera.com or http://www.c-itnow.com/ for
  32 details and pictures.
  33
  34 This very chipset ("X Chip", as marked at the factory)
  35 is used in several other cameras, and they are supported
  36 as well:
  37
  38 - IBM NetCamera
  39 - Veo Stingray
  40
  41 The Linux driver was developed with camera with following
  42 model number (or FCC ID): KSX-XVP510. This camera has three
  43 interfaces, each with one endpoint (control, iso, iso). This
  44 type of cameras is referred to as "model 1". These cameras are
  45 no longer manufactured.
  46
  47 Xirlink now manufactures new cameras which are somewhat different.
  48 In particular, following models [FCC ID] belong to that category:
  49
  50 XVP300 [KSX-X9903]
  51 XVP600 [KSX-X9902]
  52 XVP610 [KSX-X9902]
  53
  54 (see http://www.xirlink.com/ibmpccamera/ for updates, they refer
  55 to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
  56 These cameras have two interfaces, one endpoint in each (iso, bulk).
  57 Such type of cameras is referred to as "model 2". They are supported
  58 (with exception of 352x288 native mode).
  59
  60 Some IBM NetCameras (Model 4) are made to generate only compressed
  61 video streams. This is great for performance, but unfortunately
  62 nobody knows how to decompress the stream :-( Therefore, these
  63 cameras are *unsupported* and if you try to use one of those, all
  64 you get is random colored horizontal streaks, not the image!
  65 If you have one of those cameras, you probably should return it
  66 to the store and get something that is supported.
  67
  68 Tell me more about all that "model" business
  69 --------------------------------------------
  70
  71 I just invented model numbers to uniquely identify flavors of the
  72 hardware/firmware that were sold. It was very confusing to use
  73 brand names or some other internal numbering schemes. So I found
  74 by experimentation that all Xirlink chipsets fall into four big
  75 classes, and I called them "models". Each model is programmed in
  76 its own way, and each model sends back the video in its own way.
  77
  78 Quirks of Model 2 cameras:
  79 -------------------------
  80
  81 Model 2 does not have hardware contrast control. Corresponding V4L
  82 control is implemented in software, which is not very nice to your
  83 CPU, but at least it works.
  84
  85 This driver provides 352x288 mode by switching the camera into
  86 quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
  87 this mode to 10 frames per second or less, in ideal conditions on
  88 the bus (USB is shared, after all). The frame rate
  89 has to be programmed very conservatively. Additional concern is that
  90 frame rate depends on brightness setting; therefore the picture can
  91 be good at one brightness and broken at another! I did not want to fix
  92 the frame rate at slowest setting, but I had to move it pretty much down
  93 the scale (so that framerate option barely matters). I also noticed that
  94 camera after first powering up produces frames slightly faster than during
  95 consecutive uses. All this means that if you use 352x288 (which is
  96 default), be warned - you may encounter broken picture on first connect;
  97 try to adjust brightness - brighter image is slower, so USB will be able
  98 to send all data. However if you regularly use Model 2 cameras you may
  99 prefer 176x144 which makes perfectly good I420, with no scaling and
 100 lesser demands on USB (300 Kbits per second, or 26 frames per second).
 101
 102 Another strange effect of 352x288 mode is the fine vertical grid visible
 103 on some colored surfaces. I am sure it is caused by me not understanding
 104 what the camera is trying to say. Blame trade secrets for that.
 105
 106 The camera that I had also has a hardware quirk: if disconnected,
 107 it 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
 111 observed this particular flaw in it.]
 112
 113 Model 2 camera can be programmed for very high sensitivity (even starlight
 114 may be enough), this makes it convenient for tinkering with. The driver
 115 code has enough comments to help a programmer to tweak the camera
 116 as s/he feels necessary.
 117
 118 WHAT 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
 126 HOW TO COMPILE THE DRIVER:
 127
 128 You need to compile the driver only if you are a developer
 129 or if you want to make changes to the code. Most distributions
 130 precompile all modules, so you can go directly to the next
 131 section "HOW TO USE THE DRIVER".
 132
 133 The ibmcam driver uses usbvideo helper library (module),
 134 so if you are studying the ibmcam code you will be led there.
 135
 136 The driver itself consists of only one file in usb/ directory:
 137 ibmcam.c. This file is included into the Linux kernel build
 138 process if you configure the kernel for CONFIG_USB_IBMCAM.
 139 Run "make xconfig" and in USB section you will find the IBM
 140 camera driver. Select it, save the configuration and recompile.
 141
 142 HOW TO USE THE DRIVER:
 143
 144 I recommend to compile driver as a module. This gives you an
 145 easier access to its configuration. The camera has many more
 146 settings than V4L can operate, so some settings are done using
 147 module options.
 148
 149 To begin with, on most modern Linux distributions the driver
 150 will be automatically loaded whenever you plug the supported
 151 camera in. Therefore, you don't need to do anything. However
 152 if you want to experiment with some module parameters then
 153 you can load and unload the driver manually, with camera
 154 plugged in or unplugged.
 155
 156 Typically module is installed with command 'modprobe', like this:
 157
 158 # modprobe ibmcam framerate=1
 159
 160 Alternatively you can use 'insmod' in similar fashion:
 161
 162 # insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
 163
 164 Module can be inserted with camera connected or disconnected.
 165
 166 The driver can have options, though some defaults are provided.
 167
 168 Driver options: (* indicates that option is model-dependent)
 169
 170 Name            Type            Range [default] Example
 171 --------------  --------------  --------------  ------------------
 172 debug           Integer         0-9 [0]         debug=1
 173 flags           Integer         0-0xFF [0]      flags=0x0d
 174 framerate       Integer         0-6 [2]         framerate=1
 175 hue_correction  Integer         0-255 [128]     hue_correction=115
 176 init_brightness Integer         0-255 [128]     init_brightness=100
 177 init_contrast   Integer         0-255 [192]     init_contrast=200
 178 init_color      Integer         0-255 [128]     init_color=130
 179 init_hue        Integer         0-255 [128]     init_hue=115
 180 lighting        Integer         0-2* [1]        lighting=2
 181 sharpness       Integer         0-6* [4]        sharpness=3
 182 size            Integer         0-2* [2]        size=1
 183
 184 Options for Model 2 only:
 185
 186 Name            Type            Range [default] Example
 187 --------------  --------------  --------------  ------------------
 188 init_model2_rg  Integer         0..255 [0x70]   init_model2_rg=128
 189 init_model2_rg2 Integer         0..255 [0x2f]   init_model2_rg2=50
 190 init_model2_sat Integer         0..255 [0x34]   init_model2_sat=65
 191 init_model2_yb  Integer         0..255 [0xa0]   init_model2_yb=200
 192
 193 debug           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
 197 flags           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
 231 framerate       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
 238 hue_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
 248 init_brightness These settings specify _initial_ values which will be
 249 init_contrast   used to set up the camera. If your V4L application has
 250 init_color      its own controls to adjust the picture then these
 251 init_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
 255 init_model2_rg  These initial settings alter color balance of the
 256 init_model2_rg2 camera on hardware level. All four settings may be used
 257 init_model2_sat to tune the camera to specific lighting conditions. These
 258 init_model2_yb  settings only apply to Model 2 cameras.
 259
 260 lighting        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
 269 sharpness       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
 276 size            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
 299 For more information and the Troubleshooting FAQ visit this URL:
 300
 301                 http://www.linux-usb.org/ibmcam/
 302
 303 WHAT 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
 318 CREDITS:
 319
 320 The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 321 Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 322 and the USB stack.
 323
 324 I also thank John Lightsey for his donation of the Veo Stingray camera.