8.7 Image Scanners

Written by Marc Fonvieille.

8.7.1 Introduction

In FreeBSD, access to image scanners is provided by the SANE (Scanner Access Now Easy) API available through the FreeBSD Ports Collection. SANE will also use some FreeBSD device drivers to access to the scanner hardware.

FreeBSD supports both SCSI and USB scanners. Be sure your scanner is supported by SANE prior to performing any configuration. SANE has a supported devices list that can provide you with information about the support for a scanner and its status. On systems prior to FreeBSD 8.X the uscanner(4) manual page also provides a list of supported USB scanners.

8.7.2 Kernel Configuration

As mentioned above both SCSI and USB interfaces are supported. According to your scanner interface, different device drivers are required.

8.7.2.1 USB Interface

The GENERIC kernel by default includes the device drivers needed to support USB scanners. Should you decide to use a custom kernel, be sure that the following lines are present in your kernel configuration file:

device usb
device uhci
device ohci
device ehci

On systems prior to FreeBSD 8.X, the following line is also needed:

device uscanner

On these versions of FreeBSD, the uscanner(4) device driver provides support for the USB scanners. Since FreeBSD 8.0, this support is directly provided by the libusb(3) library.

After rebooting with the correct kernel, plug in your USB scanner. A line showing the detection of your scanner should appear in the system message buffer (dmesg(8)):

ugen0.2: <EPSON> at usbus0

or on a FreeBSD 7.X system:

uscanner0: EPSON EPSON Scanner, rev 1.10/3.02, addr 2

These messages show that our scanner is using either /dev/ugen0.2 or /dev/uscanner0 as device node according to the FreeBSD version we run. For this example, a EPSON Perfection® 1650 USB scanner was used.

8.7.2.2 SCSI Interface

If your scanner comes with a SCSI interface, it is important to know which SCSI controller board you will use. According to the SCSI chipset used, you will have to tune your kernel configuration file. The GENERIC kernel supports the most common SCSI controllers. Be sure to read the NOTES file and add the correct line to your kernel configuration file. In addition to the SCSI adapter driver, you need to have the following lines in your kernel configuration file:

device scbus
device pass

Once your kernel has been properly compiled and installed, you should be able to see the devices in the system message buffer, when booting:

pass2 at aic0 bus 0 target 2 lun 0
pass2: <AGFA SNAPSCAN 600 1.10> Fixed Scanner SCSI-2 device
pass2: 3.300MB/s transfers

If your scanner was not powered-on at system boot, it is still possible to manually force the detection by performing a SCSI bus scan with the camcontrol(8) command:

# camcontrol rescan all
Re-scan of bus 0 was successful
Re-scan of bus 1 was successful
Re-scan of bus 2 was successful
Re-scan of bus 3 was successful

Then the scanner will appear in the SCSI devices list:

# camcontrol devlist
<IBM DDRS-34560 S97B>              at scbus0 target 5 lun 0 (pass0,da0)
<IBM DDRS-34560 S97B>              at scbus0 target 6 lun 0 (pass1,da1)
<AGFA SNAPSCAN 600 1.10>           at scbus1 target 2 lun 0 (pass3)
<PHILIPS CDD3610 CD-R/RW 1.00>     at scbus2 target 0 lun 0 (pass2,cd0)

More details about SCSI devices are available in the scsi(4) and camcontrol(8) manual pages.

8.7.3 SANE Configuration

The SANE system is split in two parts: the backends (graphics/sane-backends) and the frontends (graphics/sane-frontends). The backends part provides access to the scanner itself. The SANE's supported devices list specifies which backend will support your image scanner. It is mandatory to determine the correct backend for your scanner if you want to be able to use your device. The frontends part provides the graphical scanning interface (xscanimage).

The first step is to install the graphics/sane-backends port or package. Then, use the sane-find-scanner command to check the scanner detection by the SANE system:

# sane-find-scanner -q
found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3

The output will show the interface type of the scanner and the device node used to attach the scanner to the system. The vendor and the product model may not appear, it is not important.

Note: Some USB scanners require you to load a firmware, this is explained in the backend manual page. You should also read sane-find-scanner(1) and sane(7) manual pages.

Now we have to check if the scanner will be identified by a scanning frontend. By default, the SANE backends comes with a command line tool called scanimage(1). This command allows you to list the devices and to perform an image acquisition from the command line. The -L option is used to list the scanner devices:

# scanimage -L
device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner

Or, for example with the USB scanner used in the Section 8.7.2.1:

# scanimage -L
device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner

This output comes from a FreeBSD 8.X system, the 'epson2:libusb:/dev/usb:/dev/ugen0.2' item gives us the backend name (epson2) and the device node (/dev/ugen0.2) used by our scanner.

Note: No output or a message saying that no scanners were identified indicates that scanimage(1) is unable to identify the scanner. If this happens, you will need to edit the backend configuration file and define the scanner device used. The /usr/local/etc/sane.d/ directory contains all backend configuration files. This identification problem does appear with certain USB scanners.

For example, with the USB scanner used in the Section 8.7.2.1, under FreeBSD 8.X the scanner is perfectly detected and working but under prior versions of FreeBSD (where uscanner(4) driver is used) sane-find-scanner gives us the following information:

# sane-find-scanner -q
found USB scanner (UNKNOWN vendor and product) at device /dev/uscanner0

The scanner is correctly detected, it uses the USB interface and is attached to the /dev/uscanner0 device node. We can now check if the scanner is correctly identified:

# scanimage -L

No scanners were identified. If you were expecting something different,
check that the scanner is plugged in, turned on and detected by the
sane-find-scanner tool (if appropriate). Please read the documentation
which came with this software (README, FAQ, manpages).

Since the scanner is not identified, we will need to edit the /usr/local/etc/sane.d/epson2.conf file. The scanner model used was the EPSON Perfection 1650, so we know the scanner will use the epson2 backend. Be sure to read the help comments in the backends configuration files. Line changes are quite simple: comment out all lines that have the wrong interface for your scanner (in our case, we will comment out all lines starting with the word scsi as our scanner uses the USB interface), then add at the end of the file a line specifying the interface and the device node used. In this case, we add the following line:

usb /dev/uscanner0

Please be sure to read the comments provided in the backend configuration file as well as the backend manual page for more details and correct syntax to use. We can now verify if the scanner is identified:

# scanimage -L
device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner

Our USB scanner has been identified. It is not important if the brand and the model do not match the scanner. The key item to be concerned with is the `epson:/dev/uscanner0' field, which give us the right backend name and the right device node.

Once the scanimage -L command is able to see the scanner, the configuration is complete. The device is now ready to scan.

While scanimage(1) does allow us to perform an image acquisition from the command line, it is preferable to use a graphical user interface to perform image scanning. SANE offers a simple but efficient graphical interface: xscanimage (graphics/sane-frontends).

Xsane (graphics/xsane) is another popular graphical scanning frontend. This frontend offers advanced features such as various scanning mode (photocopy, fax, etc.), color correction, batch scans, etc. Both of these applications are usable as a GIMP plugin.

8.7.4 Giving Other Users Access to the Scanner

All previous operations have been done with root privileges. You may however, need other users to have access to the scanner. The user will need read and write permissions to the device node used by the scanner. As an example, our USB scanner uses the device node /dev/ugen0.2 which is in fact just a symlink to the real device node called /dev/usb/0.2.0 (a quick look at the contents of the /dev directory will confirm it). Both, the symlink and the device node, are owned respectively by the wheel and the operator groups. Adding the user joe to these groups will allow him to use the scanner but, for obvious security reasons, you should think twice before adding a user to any group, especially the wheel group. A better solution would be creating a specific group for using the USB devices and make the scanner device accessible to members of this group.

So we will use, for example, a group called usb. The first step is the creation of this group with the help of the pw(8) command:

# pw groupadd usb

Then we have to make the /dev/ugen0.2 symlink and the /dev/usb/0.2.0 device node accessible to the usb group with the correct write permissions (0660 or 0664), because by default only the owner of these files (root) can write to them. All of this is done by adding the following lines to the /etc/devfs.rules file:

[system=5]
add path ugen0.2 mode 0660 group usb
add path usb/0.2.0 mode 0666 group usb

FreeBSD 7.X users will probably need the following lines with the correct device node /dev/uscanner0:

[system=5]
add path uscanner0 mode 660 group usb

Then add the following to /etc/rc.conf and reboot the machine:

devfs_system_ruleset="system"

More information regarding these lines can be found in the devfs(8) manual page.

Now, one will just have to add users to the usb group to allow the access to the scanner:

# pw groupmod usb -m joe

For more details read the pw(8) manual page.