Debian Codegraph @

upstream/debian-unstable/man5/sane-usb.5

raw
1 .TH sane\-usb 5 "14 Jul 2008" "" "SANE Scanner Access Now Easy"
2 .IX sane\-usb
3 .SH NAME
4 sane\-usb \- USB configuration tips for SANE
5 .SH DESCRIPTION
6 This manual page contains information on how to access scanners with a USB
7 interface. It focuses on two main topics: getting the scanner detected by the
8 operating system kernel and using it with SANE.
9 .PP
10 This page applies to USB most backends and scanners, as they use the generic
11 sanei_usb interface. However, there is one exception: USB Scanners
12 supported by the
13 .BR sane\-microtek2 (5)
14 backend need a special USB kernel driver.
15
16 .SH "QUICK START"
17 This is a short HOWTO-like section. For the full details, read the following
18 sections. The goal of this section is to get the scanner detected by
19 .BR sane\-find\-scanner (1).
20 .PP
21 Run
22 .BR sane\-find\-scanner (1).
23 If it lists your scanner with the correct vendor and
24 product ids, you are done. See section
25 .B "SANE ISSUES"
26 for details on how to go on.
27 .PP
28 .BR sane\-find\-scanner (1)
29 doesn't list your scanner? Does it work as root? If yes, there is a permission issue.
30 See the
31 .B LIBUSB
32 section for details.
33 .PP
34 Nothing is found even as root? Check that your kernel supports USB and that
35 libusb is installed (see section
36 .BR LIBUSB ).
37
38 .SH "USB ACCESS METHODS"
39 For accessing USB devices, the USB library libusb is used. There used to exist
40 another method to access USB devices: the kernel scanner driver. The kernel
41 scanner driver method is deprecated and shouldn't be used anymore. It may be
42 removed from SANE at any time. In Linux, the kernel scanner driver has been
43 removed in the 2.6.* kernel series. Only libusb access is documented in this
44 manual page.
45
46 .SH LIBUSB
47 SANE can only use libusb 0.1.6 or newer. It needs to be installed at
48 build-time. Modern Linux distributions and other operating systems come with
49 libusb.
50 .PP
51 Libusb can only access your scanner if it's not claimed by the kernel scanner
52 driver. If you want to use libusb, unload the kernel driver (e.g. rmmod
53 scanner under Linux) or disable the driver when compiling a new kernel. For
54 Linux, your kernel needs support for the USB filesystem (usbfs). For kernels
55 older than 2.4.19, replace "usbfs" with "usbdevfs" because the name has
56 changed. This filesystem must be mounted. That's done automatically at boot
57 time, if
58 .I /etc/fstab
59 contains a line like this:
60 .PP
61 .RS
62 none /proc/bus/usb usbfs defaults 0 0
63 .RE
64 .PP
65 The permissions for the device files used by libusb must be adjusted for user
66 access. Otherwise only root can use SANE devices. For
67 .IR Linux ,
68 the devices are located in
69 .I /proc/bus/usb/
70 or in
71 .IR /dev/bus/usb ,
72 if you use
73 udev. There are directories named e.g. "001" (the bus name) containing files
74 "001", "002" etc. (the device files). The right device files can be found out by
75 running:
76 .I "scanimage \-L:
77 as root. Setting permissions with
78 .BR chmod (1)
79 is not permanent, however. They will be reset after reboot or replugging the scanner.
80 .PP
81 Usually
82 .BR udev (7)
83 or for older distributions the hotplug utilities are used, which
84 support dynamic setting of access permissions. SANE comes with udev and hotplug
85 scripts in the directory
86 .I tools/udev
87 and
88 .IR tools/hotplug .
89 They can be used for setting permissions, see
90 .IR /usr/share/doc/libsane/README.linux ,
91 .IR tools/README
92 and the
93 .I README
94 in the
95 .I tools/hotplug
96 directory for more details.
97 .PP
98 For the
99 .BR BSDs ,
100 the device files used by libusb are named
101 .IR /dev/ugen* .
102 Use
103 .BR chmod (1)
104 to apply appropriate permissions.
105
106 .SH "SANE ISSUES"
107 .PP
108 This section assumes that your scanner is detected by
109 .BR sane\-find\-scanner (1).
110 It doesn't make sense to go on, if this is not the case. While
111 .BR sane\-find\-scanner (1)
112 is able to detect any USB scanner, actual scanning will only work if the
113 scanner is supported by a SANE backend. Information on the level of support
114 can be found on the SANE webpage
115 .RI ( http://www.sane\-project.org/ ),
116 and the individual backend manpages.
117 .PP
118 Most backends can detect USB scanners automatically using "usb" configuration
119 file lines. This method allows one to identify scanners by the USB vendor and
120 product numbers. The syntax for specifying a scanner this way is:
121 .PP
122 .RS
123 usb
124 .I VENDOR PRODUCT
125 .RE
126 .PP
127 where
128 .I VENDOR
129 is the USB vendor id, and
130 .I PRODUCT
131 is the USB product id of the scanner. Both ids are non-negative integer numbers
132 in decimal or hexadecimal format. The correct values for these fields can be
133 found by running
134 .BR sane\-find\-scanner (1),
135 looking into the syslog (e.g.,
136 .IR /var/log/messages )
137 or under Linux by issuing the command
138 .IR "cat /proc/bus/usb/devices" .
139 This is an example of a config file line:
140 .PP
141 .RS
142 usb 0x055f 0x0006
143 .RE
144 .PP
145 would have the effect that all USB devices in the system with a vendor id of
146 0x55f and a product id of 0x0006 would be probed and recognized by the
147 backend.
148 .PP
149 If your scanner is not detected automatically, it may be necessary to edit the
150 appropriate backend configuration file before using SANE for the first time.
151 For a detailed description of each backend's configuration file, please refer to
152 the relevant backend manual page (e.g.
153 .BR sane\-mustek_usb (5)
154 for Mustek USB scanners).
155 .PP
156 Do
157 .B not
158 create a symlink from
159 .I /dev/scanner
160 to the USB device because this link is used by the SCSI backends. The scanner
161 may be confused if it receives SCSI commands.
162
163 .SH ENVIRONMENT
164 .TP
165 .B SANE_DEBUG_SANEI_USB
166 If the library was compiled with debug support enabled, this
167 environment variable controls the debug level for the USB I/O
168 subsystem. E.g., a value of 128 requests all debug output to be
169 printed. Smaller levels reduce verbosity. Values greater than 4 enable
170 libusb debugging (if available). Example:
171 .IR "export SANE_DEBUG_SANEI_USB=4" .
172 .PP
173 .TP
174 .B SANE_USB_WORKAROUND
175 If your scanner does not work when plugged into a USB3 port, try
176 setting the environment variable
177 .B SANE_USB_WORKAROUND
178 to 1. This may work around issues which happen with particular kernel
179 versions. Example:
180 .I export SANE_USB_WORKAROUND=1.
181 .TP
182 .B SANE_XEROX_USB_HALT_WORKAROUND
183 If your old (pre-2010) Xerox / Samsung / HP scanner is detected
184 only once and subsequent usage requires replugging the cable, try
185 setting the environment variable
186 .B SANE_XEROX_USB_HALT_WORKAROUND
187 to 1. This may work around issues which happen with particular USB
188 controllers. Example:
189 .I export SANE_XEROX_USB_HALT_WORKAROUND=1.
190
191 .SH "SEE ALSO"
192 .BR sane (7),
193 .BR sane\-find\-scanner (1),
194 .BR sane\-"backendname" (5),
195 .BR sane\-scsi (5)
196
197 .SH AUTHOR
198 Henning Meier-Geinitz
199 .RI < henning@meier\-geinitz.de >