NIASH chipset based flatbed scanners - HOW-TO

Table of Contents

  1. Introduction
    1. Requirements
    2. Where to obtain the required software
  2. Preparing the system
    1. Linux kernel version and capabilities
    2. Previously installed software
    3. Device files (kernel method)
      1. With devfs
      2. Without devfs
    4. Installing libUSB (libusb method)
  3. The test tool
  4. The SANE backend
  5. Places to look for more information
  6. Known Bugs (Caveats)
  7. Reporting Bugs

1 - Introduction

This project's goal is to implement a SANE backend for flatbed scanners with the NIASH chipset, the following document describes and explains the procedures to undertake in order to fully install and configure a working version of the package. Although the major aim was to write a SANE backend, to ease the testing and experimenting, a test tool was also built, it shares most of the code with the SANE backend, but provides a simpler interface and (hopefully) turns the building and configuration processes, as well as error and bug tracking more easy to cope with. Since this project is in alpha stage, it is therefore recommended that users build and use this test tool before trying to build the SANE backend.

As of the date of this writing, the package makes use of two distinct ways of accessing USB scanners:

The default under GNU/Linux systems is to build the package with both methods (if available) and let the user choose which to use at run time. Alternatively the user might want to build the package with just one of the methods, which is perfectly possible (see details bellow). Note that under the free BSDs the package will only be built with the LibUSB method.

In all the examples below we will use a ficticious release whose revision number is 2, release date the 28th of January 2002, and distribution file testtool-20020128_2.tar.gz.

Please note that this tools are provided with no warranty, use them at your own risk.

1.1 - Requirements

1.2 - Where to obtain the required software

2 - Preparing the system

The following itens should be checked before trying to install the package:

2.1 - Linux kernel version and capabilities

It is mandatory that you run a 2.4 series Linux kernel (at least version 2.4.13 to use the kernel method) with the following itens compiled as modules or builted in:
Capability Module Notes
Support for USB - CONFIG_USB usbcore.o Required
Preliminary USB device filesystem - CONFIG_USB_DEVICEFS n/a Required to use libusb method, optional otherwise
UHCI (Intel PIIX4, VIA, ...) support - CONFIG_USB_UHCI usb-uhci.o Required on systems with an UHCI USB controller
UHCI Alternate Driver (JE) support - CONFIG_USB_UHCI_ALT uhci.o An alternative driver for UHCI USB controllers (compile this or the previous, only one is required)
OHCI (Compaq, iMacs, ...) support - CONFIG_USB_OHCI usb-ohci.o Required on systems with an OHCI USB controller
USB Scanner support - CONFIG_USB_SCANNER scanner.o Required to use the kernel method, not recommended to use the libusb method

2.2 - Previously installed software

In order to properly build SANE with the NIASH backend, you should remove any previously installed version of SANE and all related packages (thanks to Harman Nagra for pointing this out).

2.3 - Device files (kernel method)

2.3.1 - With devfs

Since 2.3.46 the Linux kernel includes a dynamic device filesystem called "devfs" (device file system). With devfs, there is no need to create the device files, because they are dynamically created for you. For USB Scanners, the device is created in /dev/usb/scannerX where X can range from 0 to 15 depending on the number of scanners connected to the system. To see if you have devfs, check if the file .devfsd exists in /dev by issuing the command: 
bash# ls /dev/.devfsd
If .devfsd is listed, then you have devfs, so keep on reading, otherwise jump to "Without devfs". If you would like to maintain the file /dev/usbscanner0 in order to maintain compatibility with applications, then add the following to /etc/devfsd.conf: 
REGISTER ^usb/scanner0$ CFUNCTION GLOBAL symlink usb/scanner0 usbscanner0
UNREGISTER ^usb/scanner0$ CFUNCTION GLOBAL unlink usbscanner0

2.3.2 - Without devfs

If you intend to use more than one scanner at a time (up to 16 are permited), add a device for each USB scanner like this: 
bash# mknod /dev/usbscanner[X] c 180 [Y]
where [X] is a number between 0 and 15, and [Y] = [X] + 48.
So, to add 2 USB scanners, issue the command: 
bash# mknod /dev/usbscanner0 c 180 48
bash# mknod /dev/usbscanner1 c 180 49
If you foresee using only one scanner it is best to: 
bash# mknod /dev/usbscanner0 c 180 48
bash# ln -s /dev/usbscanner0 /dev/usbscanner
Set the appropriate permissions for /dev/usbscanner[0-15] (don't forget about group and world permissions). Both read and write permissions are required for proper operation. For example: 
bash# chmod 666 /dev/usbscanner0

2.4 - Installing libUSB (libusb method)

Although the process of building and installing libUSB is out of the scope of this document, we warn you of the following:

3 - The test tool

Unpack the sources like this: 

bash# cd /usr/src
bash# tar xvzf /path/to/sources/testtool-20020128_2.tar.gz
bash# cd testtool
To build the package with both USB access methods just issue: 
bash# make
to build the package with just the kernel USB access method, issue: 
bash# make USB=kernel
to build the package with just the LibUSB USB access method, issue: 
bash# make USB=libusb
to see the what you can do with the test tool do: 
bash# ./testtool -h

4 - The SANE backend

Unpack SANE backends source code to the desired directory, and use the patch-sane.sh script provided with the package (lets assume that the SANE source directory was unpacked to the parent directory of the test tool): 

bash# ./patch-sane.sh ../sane-backend-x.x.x
If everything went right, then just build SANE backends, otherwise, you might try the official patch that we make available at the project's website (instructions are provided here).

5 - Places to look for more information

6 - Known Bugs (Caveats)

7 - Reporting bugs

To report bugs and make sugestions use the facilities provided in our website. To make things easier, provide us at least the following information:


Last modified: $Date: 2002/04/22 22:48:54 $
Copyright © 2002 Bertrik Sikken, Ricardo Martins