#

# 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(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. 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)