About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / ibmcam.txt




Custom Search

Based on kernel version 3.8. Page generated on 2013-02-20 22:08 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.