/var/log/messages: access denied!
/proc/bus/usb/devices, directory is empty!
/proc/bus/usb/devices says "driver=(none)" - why?
/dev/video files!
1. Does your driver support my camera?
If you have an IBM (or Xirlink) camera then this driver is probably the most appropriate for your camera. At this time the driver supports all known IBM/Xirlink cameras. See the main page for list of known IBM/Xirlink cameras.
People occasionally report that their cameras that should be supported in fact do not work - they fail to send USB data back to the computer. It is very difficult for me to understand what I am missing in the driver because I don't have that camera and I don't have any documentation!
2. Do you work for IBM or Xirlink?
No - neither now nor ever before.
3. Does IBM or Xirlink have or provide Linux driver for these cameras?
Not to my knowledge. If they had a driver it was never released.
4. So where did you get the programming instructions for those cameras?
I never had any documentation. All my knowledge about those cameras was obtained by "black box"-style observations and by looking at data that a Windows box normally sends over the USB bus to talk to the camera. I spent many days just sending different commands to the camera and looking at their effect.
5. So now you know everything there is to know about those cameras?
Not at all. I grokked only enough to make a driver. I still have no clue what most commands do and why this or that magic number is sent now and then. This means that if your camera does not want to send video data I can't help - I honestly don't know why this might happen.
6. Does it mean you offer the driver on "as is" basis?
Practically, yes. The driver works for majority of people who already got these cameras. IBM/Xirlink cameras are quite affordable and therefore popular. If you need a camera for a highly important project, like Web conferencing for your boss, make yourself a favor and buy a camera that has published protocol. CPiA and OV511 are such chipsets, and developers know pretty much everything about them. These cameras are supportable.
Reverse-engineered devices, like IBM/Xirlink cameras, are OK only when you are stuck with them. Then you try this and that driver, this and that hack hoping that something magically works and the device comes alive.
I hope the driver is good enough for most people and most supported cameras. However if something does not work... well, my ability to troubleshoot your device is limited. Quite possibly my driver misses some "secret sauce" and this causes the camera to misbehave now and then. Well, what can I do? I just hope you are in 99% of happy users.
7. What about quality of those cameras?
Some models are better and more expensive, some are cheaper and barely usable. The lens on egg-shaped cameras is loose in threads. Models 2 and 4 are cheaper and provide not so sharp pictures. Model 1 is old and you hardly can buy it nowadays. Model 3 is a bit more expensive but takes images up to 640x480. Some model 3 cameras have RCA jack for external NTSC signal (from your VCR, for example).
8. Why there are several models of cameras?
Because cameras were reworked over time, its controller board changed to be either better or cheaper.
9. Where those model numbers came from?
I invented them to tell the difference between similar cameras made or sold by different companies. It is a common practice to license a design from one company, order manufacturing from another firm and sell under completely unrelated brand name. This is confusing. Since we only care about the design part, model numbers identify different designs.
10. How do I learn which camera I got?
You plug the camera into a Linux box. USB stack reports the manufacturer code,
the product code and revision code. These three numbers uniquely identify the
model of the camera. See the Table 1 on the main page.
Your /proc/bus/usb/devices may look like this. I highlighted the
numbers that determine the model number:
T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=12 MxCh= 0 D: Ver= 0.01 Cls=0a(data ) Sub=03 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0545 ProdID=8080 Rev= 0.02 |
If the driver for IBM cameras is loaded then it also reports what model it found.
11. How do I get started with all that USB stuff?
Read Linux USB HOWTO here.
12. What Linux kernel is required to support this camera?
Kernels 2.2.latest (like 2.2.18) and 2.4.x are OK. You do not want to work with earlier kernels because USB support in them was incomplete.
13. Do I need to recompile the kernel to use the camera?
Not at all. The support
for this camera is already in latest kernels (2.2.12 and newer). The module is called
ibmcam.o and you can load it (as root) with this command:
# modprobe ibmcam |
If you have special requirements, such as older or not standard kernel, then you may want to compile the driver from CVS at SourceForge. You must be reasonably familiar with compilation of the kernel to do that, but if you play with custom kernels you probably are.
14. I plugged the camera into my Linux box and nothing happens!
There will be no visible response anywhere on screen (unless you run
some monitoring tools like usbview). The USB stack and drivers work
silently. They usually report what they do into the system log file
/var/log/messages. Read this file to find out what happened.
Also read the file /proc/bus/usb/devices.
15. I can't read file /var/log/messages: access denied!
On most distributions you must be root to read that file.
16. There is no file /proc/bus/usb/devices, directory is empty!
You have to mount usbdevfs first. Most modern distributions do that for you.
17. The file /proc/bus/usb/devices says "driver=(none)" - why?
You may see something like this:
T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=12 MxCh= 0 D: Ver= 0.01 Cls=0a(data ) Sub=03 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0545 ProdID=8080 Rev= 0.02 C:* #Ifs= 3 Cfg#= 1 Atr=c0 MxPwr=500mA I: If#= 0 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=ff Prot=00 Driver=(none) E: Ad=01(B) Atr=00(Ctrl) MxPS= 8 Ivl= 0ms I: If#= 1 Alt= 0 #EPs= 1 Cls=01(audio) Sub=02 Prot=00 Driver=(none) E: Ad=83(I) Atr=01(Isoc) MxPS= 0 Ivl= 1ms I: If#= 1 Alt= 1 #EPs= 1 Cls=01(audio) Sub=02 Prot=00 Driver=(none) E: Ad=83(I) Atr=01(Isoc) MxPS= 18 Ivl= 1ms I: If#= 2 Alt= 0 #EPs= 1 Cls=0a(data ) Sub=03 Prot=00 Driver=(none) E: Ad=82(I) Atr=01(Isoc) MxPS= 0 Ivl= 1ms I: If#= 2 Alt= 1 #EPs= 1 Cls=0a(data ) Sub=03 Prot=00 Driver=(none) E: Ad=82(I) Atr=01(Isoc) MxPS=1022 Ivl= 1ms |
This means either that the driver is not loaded, or that the driver is loaded but
does not recognize your camera. Check your /var/log/messages file
to determine what happened. For example:
hub.c: port 1 connection change
hub.c: port 1, portstatus 101, change 1, 12 Mb/s
hub.c: port 1, portstatus 103, change 10, 12 Mb/s
hub.c: USB new device connect on bus1/1, assigned device number 3
usb.c: kmalloc IF c5f8d360, numif 3
usb.c: new device strings: Mfr=0, Product=0, SerialNumber=0
usb.c: unhandled interfaces on device
usb.c: USB device 3 (vend/prod 0x545/0x8080) is not claimed by any active driver.
|
The example above says that the new device (IBM camera model 1) is properly connected and USB stack had no problems talking to the device. However none of currently loaded drivers recognized this device. Let's find out why this happened!
Check what modules are loaded with command /sbin/lsmod:
Module Size Used by scanner 6256 0 (unused) visor 4448 0 (unused) usbserial 12624 0 [visor] hid 12128 0 (unused) mousedev 4320 1 input 3360 0 [hid mousedev] usb-ohci 17168 0 (unused) usbcore 53648 1 [scanner visor usbserial hid usb-ohci] 8139too 15552 1 |
Many modules, but ibmcam module is not there! Let's load it with command
modprobe ibmcam. Now repeat /sbin/lsmod:
Module Size Used by
ibmcam 24000 0
scanner 6256 0 (unused)
visor 4448 0 (unused)
usbserial 12624 0 [visor]
hid 12128 0 (unused)
mousedev 4320 1
input 3360 0 [hid mousedev]
usb-ohci 17168 0 (unused)
usbcore 53648 1 [ibmcam scanner visor usbserial hid usb-ohci]
8139too 15552 1
|
Now ibmcam module seems to be loaded! Let's check
/proc/bus/usb/devices again:
T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=12 MxCh= 0 D: Ver= 0.01 Cls=0a(data ) Sub=03 Prot=00 MxPS= 8 #Cfgs= 1 P: Vendor=0545 ProdID=8080 Rev= 0.02 C:* #Ifs= 3 Cfg#= 1 Atr=c0 MxPwr=500mA I: If#= 0 Alt= 0 #EPs= 1 Cls=ff(vend.) Sub=ff Prot=00 Driver=(none) E: Ad=01(B) Atr=00(Ctrl) MxPS= 8 Ivl= 0ms I: If#= 1 Alt= 0 #EPs= 1 Cls=01(audio) Sub=02 Prot=00 Driver=(none) E: Ad=83(I) Atr=01(Isoc) MxPS= 0 Ivl= 1ms I: If#= 1 Alt= 1 #EPs= 1 Cls=01(audio) Sub=02 Prot=00 Driver=(none) E: Ad=83(I) Atr=01(Isoc) MxPS= 18 Ivl= 1ms I: If#= 2 Alt= 0 #EPs= 1 Cls=0a(data ) Sub=03 Prot=00 Driver=ibmcam E: Ad=82(I) Atr=01(Isoc) MxPS= 0 Ivl= 1ms I: If#= 2 Alt= 1 #EPs= 1 Cls=0a(data ) Sub=03 Prot=00 Driver=ibmcam E: Ad=82(I) Atr=01(Isoc) MxPS=1022 Ivl= 1ms |
Success! Now the driver claimed all two alternative settings of interface 2. This is normal for model 1 cameras. Other interfaces are not in use, and the whole structure of USB interfaces changes between models of cameras. That's one of big differences between models.
18. I can't load your driver, insmod says "Unresolved symbols" !
You probably see something like this:
Using /lib/modules/2.4.0/kernel/drivers/usb/ibmcam.o /lib/modules/2.4.0/kernel/drivers/usb/ibmcam.o: unresolved symbol video_register_device /lib/modules/2.4.0/kernel/drivers/usb/ibmcam.o: unresolved symbol video_unregister_device |
This happens when you use insmod command to load the module
instead of modprobe. IBM camera driver needs module videodev,
and modprobe automatically pulls it in when some other module needs it.
This is called "dependency check". insmod, on the other hand, does not
check anything, and unless you are a developer you should use modprobe.
19. What are module options?
They are parameters which you can pass to the driver module when you load it. The driver has many options, but normally you don't need any because the driver assigns reasonable default values for all options anyway.
For example, you may enable debugging information on screen this way:
# modprobe ibmcam flags=9 |
The complete list of all module options is provided in kernel documentation.
See file linux/Documentation/usb/ibmcam.txt in your kernel tree.
You also can use command "modinfo -p ibmcam" to list options.
Most of options deal with color adjustments and rarely used features.
20. How do I change the image size?
Probably this is one option you are most likely to use: "size=N". This option switches the camera to capture images on given resolution (image size). The larger image size is the slower the frame rate will be, but each frame becomes better and better. The number N above defines the image size. Note that no single camera supports all image sizes; then the driver will choose one of supported sizes instead.
|
|
21. Now your driver recognized my camera; what do I do next?
You can read video data from the matching special file (device), like
/dev/video. If you have several video devices they will be
numbered sequentially: /dev/video0, /dev/video1 etc.
Numbered devices are claimed by camera driver(s) and returned back into
the pool as needed, so if you have two cameras they can be /dev/video0
and /dev/video1 depending on order of connection. This is true for
most video devices.
22. I don't have any /dev/video files!
You must be running a very old distribution! In any case, those
special files can
be made with mknod command. Read Linux-USB HOWTO to learn how.
Note that /dev/video is usually just a link to /dev/video0.
23. How do I read the picture from the camera?
Well, the easiest way is this:
$ cat < /dev/video > foo.dat
. . .
^C <--Press Control-C here to stop reading
$
|
This is hardly a practical way to get any good pictures, but it is a simple and effective test of the camera. A normally functioning camera will produce about one megabyte of video data per second. So if you collect several megabytes of some (binary) data in few seconds this tells that the camera most likely works.
What if, however, the file size is zero regardless of how long you wait? This means that the camera does not send data, or it sends some garbage instead of correct video frames. Continue testing but be warned of possible trouble ahead.
24. How do I get a usable picture after all?
You need a video application (program), one that conforms to V4L (Video for Linux) standard. Many such applications exist, xawtv being probably better known. More V4L applications are listed on this page.
25. Why xawtv warns me about some "overlay" support missing?
Overlay is a hardware hack. Some PCI video capture cards can work in bus mastering mode. This allows them to hijack the main bus of the computer and access most of the memory as CPU itself normally does. This allows the video capture card to write directly into the video memory of the display card completely bypassing the CPU. Such hack is very efficient, and many popular PCI-based capture cards support it. However USB hardware is not capable of this feat.
xawtv warns you that overlay support in USB camera driver is not
available. True, it is not available because of hardware limitations.
You should disable overlay in xawtv by specifying option
-remote. Then xawtv will not even attempt to access the
overlay capability of the driver.
26. Why xawtv produces some error messages on startup?
That's because xawtv was designed primarily for video capture cards (TV tuners). These cards have their own processor, unlimited bandwidth of PCI bus and have their own Linux driver (like bttv).
xawtv sends some illegal requests to USB camera driver. The driver correctly rejects those requests, this explains some of visible error messages. Other messages are caused by xawtv "probing" the driver in order to find out what video formats (palettes) it supports, what video sizes etc. During probing errors do not cause any harm; instead xawtv just notes that this driver does or does not support a given set of parameters. After probing is complete xawtv switches to the most appropriate mode that is supported by the driver.
27. xawtv shows just a black screen, what to do?
This may be caused by your camera not sending proper video data stream. xawtv usually prints "v4l: oops: got sigalarm" message every second or so, when it gives up on a frame. Generally, it is a bad sign. Before giving up, however, check couple of things:
size=N. The value of N should be
in range [0..6] but not all values are supported by all cameras.
It is safe to try, though.
flags=9. This option will enable some
debugging information as part of the picture. You may see a blue
picture with tiny running numbers on the left. Those numbers tell
what the driver is doing. Grab several snapshots ('g' in xawtv)
for analysis.
What these numbers mean is explained below.
debug=1
or debug=2. The debugging information will be written
into /var/log/messages, this may generate a lot of disk
activity during the test.
28. What is the meaning of numbers in the debugging output on blue background?
This output may be produced by module option flags=9. If the
camera fails to deliver data the driver will replace the picture with
blue background, otherwise numbers will be overlayed on the live image.
Following table explains what numbers mean, top to bottom.
| Row | Variable | Interpretation |
|---|---|---|
| 1 | frame_num | Current frame number, counting up |
| 2 | urb_count | Counts video USB transfer requests completed (successfully or not) by the USB stack |
| 3 | urb_length | Shows number of video data bytes delivered in this USB request (not cumulative!) |
| 4 | data_count | Counts all data bytes received from camera via video data pipe |
| 5 | header_count | Counts frame headers (markers) detected by IBM camera datastream parser |
| 6 | iso_skip_count | Counts empty video packets sent by the camera (when it has no data, for example) |
| 7 | iso_err_count | Counts USB video packets that completed with errors |
| 8 | colour | Current setting of color (saturation) |
| 9 | hue | Current setting of hue (tint) |
| 10 | brightness | Current setting of brightness |
| 11 | contrast | Current setting of contrast |
| 12 | whiteness | Current setting of whiteness (not used, needed only for grayscale images) |
29. The picture is OK but there is too much red/green/blue/whatever
Many IBM/Xirlink cameras apparently have white balance feature in hardware. This means that they seem to adjust to the color temperature of the light, thus correcting colors accordingly. Model 4 definitely does not have this feature. It means that in an incandescent light the picture will have red tones and in sunlight the image will have more blue tones.
In any case, V4L application should have hue correction control somewhere ('o' in xawtv). Use it to adjust the hue of the image as needed.
30. If all else fails, who will help me?
I will try to help if I can. See here.