Scanner Button Daemon (scanbuttond), Version 0.2.3
==================================================


First things first
------------------

This software is in its very early stages of development. Although this daemon
seems to work for most people, there may still be lots of critical bugs.
Be prepared for the worst!


Introduction
------------

Modern scanners usually have several front panel buttons which are intended to
trigger certain actions like copying, faxing or mailing the scanned document.
This daemon monitors the scanner's buttons and runs a shell script whenever one
of these buttons has been pressed. Because it is accessing the scanner directly
via libusb, there should be no conflicts with SANE or other scanner drivers:
scanbuttond simply won't touch the scanner hardware while you are using SANE.


Requirements
------------

 * Scanner: see "supported scanners" below
 * Operating system: Linux (and perhaps other Unix-like systems)
 * Connection: USB (using libusb, the scanner kernel module is currently
   unsupported)


Compilation & Installation
--------------------------

Since version 0.2.3, scanbuttond uses the GNU autotools for compilation &
installation. Please see the file INSTALL for generic instructions on using
them.

If you are using a CVS version instead of a release, you may have to bootstrap
the package. This can be done by running:
"aclocal; autoconf; autoheader; automake -a; libtoolize". 
You should now be able to run ./configure and make.

After you have installed scanbuttond, you should run "ldconfig" to update the
cache of the dynamic linker. If you forget to do that, scanbuttond probably
won't be able to load the backend modules or resolve the dependencies between
them!

Please do not forget to set up your configuration files if you have
installed scanbuttond for the first time. They are usually located in the
directory "/usr/local/etc/scanbuttond". To get started, rename
"buttonpressed.sh.example" to "buttonpressed.sh" and
"initscanner.sh.example" to "initscanner.sh".


Usage
-----

If you just want to try out scanbuttond, type
> scanbuttond

If everyhing works, scanbuttond will fork() to background. To see what
scanbuttond is doing, you can have a look at your system log, for example
/var/log/everything/current (for Gentoo Linux systems running metalog).

To terminate scanbuttond, type
> killall scanbuttond
That should do the job. Scanbuttond installs a signal handler which should
ensure a clean shutdown even when it's killed.

If you intend to use scanbuttond seriously, you would probably want to write a
distribution-specific init-script for starting and stopping the daemon.


Supported scanners
------------------

Supported by the epson backend (via libusb):
* Epson Expression 1600 (expected to work)
* Epson Expression 1680 (expected to work)
* Epson Perfection 610 (expected to work)
* Epson Perfection 636U (expected to work)
* Epson Perfection 640 (expected to work)
* Epson Perfection 1200U (expected to work)
* Epson Perfection 1240 (working, tested)
* Epson Perfection 1640 (expected to work)
* Epson Perfection 1650 (working, tested)
* Epson Perfection 1660 (working, tested)
* Epson Perfection 2400 (working, tested)
* Epson Perfection 2450 (expected to work)
* Epson Perfection 3200 (expected to work)
* Epson CX3200 (working, tested)
* Epson Stylus Scan 2500 (working, tested)

Supported by the hp3500 backend (via libusb):
* HP ScanJet 3500C (expected to work)
* HP ScanJet 3530C (expected to work)
* HP ScanJet 3570C (expected to work)

Supported by the hp3900 backend (via libusb):
* HP ScanJet 3800 (working, tested)
* HP ScanJet 3970 (working, tested)
* HP ScanJet 4070 (working, tested)
* HP ScanJet 4370 (working, tested)
* HP ScanJet G2710 (working, tested)
* HP ScanJet G3010 (working, tested)
* HP ScanJet G3110 (working, tested)
* Umax Astra 4900/4950 (expected to work)

Supported by the hp5590 backend (via libusb):
* HP Scanjet 4570 (expected to work)
* HP Scanjet 5550 (expected to work)
* HP Scanjet 5590 (expected to work)
* HP Scanjet 7650 (expected to work)

Supported by the mustek backend (via libusb):
* Mustek BearPaw 2448TA (experimental)

Supported by the niash backend (via libusb):
* Agfa Snapscan Touch (expected to work)
* HP Scanjet 3300c (expected to work)
* HP Scanjet 3400c (expected to work)
* HP Scanjet 4300c (expected to work)

Supported by the plustek backend (via libusb):
* Canon CanoScan N1220U (expected to work)
* Canon CanoScan D660U (expected to work)
* Canon CanoScan N650U (expected to work)
* Canon CanoScan LiDE 20 (experimental)
* Canon CanoScan LiDE 25 (experimental)
* Canon CanoScan LiDE 30 (experimental)
* Epson Perfection 1260 (working, tested)
* Hewlett-Packard ScanJet 2200c (experimental)
* Genius (KYE) ColorPage-HR6 V2 (experimental)

Supported by the plustek_umax backend (via libusb):
* UMAX Astra 3400/3450 (experimental)

Supported by the snapscan backend (via libusb):
* Epson Perfection 2480 (expected to work)
* Epson Perfection 2580 (expected to work)
* Epson Perfection 1670 (working, tested)
* Epson Perfection 3490 (working, tested)
* Epson Perfection 3590 (working, tested)
* Epson Perfection 1270 (working, tested)

Supported by the gt68xx backend (via libusb):
* Genius Colorpage Vivid4 (working, experimental)

Note: the mustek, niash, plustek, plustek_umax, gt68xx and snapscan backends
were implemented using information gathered by "sniffing" the communication
between the Windows driver and the scanner, because there is no technical
documentation available for these devices! This means that there may be some
weird issues (e.g. button press events reported twice).


How to link actions to buttons
------------------------------

Whenever a scanner button has been pressed, scanbuttond starts a shell script
and passes it the button number and the SANE scanner name as command line
arguments. By default, this shell script is installed as
"/usr/local/etc/scanbuttond/buttonpressed.sh". Please modify it to fit your
purposes.


Scanner initialization
----------------------

Note: this only applies to some scanners supported by the non-epson backends.
All scanners supported by the epson backend do not need special initialization.

Some scanners require a special initialization procedure (firmware uploading,
for example) before they can be used by scanbuttond. Since the scanbuttond
backend modules cannot yet handle such operations, the initialization has to be
performed by external programs, for example by "scanimage" which is part of
SANE. You can customize the initialization procedure by editing the scanner
initialization script, which is by default installed at
"/usr/local/etc/scanbuttond/initscanner.sh". This script will be executed
whenever a new device has to be initialized. In most cases, it should be
sufficient to put something like "scanimage -n" into this script.


How to contribute to this project
---------------------------------

The development of scanbuttond should not be dependent on one single person, 
but a community effort.
You could help by ...

 * adding or enhancing a scanner backend
 * adding or enhancing a connection interface
 * doing some extensive testing
 * sending patches
 * sending bug reports
 * mailing ideas how to enhance scanbuttond
 * ...

If you want to help, please send me an email (see below).


Contact
-------

Any suggestions, criticism, bug reports/fixes, patches, ... are appreciated.
Feel free to contact me via email:

Bernhard Stiftner <[email protected]>