TWAIN SANE Frequently Asked Questions

The TWAIN SANE Interface says “no image source found”, but my scanner is connected to my computer and is turned on

There can be several reasons for this. Some scanners — especially older SCSI scanners — from the era before the introduction of plug-and-play devices can not be detected unless they were turned on at the time your computer was started. If you have such a scanner try restarting your computer with your scanner turned on.

Another reason might be that the SANE backend that is used when scanning with your scanner must be configured for your hardware configuration in order to support autodetection. The device names on MacOS X are not necessarily invariant between reboots of the computer, so it is essential that autodetection of the device is working.

When trying to make things work, it helps if you are not trying to fix to many things on the same time. You should first make sure that the SANE libraries work with your scanner. Later, once the SANE libraries are configured properly for your hardware, make the configured libraries work together with the TWAIN SANE Interface. If the SANE libraries don’t work on their own, the Interface can not possibly work!

How do I configure the SANE backends for my scanner?

The full and complete information about how to configure the SANE backend libraries depends strongly on which of the many backends that supports your scanner. For the most part this is not a MacOS X specific issue, but a backend specific issue. First find out which of the many provided backends that is supposed to support your scanner by consulting the list of supported devices on the SANE project website. Then find the specific details about how to configure this backend form the backend specific pages that you can reach by clicking on the links in the table.

First try to scan using the SANE libraries without using the Interface. The SANE backends package contains not only the SANE libraries but also some programs that can be run from the command line in the Terminal application.

Start the Terminal application (it should be located in the Utilities folder within the Applications folder), then type in the Terminal window the command:

scanimage > test.pnm

If you get an error message like “scanimage: command not found” see the next section.

If everything is OK this should start a scan on your scanner and save the acquired image as a PNM file in your home folder. If you rather want a TIFF file use

scanimage --format tiff > test.tiff

If it doesn’t work, you might be able to make it work by editing the configuration file for your backend. This is most easily done using the SANE Preference Pane. If you don’t have this installed you can edit the configuration files using some text editor (e.g. emacs) in the Terminal application. To edit the file use a command like the following from within the Terminal:

sudo emacs /usr/local/etc/sane.d/〈name of your backend〉.conf

Note: The configuration files are common to all users on your computer and can only be changed by someone with administration privileges. For this reason the sudo command must be used. The first time you use the sudo command you will be asked for your password, but if you do sudo again the authorization from the first sudo will still be valid. After some time the authorizaton will expire and you will be asked for your password again.

You can try to use the following commands to see if the SANE libraries can find your scanner:

sane-find-scanner
scanimage -L

Note that there are no entries in the /dev directory for scanners on MacOS X and for USB devices it relies entirely on libusb for communication. Backends for USB devices that don’t support libusb does not work on MacOS X.

Read the comments in the configuration file and the information available on the backend specific web pages to get details about what to write in the configuraton file. If you are using the SANE Preference Pane you can get information by clicking on the help button for your backend.

You can also browse through the archive of the sane-devel mailing list and the SANE bug tracker to see if someone else have had the same problems as you are experiencing.

If you can not make the backend for your scanner work you should try using the test backend. Try scanning using the command

scanimage -d test:0 > test.pnm

If this works, but you can not get your scanner to work there is something wrong with the backend you are trying to use, either in the configuraion of it or there is a bug in it. In this case you should ask the maintainers of the backend you are using. You could also send your questions to the sane-devel mailing list. Sending to this list requires registration.

To get more information about what exactly goes wrong with your backend you should activate the debugging output for your backend:

For bash:
SANE_DEBUG_〈name of your backend in capitals〉=n scanimage > test.pnm
For tcsh:
(setenv SANE_DEBUG_〈name of your backend in capitals〉 n; scanimage > test.pnm)

where n is a number between 1 and 255. The higher the number the more debugging information you should get. Other useful debugging variables are SANE_DEBUG_SANEI_SCSI (for SCSI scanners), SANE_DEBUG_SANEI_USB (for USB scanners) and SANE_DEBUG_SANEI_THREAD for the SANE thread functions. You can use more than one of them at a time, which is usually a good idea, since you then can get information about how the different parts of SANE interact.

If you want to save the debugging output to a file instead of writing it to the Terminal you can do the following:

For bash:
SANE_DEBUG_〈name of your backend in capitals〉=n scanimage > test.pnm 2> log.txt
For tcsh:
(setenv SANE_DEBUG_〈name of your backend in capitals〉 n; scanimage > test.pnm) >& log.txt

I try to run the scanimage program but get an error message “scanimage: command not found”

When you enter a command on the command line, the system searches for a program or script with the same name to execute. The list of directories that are searched are those in the colon separated list in the PATH environment variable. To see your current PATH use the command

echo $PATH

The scanimage program is located in the /usr/local/bin directory, if this directory is not mentioned in your PATH the system won’t find it. Use one of the following commands (depending on which shell you are using) to add this directory to your path:

For bash:
export PATH=$PATH:/usr/local/bin
For tcsh:
setenv PATH ${PATH}:/usr/local/bin

If you don’t know which shell you are running you can find out by using the command

echo $SHELL

I added /usr/local/bin to my path, but the next time I start the Terminal application it is not there any more

If you want to automatically set the path every time you start the Terminal application, you should create a property list file called environment.plist containing an entry with the key PATH and a value equal to the path you want to have. A property list file is an XML file, an example of which can be found here. If you have installed the Developer tools you have a special Property List Editor application in /Developer/Application/Utilites, but you can edit the file in a normal text editor if you don’t have this installed.

If you use a text editor make sure the file is saved in plain text format, and not in e.g. RTF or some other styled text format. Also make sure that you remove any additional extension to the filename the editor might add to the filename. The Finder can sometimes hide the last extension from the user so that a file named environment.plist.txt is displayed as environment.plist in the Finder. To make sure you see the complete name of the file make sure the “hide extension” checkbox is unchecked if the file’s File Info dialog.

You should then put this file in a folder called “.MacOSX” in your home folder. You will not be allowed to name a folder this way in the Finder, so you have to first give it an other name, like e.g. “MacOSX”. Then put the environment.plist file in it, and then rename it from the Terminal application using the command

mv MacOSX .MacOSX

Note that the folder will no longer be seen in the Finder, since files and folders whose names begin with a point are hidden files. Starting from the next time you log in, the system will set your path according to your environment.plist file.

Scanning using the scanimage program works, but when I try to use the TWAIN SANE Interface it doesn’t work

Start the application from the command line instead of doubleclicking on its icon. If your application is of the CFM (Code Fragment Manager) type, you must start it using the LaunchCFMApp application like in the following two examples. Since the command line in these examples are long, they have been broken into several lines. If you type them on one line you should skip the \ signs that tells the shell the command continues on the next line.

/System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp \
/Applications/GraphicConverter/Contents/MacOS/GraphicConverter
/System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp \
"/Applications/OmniPage Pro X/Components/OmniPage Pro X"

To obtain more information you can set the debugging environment variable for your backend to a reasonable number.

For bash:
SANE_DEBUG_〈name of your backend in capitals〉=n \
/System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp \
/Applications/GraphicConverter/Contents/MacOS/GraphicConverter
For tcsh:
(setenv SANE_DEBUG_〈name of your backend in capitals〉=n; \
/System/Library/Frameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp \
/Applications/GraphicConverter/Contents/MacOS/GraphicConverter)

where n is a number between 1 and 255. The higher the number the more debugging information you should get. Other useful debugging variables are SANE_DEBUG_SANEI_SCSI, SANE_DEBUG_SANEI_USB and SANE_DEBUG_SANEI_THREAD. For information about how to save the debugging information to a file instead of writing it to the Terminal see above.

Also try to use a test device provided by the test backend instead of your scanner and see if that works with your application. Use the SANE Preference Pane to activate the test backend. Or, if you don’t have this installed, edit the configuration file for the dll backend (the one the loads all the other backends) using a text editor in the Terminal:

sudo emacs /usr/local/etc/sane.d/dll.conf

and remove the # sign on the line that says “#test”. After doing this restart your application and select one of the image sources provided by the test backend.

My scanner works with other applications, but not with Image Capture

Image Capture uses the TWAIN Bridge application to talk to TWAIN data sources. This is a really weird application. Firstly, it does not — like normal TWAIN capable applications — let the TWAIN data source try to find a scanner it supports by itself. Instead it requires a list of vendor and product IDs of all supported scanners to be present in the TWAIN data source’s property list (/Library/Image Capture/TWAIN Data Sources/SANE.ds/Contents/Info.plist). So the first thing to do is to check if your scanner’s IDs are in this list and if not add them. See Apple Technical Note TN2088 for details about the format of this file. If you succeed with this let me know, and I can add the numbers to the default list for the next release.

Secondly, someone at Apple made a really weird decision that the TWIAN Bridge should only support hotpluggable devices. This means that any scanner that only supports coldplug can not be used by the TWAIN Bridge. In normal applications coldplug is always supported. If your scanner is USB or Firewire it is hotpluggable and you should be able to add an entry for it in the property list to make it work. If you have a SCSI scanner that only supports coldplug, adding the correct IDs to the property list won’t help. In this case you can play a trick and add the IDs for some other connected USB device and pretend it is a scanner. The TWAIN Bridge will then detect this “scanner” and start running and once this happens you can use your non-hotpluggable device. I have managed to trick Image Capture to accept my non-hotpluggable HP SCSI scanner by adding a fake entry for my USB mouse in the property list. The same trick must be used if you want to use a saned server (i.e. the net backend) as your image source without having a hotpluggable scanner connected locally.

Update: Starting from MacOS X 10.5 it is no longer possible to trick the TWAIN Bridge with the USB IDs of an Apple mouse or an Apple keyboard. Using the USB IDs of a USB memory stick still does the tick though.

My scanner works with other applications, but not with Adobe PhotoShop

Default installations of recent versions of Adobe PhotoShop are not TWAIN compatible, but require a TWAIN plugin to be installed. For more information about this see Adobe tech note 405072.

When I try to scan I get an error message about a missing firmware file

Some scanners require a piece of software called firmware that must be uploaded to the scanner and executed on the scanner’s processor. You can normally find this firmware file on the installation CD that came with your scanner or download it from the scanner manufacturer’s website or from the website of the SANE backend maintainer. You can use the SANE Preference Pane to install or uninstall firmware files with drag and drop from the Finder. Once you have installed the firmware file on your computer you might have to specify its name and location in the backend configuration file.

When trying to scan I get the message “another process has device opened for exclusive access”

When SANE loops through the devices you will get this message for many of your non-scanner devices, like your keyboard and your mouse. But, if you get this message for your scanner (check the USB IDs in the log) there might be some other driver claiming the device. To turn off this driver, open the System Preferences and choose Accounts then select the Startup Applications tab and deselect the driver. You might have to reboot for the new selection to take effect.

SCSI scanners with more than one logical unit number

Some SCSI scanners present themselves to the computer as more than one device, but with different logical unit numbers (LUNs). For these devices it is important to make sure that SANE is communicating with the device whose LUN is 0. A device with multiple LUNs is listed more than once in the output from sane-find-scanner:

found SCSI scanner "UMAX Astra 600S V1.2" at <012f5c00000000161e25d0af>
found SCSI scanner "UMAX Astra 600S V1.2" at <012f5a00000000161ede71d3>
found SCSI scanner "UMAX Astra 600S V1.2" at <012f5200000000161f97da74>
found SCSI scanner "UMAX Astra 600S V1.2" at <012f500000000016204fd11f>
found SCSI scanner "UMAX Astra 600S V1.2" at <012fb8000000001621073c0e>
found SCSI scanner "UMAX Astra 600S V1.2" at <012fb6000000001621c332a9>
found SCSI scanner "UMAX Astra 600S V1.2" at <01303e0000000016227c91b9>
found SCSI scanner "UMAX Astra 600S V1.2" at <011cfe0000000016233552dc>

If you have a scanner like this you have to specify the LUN in the configration file for the SANE backend used by your scanner. The LUN is the 7th parameter to the scsi keyword, so you have to pad with stars to get the defaults for the parameters before. If, as an example, the line reads

scsi UMAX * Scanner

change it to

scsi UMAX * Scanner * * * 0

My USB scanner supported by the microtek2 backend does not work

USB scanners supported by the microtek2 backend only work on Linux. The reason for this is that the backend is implemented by using the microtek Linux kernel module. If these scanners are going to work on other operating systems the functionality of the microtek Linux kernel module must be reimplemented using e.g. libusb.

My SCSI scanner doesn’t work any more after upgrading to MacOS X 10.5

Apple dropped support for some older SCSI cards in the default system installation in MacOS X 10.5. This happened to my Adaptec 2930CU card. I got it working by installing the driver downloadable from the Adaptec web site. This driver is powerpc only (no intel version available) and quite old (2002) but works for me with MacOS X 10.5, miraculously. Adaptec’s site for legacy products can be found here.

Can I use the TWAIN SANE Interface to scan over the network from a scanner on a saned server?

Yes. First make sure you are allowed to connect to the saned server. You should also configure the net backend on your computer to search for devices on the remote computer by editing the net backend configuration file using the SANE Preference Pane. Or, if you don’t have this installed, by using a text editor in the Terminal:

sudo emacs /usr/local/etc/sane.d/net.conf

Press the help button for the net backend in the SANE Preference Pane or consult the sane-net man page for more information. I have successfully scanned over the network from a Fedora Linux server exporting the test backend.

Can I share my scanner connected to my Macintosh with other users over the network?

Yes. You have to start the saned server. This can be done using the SANE Preference Pane. If you don’t have this installed you have to create a xinetd configuration file called sane-port in the /etc/xinetd.d/ directory yourself. An example can be found here. Then make sure that there is a line defining the sane-port in /etc/services. The following lines can be found in the default /etc/services, so you probably don’t have to add it yourself.

sane-port 6566/udp # SANE Control Port
sane-port 6566/tcp # SANE Control Port

The SANE Preference Pane lets you add the hostnames, IP addresses or subnets of the computers for which you want to allow access to you scanner. If you don’t have this installed you have to edit the saned configration files by hand.

If you want the changes to the xinetd settings to take effect without restarting the computer run the command

sudo killall -SIGHUP xinetd

This is done automatically if you use the SANE Preference Pane to activate saned.

If you are running a firewall on your computer, you should know that the saned server uses port 6566 as the control port, but it also uses randomly assigned free ports in the range 1024-65535 for data transfers. So you have to open this range of ports for access from the computers that should be allowed to use your scanner remotely.

If you use the option to restrict the port range used by saned for data transfers, you only need to open the selected range of ports in the firewall — and port 6566 of course.

I have successfully used my HP SCSI scanner connected to my Macintosh from a laptop running Fedora Linux over the network using the saned server on the Macintoch.

How do I select which graphical user interface (GUI) to use in Image Capure?

When you are running Image Capture you have a choice between two different GUIs. You can either use Image Capture’s native GUI which provides basic options, or you can use the GUI that the TWAIN SANE Interface provides which gives access to all options available in the SANE backend supporting your scanner. To select which GUI is used you should select “Browse devices...” from the Devices menu. In the list of Image Capture Devices that is displayed, in the section TWAIN devices, you will find an entry called SANE. If you select this entry, there will appear, at the bottom of the window, a check-box with the titel “Use TWAIN software”. If you select this check-box, the TWAIN SANE Interface’s GUI will be used, if you deselect it, Image Capture’s native GUI will be used. You have to quit and restart the Image Capture application in order for a new selection to become active.

Update: The ability to use the TWAIN GUI in Image Capture seems to have been disabled in the version included in MacOS X 10.6.

When I try to install the packages it complains saying I should install the MacOS X 10.x.y SDK first

You are trying to install one of the SDK packages that is intended to be used together with the MacOS X cross compilation SDK that can be used if you want to compile programs for older versions of MacOS X. If you are only interested in running the software you should not install the SDK packages. The SDK packages are intended for software developers.

If you just want to run the programs the binary packages are sufficient.

If you are a software developer and want to use the cross compilation SDKs for MacOS X that are part of the Xcode installation. The SDK packages only contain header files and stubbed libraries (containing only the linking symbols, no executable code).

When I try to install the packages there is an error message saying that the “bill of materials” is missing

This happens if you expand the compressed package files with StuffIt expander with the “Continue to expand if possible” option set in the StuffIt preferences. An installer package contains compressed files. If these are expanded the installer package becomes broken. Try again with the “Continue to expand if possible” option unset or use a different tool for expanding the files.

When I try to install the packages there is an error message saying that “an error was encountered while running the InstallationCheck tool”

This happens if you unpack the .tar.gz file using a program that removes the execution permissions from the unpacked files. Try unpacking the downloaded file using a different program or restore the execution permission on the InstallationCheck script manually. I have reports that the unpacking program “Zipeg” has this behaviour.

Starting from version 3.2 the installation packages are in the “flattened” (single file) format and no longer in the “bundle” (multiple file) format. It is therefore no longer necessary to archive (tar) the installation package in order to properly transfer it over the network. There should no longer be any issues caused by unpacking the downloaded file, since the file does not need unpacking before installation.

Is there an uninstaller for the packages?

The major disadvantage of the Apple Installer is that there at the moment is no unistall option implemented in it. However, there is nothing that prevents you from removing the installed files manually.

To get the list of files and directories installed by a package do the following (in the Terminal):

lsbom /private/var/db/receipts/〈id of the package〉.bom

The id of the packages are the long identifiers for the installed components: se.ellert.twain-sane, se.ellert.preference.sane, org.sane-project.sane-backends, net.sourceforge.libusbx. List the contents of the receipts directory for a complete list of installed packages.

The TWAIN SANE Interface and the SANE Preference Pane are installed in the Mac OS X part of the file system and can be uninstalled by simply dragging them from their install locations to the Trash. The install locations are /Library/Image Capture/TWAIN Data Sources/SANE.ds and /Library/PreferencePanes/SANE.prefPane.

The other packages are installed in the Unix part of the file system (in this case in /usr/local) and are therefore not visible from the Mac OS X desktop. So to remove these packages you need to remove the installed files and directories manually from the Terminal. Simply remove the files in the list obtained from lsbom as described above, and the directories in the list if they are empty. Do not forcefully remove any directories if they are not empty, since then you will remove files installed by other packages. (If the directory contains only a file named “.DS_Store” it can be safely removed.)

After removing the files you might also want to remove the “receipt” for the installation. This can be done using pkgutil:

pkgutil --forget 〈id of the package〉

Mattias Ellert