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 IBM "C-It" camera, also known as "Xirlink 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 The Linux driver was developed with camera with following
  35 model number (or FCC ID): KSX-XVP510. This camera has three
  36 interfaces, each with one endpoint (control, iso, iso). This
  37 type of cameras is referred to as "model 1". These cameras are
  38 no longer manufactured.
  39
  40 Xirlink now manufactures new cameras which are somewhat different.
  41 In particular, following models [FCC ID] belong to that category:
  42
  43 XVP300 [KSX-X9903]
  44 XVP600 [KSX-X9902]
  45 XVP610 [KSX-X9902]
  46
  47 (see http://www.xirlink.com/ibmpccamera/ for updates, they refer
  48 to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
  49 These cameras have two interfaces, one endpoint in each (iso, bulk).
  50 Such type of cameras is referred to as "model 2". They are supported
  51 (with exception of 352x288 native mode).
  52
  53 Quirks of Model 2 cameras:
  54 -------------------------
  55
  56 Model 2 does not have hardware contrast control. Corresponding V4L
  57 control is not used at the moment. It may be possible to implement
  58 contrast control in software, at cost of extra processor cycles.
  59
  60 This driver provides 352x288 mode by switching the camera into
  61 quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
  62 this mode to 10 frames per second or less, in ideal conditions on
  63 the bus (USB is shared, after all). The frame rate
  64 has to be programmed very conservatively. Additional concern is that
  65 frame rate depends on brightness setting; therefore the picture can
  66 be good at one brightness and broken at another! I did not want to fix
  67 the frame rate at slowest setting, but I had to move it pretty much down
  68 the scale (so that framerate option barely matters). I also noticed that
  69 camera after first powering up produces frames slightly faster than during
  70 consecutive uses. All this means that if you use videosize=2 (which is
  71 default), be warned - you may encounter broken picture on first connect;
  72 try to adjust brightness - brighter image is slower, so USB will be able
  73 to send all data. However if you regularly use Model 2 cameras you may
  74 prefer videosize=1 which makes perfectly good I420, with no scaling and
  75 lesser demands on USB (300 Kbits per second, or 26 frames per second).
  76
  77 The camera that I had also has a hardware quirk: if disconnected,
  78 it needs few minutes to "relax" before it can be plugged in again
  79 (poorly designed USB processor reset circuit?)
  80
  81 Model 2 camera can be programmed for very high sensitivity (even starlight
  82 may be enough), this makes it convenient for tinkering with. The driver
  83 code has enough comments to help a programmer to tweak the camera
  84 as s/he feels necessary.
  85
  86 WHAT YOU NEED:
  87
  88 - A supported IBM PC (C-it) camera (model 1 or 2)
  89
  90 - A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)
  91
  92 - A Video4Linux compatible frame grabber program such as xawtv.
  93
  94 HOW TO COMPILE THE DRIVER:
  95
  96 You need to compile the driver only if you are a developer
  97 or if you want to make changes to the code. Most distributions
  98 precompile all modules, so you can go directly to the next
  99 section "HOW TO USE THE DRIVER".
 100
 101 The driver consists of two files in usb/ directory:
 102 ibmcam.c and ibmcam.h These files are included into the
 103 Linux kernel build process if you configure the kernel
 104 for CONFIG_USB_IBMCAM. Run "make xconfig" and in USB section
 105 you will find the IBM camera driver. Select it, save the
 106 configuration and recompile.
 107
 108 HOW TO USE THE DRIVER:
 109
 110 I recommend to compile driver as a module. This gives you an
 111 easier access to its configuration. The camera has many more
 112 settings than V4L can operate, so some settings are done using
 113 module options.
 114
 115 Typically module is installed with command 'modprobe', like this:
 116
 117 # modprobe ibmcam framerate=1
 118
 119 Alternatively you can use 'insmod' in similar fashion:
 120
 121 # insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
 122
 123 Module can be inserted with camera connected or disconnected.
 124
 125 The driver can have options, though some defaults are provided.
 126
 127 Driver options: (* indicates that option is model-dependent)
 128
 129 Name            Type            Range [default] Example
 130 --------------  --------------  --------------  ------------------
 131 debug           Integer         0-9 [0]         debug=1
 132 flags           Integer         0-0xFF [0]      flags=0x0d
 133 framerate       Integer         0-6 [2]         framerate=1
 134 hue_correction  Integer         0-255 [128]     hue_correction=115
 135 init_brightness Integer         0-255 [128]     init_brightness=100
 136 init_contrast   Integer         0-255 [192]     init_contrast=200
 137 init_color      Integer         0-255 [128]     init_color=130
 138 init_hue        Integer         0-255 [128]     init_hue=115
 139 lighting        Integer         0-2* [1]        lighting=2
 140 sharpness       Integer         0-6* [4]        sharpness=3
 141 videosize       Integer         0-2* [2]        videosize=1
 142
 143 Options for Model 2 only:
 144
 145 Name            Type            Range [default] Example
 146 --------------  --------------  --------------  ------------------
 147 init_model2_rg  Integer         0..255 [0x70]   init_model2_rg=128
 148 init_model2_rg2 Integer         0..255 [0x2f]   init_model2_rg2=50
 149 init_model2_sat Integer         0..255 [0x34]   init_model2_sat=65
 150 init_model2_yb  Integer         0..255 [0xa0]   init_model2_yb=200
 151
 152 debug           You don't need this option unless you are a developer.
 153                 If you are a developer then you will see in the code
 154                 what values do what. 0=off.
 155
 156 flags           This is a bit mask, and you can combine any number of
 157                 bits to produce what you want. Usually you don't want
 158                 any of extra features this option provides:
 159
 160                 FLAGS_RETRY_VIDIOCSYNC  1  This bit allows to retry failed
 161                                            VIDIOCSYNC ioctls without failing.
 162                                            Will work with xawtv, will not
 163                                            with xrealproducer. Default is
 164                                            not set.
 165                 FLAGS_MONOCHROME        2  Activates monochrome (b/w) mode.
 166                 FLAGS_DISPLAY_HINTS     4  Shows colored pixels which have
 167                                            magic meaning to developers.
 168                 FLAGS_OVERLAY_STATS     8  Shows tiny numbers on screen,
 169                                            useful only for debugging.
 170                 FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers.
 171                 FLAGS_SEPARATE_FRAMES   32 Shows each frame separately, as
 172                                            it was received from the camera.
 173                                            Default (not set) is to mix the
 174                                            preceding frame in to compensate
 175                                            for occasional loss of Isoc data
 176                                            on high frame rates.
 177                 FLAGS_CLEAN_FRAMES      64 Forces "cleanup" of each frame
 178                                            prior to use; relevant only if
 179                                            FLAGS_SEPARATE_FRAMES is set.
 180                                            Default is not to clean frames,
 181                                            this is a little faster but may
 182                                            produce flicker if frame rate is
 183                                            too high and Isoc data gets lost.
 184
 185 framerate       This setting controls frame rate of the camera. This is
 186                 an approximate setting (in terms of "worst" ... "best")
 187                 because camera changes frame rate depending on amount
 188                 of light available. Setting 0 is slowest, 6 is fastest.
 189                 Beware - fast settings are very demanding and may not
 190                 work well with all video sizes. Be conservative.
 191
 192 hue_correction  This highly optional setting allows to adjust the
 193                 hue of the image in a way slightly different from
 194                 what usual "hue" control does. Both controls affect
 195                 YUV colorspace: regular "hue" control adjusts only
 196                 U component, and this "hue_correction" option similarly
 197                 adjusts only V component. However usually it is enough
 198                 to tweak only U or V to compensate for colored light or
 199                 color temperature; this option simply allows more
 200                 complicated correction when and if it is necessary.
 201
 202 init_brightness These settings specify _initial_ values which will be
 203 init_contrast   used to set up the camera. If your V4L application has
 204 init_color      its own controls to adjust the picture then these
 205 init_hue        controls will be used too. These options allow you to
 206                 preconfigure the camera when it gets connected, before
 207                 any V4L application connects to it. Good for webcams.
 208
 209 init_model2_rg  These initial settings alter color balance of the
 210 init_model2_rg2 camera on hardware level. All four settings may be used
 211 init_model2_sat to tune the camera to specific lighting conditions. These
 212 init_model2_yb  settings only apply to Model 2 cameras.
 213
 214 lighting        This option selects one of three hardware-defined
 215                 photosensitivity settings of the camera. 0=bright light,
 216                 1=Medium (default), 2=Low light. This setting affects
 217                 frame rate: the dimmer the lighting the lower the frame
 218                 rate (because longer exposition time is needed). The
 219                 Model 2 cameras allow values more than 2 for this option,
 220                 thus enabling extremely high sensitivity at cost of frame
 221                 rate, color saturation and imaging sensor noise.
 222
 223 sharpness       This option controls smoothing (noise reduction)
 224                 made by camera. Setting 0 is most smooth, setting 6
 225                 is most sharp. Be aware that CMOS sensor used in the
 226                 camera is pretty noisy, so if you choose 6 you will
 227                 be greeted with "snowy" image. Default is 4. Model 2
 228                 cameras do not support this feature.
 229
 230 videosize       This setting chooses one if three image sizes that are
 231                 supported by this driver. Camera supports more, but
 232                 it's difficult to reverse-engineer all formats.
 233                 Following video sizes are supported:
 234
 235                 videosize=0     128x96  (Model 1 only)
 236                 videosize=1     176x144
 237                 videosize=2     352x288
 238                 videosize=3     320x240 (Model 2 only)
 239                 videosize=4     352x240 (Model 2 only)
 240
 241                 The last one (352x288) is the native size of the sensor
 242                 array, so it's the best resolution camera (Model 1) can
 243                 yield. The best resolution of Model 2 is 176x144, and
 244                 larger images are produced by stretching the bitmap.
 245                 Choose the image size you need. The smaller image can
 246                 support faster frame rate. Default is 352x288.
 247
 248 WHAT NEEDS TO BE DONE:
 249
 250 - The box freezes if camera is unplugged after being used (OHCI).
 251   Workaround: remove usb-ohci module first.
 252 - On occasion camera (model 1) does not start properly (xawtv reports
 253   errors), or camera produces negative image (funny colors.)
 254   Workaround: reload the driver module. Reason: [1].
 255 - The button on the camera is not used. I don't know how to get to it.
 256   I know now how to read button on Model 2, but what to do with it?
 257
 258 [1]
 259 - Camera reports its status back to the driver; however I don't know
 260   what returned data means. If camera fails at some initialization
 261   stage then something should be done, and I don't do that because
 262   I don't even know that some command failed. This is mostly Model 1
 263   concern because Model 2 uses different commands which do not return
 264   status (and seem to complete successfully every time).
 265
 266 VIDEO SIZE AND IMAGE SIZE
 267
 268 Camera produces picture X by Y pixels. This is camera-specific and can be
 269 altered by programming the camera accordingly. This image is placed onto
 270 larger (or equal) area W by H, this is V4L image. At this time the driver
 271 uses V4L image size (W by H) 352x288 pixels because many programs (such
 272 as xawtv) expect quite specific sizes and don't want to deal with arbitrary,
 273 camera-specific sizes. However this approach "hides" real image size, and
 274 application always sees the camera as producing only 352x288 image. It is
 275 possible to change the V4L image size to 128x96, and then if camera is
 276 switched to 128x96 mode then xawtv will correctly accept this image size. But
 277 many other popular sizes (such as 176x144) will not be welcomed. This is the
 278 reason why all camera images are at this time placed onto 352x288 "canvas",
 279 and size of that canvas (V4L) is reported to applications. It will be easy
 280 to add options to control the canvas size, but it will be application-
 281 specific because not all applications are ready to work with variety of
 282 camera-specific sizes.
 283
 284 CREDITS:
 285
 286 The code is based in no small part on the CPiA driver by Johannes Erdfelt,
 287 Randy Dunlap, and others. Big thanks to them for their pioneering work on that
 288 and the USB stack.