sane-usb(5) SANE Scanner Access Now Easy sane-usb(5)NAMEsane-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 sys-
tem 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 following sections. The goal of this section is
to get the scanner detected by sane-find-scanner(5).
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. Currently USB access is
tested for Linux (kernel, libusb), FreeBSD (kernel, lib-
sub), 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 instal-
lation issues, also check the /usr/free-
ware/share/doc/sane-backends/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 scanimage -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 util-
ities (http://linux-hotplug.sourceforge.net/), which sup-
port dynamic setting of access permissions. Last, the
frontends can be run as root. However, that's not recom-
mended 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 appropriately. We recommend to add a group "scanner"
to /etc/group which contains 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 sup-
ported by the current version of the generic scanner
driver. See sane-gt68xx(5) for details. For these scan-
ners, 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/freeware/share/doc/sane-back-
ends/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-scanner. 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. Information on the
level of support can be found on the SANE webpage
(http://www.mostang.com/sane/), and the individual backend
manpages.
Most backends can detect USB scanners automatically using
"usb" configuration 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 inte-
ger 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 sys-
tems, 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 avail-
able). Example: export SANE_DEBUG_SANEI_USB=4.
SEE ALSOsane(7), sane-find-scanner(1), sane-"backendname"(5),
sane-scsi(5)AUTHOR
Henning Meier-Geinitz
sane-backends 1.0.12 27 Nov 2002 sane-usb(5)
