1 |
1275 |
phoenix |
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.
|