sane-usb.5
sane-usb(5) SANE Scanner Access Now Easy sane-usb(5)
NAME
sane-usb - USB configuration tips for SANE
DESCRIPTION
This manual page contains information on how to access scanners with a
USB interface. It focusses on two main topics: getting the scanner
detected by the operating system kernel and using it with SANE.
This page applies to most backends and scanners, as they use the
generic sanei_usb interface. However, there are some exceptions: USB
Scanners supported by the avision and microtek2 backends need special
USB kernel drivers, see sane-avision(5) and sane-microtek2(5) for
details. The sm3600 backend supports only access via libusb. See the
appropriate section in this manpage and sane-sm3600(5).
QUICK START
This is a short HOWTO-like section. For the full details, read the fol-
lowing sections. The goal of this section is to get the scanner
detected by sane-find-scanner(1).
Run sane-find-scanner. If it lists your scanner with the correct vendor
and product ids, you are done. See section SANE ISSUES for details on
how to go on.
Sane-find-scanner lists your scanner, but can't detect the vendor- and
product ids? Scanning may work nevertheless, just try with section SANE
ISSUES. If it doesn't, install libusb (see section LIBUSB) or, if you
use Linux, upgrade your kernel (see section GENERIC KERNEL SCANNER
DRIVER).
Sane-find-scanner doesn't list your scanner? Does it work as root? If
yes, there is a permission issue. If sane-find-scanner lists a device
name starting with libusb:, read LIBUSB, otherwise have a look at the
section GENERIC KERNEL SCANNER DRIVER).
Nothing is found even as root? Either install libusb (see section
LIBUSB), or make sure, that the kernel scanner driver knows the ids of
your scanner (see section GENERIC KERNEL SCANNER DRIVER).
USB ACCESS METHODS
Two methods for accessing USB devices are currently in use: direct
access using the kernel scanner driver and access over libusb. By
default, both methods are tried by SANE, if they are available. Cur-
rently USB access is tested for Linux (kernel, libusb), FreeBSD (ker-
nel, libsub), NetBSD (libusb), OpenBSD (kernel, libusb) and MacOS X
(libusb). Testing on MacOS X is very limited and not all scanners seem
to work reliably with the BSDs. For installation issues, also check the
/usr/local/doc/sane-1.0.12-cvs/README.platform files.
Generally speaking, if your scanner works with one method, there is no
need to switch to the other one.
Libusb is the more general approach and is able to access any scanner.
Also, it supports more platforms.
Autodetecting scanners and using USB control messages with the kernel
access method only works with recent (>=v2.4.12) Linux kernels. If you
need one of these two features on a different platform, use libusb
instead. Also, the kernel scanner driver may be removed from Linux
2.5/2.6 in future so libusb will be the only access method.
LIBUSB
SANE can only use libusb 0.1.6 or newer. It needs to be installed at
build-time.
Libusb can only access your scanner if it's not claimed by the kernel
scanner driver. If you want to use libusb, unload the kernel driver
(e.g. rmmod scanner under Linux) or disable the driver when compiling a
new kernel. For Linux, your kernel needs support for the USB filesystem
(usbfs). For kernels older than 2.4.19, replace "usbfs" with "usbdevfs"
because the name has changed. This filesystem must be mounted. That's
done automatically at boot time, if /etc/fstab contains a line like
this:
none /proc/bus/usb usbfs defaults 0 0
The permissions for the device files used by libusb must be adjusted
for user access. Otherwise only root can use SANE devices. For Linux,
the devices are located in /proc/bus/usb/. There are directories named
e.g. "001" (the bus name) containing files "001", "002" etc. (the
device files). The right device files can be found out by running scan-
image -L as root. Setting permissions with "chmod" is not permanent,
however. They will be resetted after reboot or replugging the scanner.
It's also possible to mount the usbfs with the option "devmode=0666",
e.g. by using the following line in /etc/fstab:
none /proc/bus/usb usbfs defaults,devmode=0666 0 0
However, this way everyone has access to all USB devices. Another way
to set permissions is to use the hotplug utilities (http://linux-hot-
plug.sourceforge.net/), which support dynamic setting of access permis-
sions. Last, the frontends can be run as root. However, that's not rec-
ommended for security reasons.
For the BSDs, the device files are named /dev/ugen*. Use chmod to
apply appropriate permissions.
GENERIC KERNEL SCANNER DRIVER
Ensure that the access permissions for the USB device are set appropri-
ately. We recommend to add a group "scanner" to /etc/group which con-
tains all users that should have access to the scanner. The permission
of the device should then be set to allow group read and write access.
For example, if the scanner is at USB device /dev/usb/scanner0, then
the following two commands would set the permission correctly:
$ chgrp scanner /dev/usb/scanner0
$ chmod 660 /dev/usb/scanner0
If your scanner isn't detected automatically by your operating system's
scanner driver, you need to tell the kernel the vendor and product ids
of your scanner. For Linux, this can be done with modprobe parameters:
First, remove the scanner module (rmmod scanner), then load it again:
modprobe scanner vendor=0x0001 product=0x0002. Use the appropriate
vendor and product ids (e.g. from /var/log/messages, dmesg, or cat
/proc/bus/usb/devices). Some scanners supported by the gt68xx backend
are not supported by the current version of the generic scanner driver.
See sane-gt68xx(5) for details. For these scanners, there will be a
message concerning "only 2 or three endpoints" in syslog.
For OpenBSD the kernel may need to be recompiled. For details look at
/usr/local/doc/sane-1.0.12-cvs/README.openbsd. Similar approaches
should be used for the other BSDs.
Linux kernel messages in syslog like "kernel: scanner.c:
open_scanner(1): Unable to access minor data" can be ignored. They are
generated when SANE scans all available USB devices for scanners.
SANE ISSUES
This section assumes that your scanner is detected by sane-find-scan-
ner. It doesn't make sense to go on, if this is not the case. While
sane-find-scanner is able to detect any USB scanner, actual scanning
will only work if the scanner is supported by a SANE backend. Informa-
tion on the level of support can be found on the SANE webpage
(http://www.sane-project.org/), and the individual backend manpages.
Most backends can detect USB scanners automatically using "usb" config-
uration file lines. This method allows to identify scanners by the USB
vendor and product numbers. The syntax for specifying a scanner this
way is:
usb VENDOR PRODUCT
where VENDOR is the USB vendor id, and PRODUCT is the USB product id of
the scanner. Both ids are non-negative integer numbers in decimal or
hexadecimal format. The correct values for these fields can be found by
looking into the syslog (e.g., /var/log/messages) or under Linux by
issuing the command "cat /proc/bus/usb/devices/". This is an example
of a config file line:
usb 0x055f 0x0006
would have the effect that all USB devices in the system with a vendor
id of 0x55f and a product id of 0x0006 would be probed and recognized
by the backend.
If your scanner is not detected automatically, it may be necessary to
edit the appropriate backend configuration file before using SANE for
the first time. For most systems, the configuration file should list
the name of the USB device file that the scanner is connected to (e.g.,
under Linux, /dev/usb/scanner0 or /dev/usbscanner0 is such a USB
device, the device file for FreeBSD is e.g. /dev/uscanner0). If
libusb is used, the device name looks like the following example:
libusb:001:002.
For a detailed description of each backend's configuration file, please
refer to the relevant backend manual page (e.g. sane-mustek_usb(5) for
Mustek USB scanners).
Do not create a symlink from /dev/scanner to the USB device because
this link is used by the SCSI backends. The scanner may be confused if
it receives SCSI commands.
ENVIRONMENT
SANE_DEBUG_SANEI_USB
If the library was compiled with debug support enabled, this
environment variable controls the debug level for the USB I/O
subsystem. E.g., a value of 128 requests all debug output to be
printed. Smaller levels reduce verbosity. Values greater than 4
enable libusb debugging (if available). Example: export
SANE_DEBUG_SANEI_USB=4.
SEE ALSO
sane(7), sane-find-scanner(1), sane-"backendname"(5), sane-scsi(5)
AUTHOR
Henning Meier-Geinitz
sane-backends 1.0.12-cvs 27 Nov 2002 sane-usb(5)
Man(1) output converted with
man2html