WikiSponsors
SDB:Configuring Scanners
tagline: From openSUSE
Contents |
[edit] Concern
You want to configure your scanner.
[edit] Procedure
To set up a scanner run the YaST Scanner module. The YaST Scanner module can be found in the YaST Control Center under Hardware -> Scanner. For more information you may have a look at YaST/Modules/Scanner at http://old-en.opensuse.org/YaST/Modules/Scanner.
Many USB scanners are set up full automated when plugged in at the USB so that there is no need to run the YaST Scanner module.
Full automated USB scanner setup happens via the udev rules file /etc/udev/rules.d/56-sane-backends-autoconfig.rules which is provided in the openSUSE package "sane-backends-autoconfig". For details see the package description (e.g. via "rpm -qi sane-backends-autoconfig"). If you do not like automated scanner driver activation, do not install this package or remove it when it is already installed.
The following paragraphs provide further information regarding the technical background and the manual configuration.
To limit the complexity of this article, only USB scanners are focused on.
Information that does not specifically apply to USB also applies to SCSI and parallel-port scanners. For SCSI scanners, see "man sane-scsi". For parallel-port scanners, see the man page for the respective backend (see section "SANE Backends" below) and the information in the manual regarding the setup of the parallel port.
[edit] Basics
The "SANE Project" provides the central software for operating scanners: http://www.sane-project.org/.
The SANE project software consists of "SANE-backends" and "SANE-frontends". In openSUSE, you find the "SANE-backends" software in the "sane-backends" package.
The SANE backends constitute the actual hardware drivers for the various scanner types; see http://www.sane-project.org/sane-backends.html.
A backend can support various models if the various models can be addressed in the same way. Such models are compatible to each other to a certain extent because they understand the same "language". Depending on the backend this language is of different kind:
- It is a primitive kind of language when the backend must directly write specific values into the chip set which controls the actual scan-unit inside the scanner. The actual values differ from model to model. Wrong values may cause poor scan quality or may even damage the scanner. Examples: the models which are supported by the "plustek" backend.
- Well built scanners have a real "scanner-language" built in. It is much easier and much more secure to drive such a scanner. Examples: The models which are supported by the "epson2" backend.
SANE stands for "Scanner Access Now Easy". By way of the "libsane" library, SANE provides a uniform API (application programming interface), enabling applications to have uniform access to various scanner models.
Applications that use a SANE backend to access a scanner are referred to as SANE frontends or simply frontends.
In addition to the SANE command line frontend "scanimage" which is included in the "SANE-backends" software, the uniform interface enables the use of other frontends like the graphical frontend XSane (see http://www.xsane.org/) which is provided by openSUSE in the package "xsane".
Rather than accessing the scanner hardware directly, a backend uses the kernel together with various subsystems for the data transmission to the scanner hardware. For example, the access to a USB scanner involves the following subsystems in addition to to the plain kernel:
- libusb (library to access USB devices)
- udev (set user access permissions to access USB devices)
- kernel modules to access USB devices
Regardless of the details, in general a stack consisting of various layers must be functional in its entirety in order to enable users to access a USB scanner from an application:
User | Application (scanner user frontend) | SANE backend (scanner driver) | libusb | udev <-- USB scanner plug-in | USB kernel modules | USB hardware in the machine | USB cable connection (additional USB hubs if necessary) | Scanner
Only the parts "SANE backend (scanner driver)" and "Application (scanner user frontend)" are what could be called "the actual scanning software".
The operability of all lower layers is a precondition for the operability of a higher layer. Therefore, the individual layers or subsystems are discussed from the bottom up.
[edit] Scanner
Run the YaST scanner module and check the list of models therein. You do not need to have a scanner connected to do this. Click "Add" and pretend to set up an imaginary scanner. Select the model and the driver from the list and click "Next" so that the YaST scanner module could show you additional messages regarding particular known issues and problems. Finally the selected driver for the model gets activated. When no scanner is connected, all what happens is that the driver tries to autodetect a scanner which will of course fail in this case.
Check the file /usr/share/doc/packages/sane-backends/sane-mfgs.html to see whether a SANE backend is available for your scanner in your installed SANE version. Please note that the accuracy of this information cannot be guaranteed. For example the vendor may use the same model name for various device variants, some of which may not be supported (e.g., see the information on "Artec/Ultima 2000").
Additionaly you may check http://www.sane-project.org/sane-mfgs.html to see whether a SANE backend is available for your scanner. The information at this site represents the latest state of the SANE software. However, please note that the accuracy of this information cannot be guaranteed. Possibly the SANE version included in your openSUSE version does not yet support your scanner.
The following list shows which scanner models are supported (or not supported), to what degree and by which backend of your installed SANE version: /usr/share/doc/packages/sane-backends/sane-backends.html.
The above HTML files are made from description files for each backend: /usr/share/sane/descriptions/"backend".desc.
The format of the entries is as follows:
:mfg "Vendor A" :model "Model 1" :interface "USB" :status :complete :model "Model 2" :interface "SCSI" :status :good :mfg "Vendor B" :model "Model X" :interface "Parport" :status :minimal :model "Model Y" :interface "IEEE-1394" :status :untested :model "Model Z" :interface "Proprietary" :status :unsupported
A considerable number of scanners are supported only by means of a so called "external backend"; see the files /usr/share/doc/packages/sane/sane-backends/sane-mfgs-external.html and /usr/share/doc/packages/sane/sane-backends/sane-backends-external.html and for the latest information see http://www.sane-project.org/lists/sane-backends-external.html
External backends are not part of the "SANE-backends" software of the SANE project. Therefore external backends are not included in the "sane-backends" package.
For every external backend, the description file /usr/share/sane/descriptions-external/"backend".desc shows which scanner models are supported or not supported to what degree.
Some scanners do not work if no suitable firmware (software in the scanner that controls the device hardware) is uploaded into the scanner when it is powered on. For such awkward models, you need to get the suitable firmware (ask the vendor of the scanner) and configure the backend for the firmware upload (see section "SANE Backends" below). As firmware is licensed by the device vendor, we are not allowed to distributed firmware with openSUSE unless the vendor makes the firmware available for distribution and redistribution under a free license. With normal scanners, the firmware is stored permanently in the device so that a normal scanner is ready to use as soon as it is powered on.
If no SANE backend is available for the scanner (see http://www.sane-project.org/sane-backends.html#S-UNSUPPORTED and the file /usr/share/sane/descriptions/unsupported.desc), the device cannot be used with one of the common frontends (scanimage, xsane). Possibly there may be other software (e.g., directly from the vendor - ask the vendor about this). If not, the device cannot be used.
[edit] USB Cable Connection and Additional USB Hubs
Maximum length of USB cables:
- Inexpensive low-speed cables (not twisted, not shielded - see the Wikipedia page on USB Cabling): No more than 3 meters. Not suitable for fast data transfer (USB 2).
- Higher-quality full-speed and high-speed cables (twisted, shielded): No more than 5 meters.
- If a USB hub is interposed, the maximum length may be shorter, depending on the properties of the cable and the hub.
Some scanners do not have a built-in power supply but draw power via USB. If your USB system does not provide enough power, a scanner of this kind will not work. In this case, try if it works with an interposed USB hub with a separate power supply.
[edit] USB Hardware + USB Kernel Modules + udev
The details here change from version to version. An article regarding scanner setup cannot describe all the details about the various lower levels. Refer to the appropriate specific documentation if there are problems in one of these areas.
A USB scanner must be displayed by the following command:
(run it both as root and as normal user), or, should command above not be available:
If this command do not display the scanner model, the data transfer between the machine and the scanner cannot work because the kernel could not recognize the USB device or not all required USB kernel modules were loaded.
To test the system in the event of problems, connect the scanner directly to the machine as the only USB device (apart from a USB keyboard or USB mouse if any). Then reboot the system while keeping the scanner switched on. Normally, hotplug/udev makes sure that the needed USB kernel modules are loaded automatically. Immediately after the reboot, view the USB kernel messages with
and look for any error messages such as "error" or "fail".
Check if the USB kernel modules needed for the particular machine's USB hardware are loaded. Check if your machine's USB hardware (i.e., the USB chipset) is supported. The command "lspci | grep -i usb" lists the USB controllers; see http://www.linux-usb.org/
[edit] USB scanner access permissions via udev
The details here change from version to version. An article regarding scanner setup cannot describe all the details about the various lower levels. Refer to the appropriate specific documentation if there are problems in one of these areas.
A backend accesses a USB scanner via libusb. This takes place via /proc/bus/usb/xxx/yyy or via /sys/bus/usb/devices/ or via /dev/bus/usb/xxx/yyy (the actual location changed and changes all the time from kernel/udev/libusb/whatever... version to version) where xxx (bus ID) and yyy (device ID) are no fixed values.
Since kernel 2.6, no static device file (like /dev/usbscanner which was used with kernel 2.4) is used for the access via libusb. Rather, the entries in /proc/bus/usb/ or /dev/bus/usb/ (or wherever it actually is for the current version) are generated anew every time the system is booted and/or whenever a scanner is unplugged and re-plugged to the USB (perhaps even when a USB scanner is switched off and on). Therefore, access permissions can no longer be set permanently as usual with the traditional "chmod" command.
The best workaround to get those kind of issues out of sight is to use the "saned" which is a service for scanning via network. On the server the saned is set up and launched via xinetd. On the client the "net" meta-backend is used for scanning via network. See "man saned" and "man sane-net". By using the loopback network this can be used on the local host too. In this case server and client are the same machine "localhost". To access a scanner via the "saned" on the local host you may set up the following:
- Let the saned run as root (default in /etc/xinetd.d/sane-port)
- Allow access from "localhost" in /etc/sane.d/saned.conf
- Specify the server "localhost" in /etc/sane.d/net.conf
- Activate the "net" meta-backend in /etc/sane.d/dll.conf
In the YaST scanner configuration, you can set up such a "Local Host Configuration" via "Other" and "Scanning via Network". Usually this is the easiest workaround when there are scanner access problems for normal users. A little drawback is that scanning frontends for the user root will recognize the scanner twice. Once directly as "backend:..." and a duplicate via the net meta-backend as "net:localhost:backend:...".
You can limit the access to certain users in /etc/sane.d/saned.users with certain saned-specific passwords. To keep the passwords secret make sure that only root has read-access to this file.
To have firewall protection against unwanted access to the saned, see SDB:CUPS and SANE Firewall settings
Alternatively you may change the udev access permission settings:
udev is used to set read/write permissions via ACL (run "getfacl /dev/bus/usb/<bus-number>/<device-number>" to show them) for the one normal desktop user who is currently logged in locally (i.e. logged in via graphical XDM/Kdm) so that the currently logged in desktop user gets sufficient permissions to use the scanner unit as normal user.
The udev rules from the sane-backends package are in /etc/udev/rules.d/55-libsane.rules - see "man udev" how to make such entries.
For scanners in HP all-in-one devices there is a special complication in the udev rules because HP all-in-one devices have additional udev rules from the hplip package in /etc/udev/rules.d/55-hpmud.rules which are set before the udev rules from the sane-backends package in /etc/udev/rules.d/55-libsane.rules so that entries in /etc/udev/rules.d/55-libsane.rules may overwrite settings in /etc/udev/rules.d/55-hpmud.rules.
[edit] SANE Backends
Every backend has its own configuration file /etc/sane.d/"backend".conf and its own man page: "man sane-backend" (replace "backend" with the name of the respective backend).
One of the backends has a special function: The "dll" backend is a meta-backend (see http://www.sane-project.org/html/doc005.html). The dll backend enables a single frontend to access various scanners by way of other backends. The access takes place as follows:
user
|
frontend
|
------ dll meta-backend ------
| |
backend_A backend_B
| |
... ...
| |
scanner A scanner B
The dll meta-backend is always interposed, even if there is only one scanner.
The backends to be used by the dll meta-backend must be activated as follows in /etc/sane.d/dll.conf, the configuration file of the dll meta-backend:
# SANE Dynamic library loader config backend_A backend_B # backend_C
In this example, the backends "backend_A" and "backend_B" are activated and "backend_C" is deactivated.
Normally it should be sufficient only to activate the appropriate backend in /etc/sane.d/dll.conf to make an USB scanner ready to use - provided the USB system and the udev layer work correctly and the backend automatically detects the USB scanner and the scanner has a built-in firmware.
If several backends are activated at the same time, there may be a conflict between the backends. If this is the case, try if it works if you only activate one backend at a time. In this way you can check whether a backend does not work at all or if the problem is merely caused by a conflict with a certain other backend.
Manual modifications may be necessary in /etc/sane.d/"backend".conf depending on the scanner model, the way how it is connected (e.g., via USB or SCSI), and the respective backend. In any case, be sure to read the comments in /etc/sane.d/"backend".conf and the man page for the respective backend with "man sane-backend" (replace "backend" with the name of the respective backend).
Examples:
Normally, a backend automatically detects the USB scanners it supports. If this does not happen, it should be possible to add a line such as the following in /etc/sane.d/"backend".conf:
usb 0xVVVV 0xMMMM
Based on the output of "lsusb", enter the hexadecimal vendor ID for 0xVVVV and the hexadecimal model ID for 0xMMMM. For certain backends the syntax "usb 0xVVVV 0xMMMM" may be different or not available at all, see the man page for the respective backend.
For SCSI scanners, enter a line such as the following for the SCSI device file in /etc/sane.d/"backend".conf:
scsi /dev/sg0
Caution: An incorrect SCSI device file can render your system inoperable!
For parallel-port scanners, manually enter a line such as one of the following in /etc/sane.d/"backend".conf:
ieee1284 parport0
(e.g., in /etc/sane.d/canon_pp.conf)
pio 0x378
(e.g., in /etc/sane.d/epson.conf)
device 0x378
or
parport0
(e.g., in /etc/sane.d/plustek_pp.conf) Caution: An incorrect entry can render your system inoperable!
For some scanners, suitable firmware must be uploaded into the scanner. Get the suitable firmware file (ask the vendor) and enter the firmware file name in /etc/sane.d/"backend".conf. Caution: Unsuitable firmware can damage the scanner!
As a backend is usually suitable for several scanner models, the default settings must reflect the least common denominator of all supported models. Therefore, you may want to optimize the settings for a specific model in /etc/sane.d/"backend".conf. Caution: Incorrect settings might damage the scanner!
[edit] Frontend
For test purposes, use the command-line frontend "scanimage" (see "man scanimage").
"scanimage -L" should display your scanner. If this does not happen, SANE (more precisely: the backend) is not able to access the scanner. If "scanimage -L" only displays the scanner when the command is executed by the user "root", only root is able to access the scanner, but not the normal users. In this case, the problem lies in the "USB scanner access permissions via udev" layer. The output of "scanimage -L" for a USB scanner has usually the following format
device 'backend-name:libusb:bus-ID:device-ID' ...
and for a SCSI scanner
device 'backend-name:/dev/sg[0123...]' ...
The actual SANE device string format (e.g. libusb:bus-ID:device-ID or /dev/sg[0123...]) depends on the particular backend.
The command "scanimage -d Device >/tmp/image.pnm" prompts the scanner to scan an image and save the result in the file /tmp/image.pnm. Replace "Device" with the SANE device string according to the output of "scanimage -L". Example:
The scanning procedure takes place with the default settings of the respective backend.
"scanimage -d Device -h" lists all available options. The first part lists the general options that do not depend on the respective backend. The second part lists the backend-specific options with the possible values or ranges and the respective default settings in square brackets. Example:
Options specific to device 'backend:libusb:123:456':
Scan Mode:
--mode Gray|Color [Color]
Selects the scan mode.
--resolution 75..600dpi [150]
Sets the resolution of the scanned image.
Geometry:
-l 0..216mm [0]
Top-left x position of scan area.
-t 0..297mm [0]
Top-left y position of scan area.
-x 0..216mm [216]
Width of scan-area.
-y 0..297mm [297]
Height of scan-area.
For example, the command for scanning a b/w picture of 10 x 15 cm in portrait orientation with 300 dpi may be as follows:
[edit] Scanning via Network
Assume there is a USB scanner connected to one host (the "server") and you like to acces it from another host (the "client").
A precondition is that scanning already works on the server.
To grant additional access via network, you can use "saned" which is a service for scanning via network. On the server the saned is set up and launched via xinetd. On the client the "net" meta-backend is used for scanning via network. See "man saned" and "man sane-net".
- On the server let the saned run (set "disable = no" in /etc/xinetd.d/sane-port and start the xinetd)
- On the server allow access from the client in /etc/sane.d/saned.conf
- On the client specify the server in /etc/sane.d/net.conf
- On the client activate the "net" meta-backend in /etc/sane.d/dll.conf
In the YaST scanner configuration, you can set up such a configuration" via "Other" and "Scanning via Network".
Note the security warning when you read "man saned":
saned is not intended to be exposed to the internet or other non-trusted networks.
Therefore use a firewall which is set up accordingly, see SDB:CUPS and SANE Firewall settings
The following stack consisting of various layers must be functional in its entirety in order to enable users to access a USB scanner which is connected to a remote host from the user's local worksatation where the user application runs:
User | Application (frontend) | SANE net (meta-backend on the client) | Client network interface | client machine Network ======================================= | server machine Server network interface | SANE saned (meta-frontend for the backend) | SANE backend (actual driver for the scanner) | libusb | USB kernel modules | USB hardware in the server machine | USB cable connection | Scanner
This kind of setup for scanning via network makes sense only when the client workstation is also located next to the scanner (in particular when both the client and the server with the scanner are located in the same room).
In contrast a powerful network printer scanner copier all-in-one device is usually used in a different way by "stand-alone scanning to e-mail" where neither a particular scanner driver software nor any SANE software is involved at all.
Normally one can scan directly on a professional network printer scanner copier and specify scan resolution and image file format (e.g. tiff, PDF, ...) and all the other scanning options directly at the device and in particular one can specify an e-mail address to which the device will send the scanned image file so that one will receive the scanned image as a mail attachment according to what was specified as image file format.
Before you buy a network printer scanner copier, check carefully that the particular device does support "stand-alone scan to e-mail" (without any additional software) and that the device provides a well usable user interface for daily work.
This way of operating is usually much more convenient for the user because when you would use a SANE backend you would have to specify all the scanning parameters on your workstation by using a SANE frontend.
But when your workstation is far away from the network scanner device, you would have to walk to the network scanner to place your sheet of paper in it and post a big red note on the network scanner that you are currently using it for scanning so that others know what is going on and don't remove your sheet, then walk back to your workstation to specify the scanning parameters and start the scan and finally you would have to walk again to the network scanner to fetch your sheet and remove your note and walk back to your workstation. On the other hand this way of operating is much better for your physical health ;-)
[edit] Trouble-Shooting (Debugging)
For debugging the debug-messages of the various layers in SANE and the verbose mode of "scanimage" are useful. See "man sane-usb", "man sane-scsi", "man sane-dll", "man sane-backend" and "man scanimage". Replace "backend" with the name of the respective backend. Replace "Device" either with the name of the respective backend or with a complete SANE device like "backend:libusb:123:456" (see the "Frontend" section).
Examples:
Testing without debug-messages:
Testing with only the debug-messages of the "dll" meta-backend. Useful when for example the "dll" meta-backend cannot find or load the actual backend or more pecise the backend library "/usr/lib[64]/sane/libsane-backend.so...":
export SANE_DEBUG_DLL=4 scanimage -d Device -v >/dev/null && echo OK || echo FAILED unset SANE_DEBUG_DLL
Testing with only the debug-messages of the actual backend. The debug value depends on the particular backend, see "man sane-backend" (replace "backend" with the name of the respective backend):
export SANE_DEBUG_backend=128 scanimage -d Device -v >/dev/null && echo OK || echo FAILED unset SANE_DEBUG_backend
Testing with only the debug-messages of the USB system (regarding SCSI see "man sane-scsi"):
export SANE_DEBUG_SANEI_USB=128 scanimage -d Device -v >/dev/null && echo OK || echo FAILED unset SANE_DEBUG_SANEI_USB
Combinations are possible but may make it more difficult to find errors because there may be too many debug-messages at once:
export SANE_DEBUG_DLL=4 export SANE_DEBUG_backend=128 export SANE_DEBUG_SANEI_USB=128 scanimage -d Device -v >/dev/null && echo OK || echo FAILED unset SANE_DEBUG_SANEI_USB unset SANE_DEBUG_backend unset SANE_DEBUG_DLL
[edit] Third-Party Scanner Drivers
A third-party driver is proprietary software when it contains at least one part which is proprietary software - usually a proprietary binary-only library which might be called a "module".
For proprietary software nobody - except the authors or vendor of the proprietary software - can provide any kind of help and support because nobody - except the authors or vendor - know how their proprietary software really works.
In this case you can only contact those wherefrom you got the proprietary software for any kind of help and support.
If third-party scanner driver software does not work in compliance with SANE you can only contact those wherefrom you got the third-party driver for help and support.
If third-party scanner driver software works in compliance with SANE:
The YaST2 scanner module cannot support third-party scanner drivers because there is no defined way in SANE how third-party scanner driver software must install so that generic scanner setup software (like the YaST2 scanner module) could support it.
But generic scanner setup support is usually not needed because:
Basically third-party scanner driver software which works in compliance with SANE should add its driver name during installation of the driver software to /etc/sane.d/dll.conf so that the driver is activated and then the driver should work, see "SANE Backends" above.
After you installed a third-party scanner driver which works in compliance with SANE, verify that its driver is listed in /etc/sane.d/dll.conf so that the driver is activated.
Afterwards check if "scanimage -L" (run it as root and as normal user) finds the scanner, see "Frontend" above.
If the driver is activated via /etc/sane.d/dll.conf but "scanimage -L" does not find the scanner when you run it as root, it is actually the driver which does not find the scanner which means that the driver does not work.
If "scanimage -L" finds the scanner when you run it as root but does not find it when you run it as normal user, there is usually an access permission issue, see "USB scanner access permissions via udev" above.
It would not help if YaST supports a third-party scanner driver because all what YaST could do is to activate the driver in /etc/sane.d/dll.conf but YaST cannot fix a driver which is activated but does not work.
If a third-party scanner driver does not work, you may try to debug it on your own, see "Trouble-Shooting (Debugging)" above or contact those wherefrom you got the third-party driver for further help and support.