diff options
Diffstat (limited to 'Documentation/usb/ibmcam.txt')
| -rw-r--r-- | Documentation/usb/ibmcam.txt | 324 |
1 files changed, 0 insertions, 324 deletions
diff --git a/Documentation/usb/ibmcam.txt b/Documentation/usb/ibmcam.txt deleted file mode 100644 index c2500364413..00000000000 --- a/Documentation/usb/ibmcam.txt +++ /dev/null @@ -1,324 +0,0 @@ -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://www.xirlink.com/ -(renamed to http://www.veo.com), 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. |