
Welcome to MUSCAN


WHAT'S IT ALL ABOUT:
muscan is a package containing a scanner driver for the
Mustek Paragon scanner series (see below).
There also is a X-based frontend.

These are the scanner models supported so far:
  - 6000CX (the one I own and the only one I tested)
  - 6000CZ (should work fine)
  - 8000CZ (should work fine)
  - 12000CZ (should work fine)
  - 6000SP (let me know if this one works)
  - 8000SP (let me know if this one works)
  - 12000SP (let me know if this one works)

There is also FreeBSD 2.1 support.

Now color, greyscale, halftone and lineart are supported.

There is a new frontend (tkmuscan) written by Chel van Gennip,
which can be used instead of xmuscan (I haven't tested this, but it
should work fine).


INSTALLATION (COMMON):
Look at the Makefile and modify the values, if neccessary.
DEVICE is the name of the scanner device (usually /dev/scanner).
Look at the OS-specific lines below.

If you want to use the X11 frontend with 3D buttons and you have the 3D-Athena
widgets installed, you might want to use libXaw3d (change XAWLIB to Xaw3d)

Do -as root- a: make install.

That's it. Try to scan one image by simply typing "muscan -f test.file"
You now can watch your scanned image using (i.e.) xv. The file is written
in PBM-raw.
(and you should of course read the manpage!)

There is a front-end called xmuscan. You can use this as well. xv is required to
display scanned images, but you can change this with the -p option.


INSTALLATION (LINUX):
Use the machine type LINUX.
You have to enable the GENERIC SCSI in your kernel and to create a
device /dev/scanner. 

Example: If you have one SCSI disk at ID 0 and one tape at ID 2, the scanner
at ID 3 and a CDROM at ID 6, you will issue the following command:

mknod /dev/scanner c 21 2; chmod 666 /dev/scanner 

(or, if you are paranoid about your system's security, 
chmod 660 /dev/scanner; chgrp <scannergroup> /dev/scanner 
and add users who are allowed to use it to this group)

This means, the scanner is the 3rd device at the SCSI bus. But take care if you
remove (in this example) the tape, for the scanner will then be the 2nd device!
(mknod ... 21 1!!!)

You have to use a supported SCSI adapter, for this is no device driver
which implements the use of the adapter shipped with the scanner but an user
level driver. Maybe (if you use newer kernels) the card will be supported,
see below.

I am using a kernel v1.2.13; this works fine. If you are using older kernels,
you probably might encounter problems with the generic SCSI driver. So you might
want to update... (at least I know of one 1.1.x kernel, which has not the sg_header
struct as my program needs it)

If your Linux source is not in /usr/src/linux, you have to change the
#include </usr/src/linux/drivers/scsi/sg.h> in muscan.c to an appropriate
value.


INSTALLATION (FREEBSD):
Use the machine type FREEBSD.
Adjust the configurable pathnames in the Makefile (esp. INSTAPPDIR and
INSTXBINDIR). You have to use GNU make instead of the generic make.
Do NOT enable SG_BIG_BUFF though, this is for Linux only. After you have
done this, do a "gmake install" as root.

You then have to symlink the "unknown" device /dev/uk? associated with
your scanner to /dev/scanner. To do this, first find out which SCSI ID
it is assigned to and then have a look at the device probing
messages at bootup. For example, my scanner is on SCSI ID 2 on my
first SCSI host adapter. In the startup messages I find a line saying:

Apr 22 18:40:34 malibu /kernel: (aha0:2:0): "unknown unknown ????" type 6 fixed
SCSI 0
Apr 22 18:40:34 malibu /kernel: uk0 (aha0:2:0): Unknown

The terms in the braces tell me that the device is the Adaptec 1542
SCSI host adapter 0, SCSI-ID 2, LUN 0 (i.e. my scanner) has been
assigned to the "unknown" device /dev/uk0. Thus I do a

ln -s /dev/uk0 /dev/scanner

and that's all.

The Mustek scanner is recognized with _all_ the possible LUN's, i.e.
(aha0:2:0) ... (aha0:2:7) in my case. This is nothing to worry about,
just use the one with LUN 0 and you should be set.

You could also "hardwire" uk devices to specific adapter/ID/LUN
combinations in the kernel. See uk(4) for details.

This port has been tested on FreeBSD 2.1-stable with a Mustek
MFS-6000CX flatbed scanner, an 1542B Adaptec SCSI host adapter and
two harddisks on the same host adapter. No panics and no SCSI lockups
yet. BUT be aware that muscan COULD panic your system (it did several
times when I did the port). So be sensible and back up all your
relevant data. It should work with 2.1.0-RELEASE, too.

Known problems:

- Messages like this during scanning:

  Apr 27 13:45:06 malibu /kernel: uk0(aha0:2:0): unknown error category from host adapter code

  Ignore them (or if you know what causes them, tell me :). They don't seem
  to do any harm.

- The Mustek scanner does not do disconnect/reconnect, so timeouts
  are likely to occur when a _single_ SCSI command takes too long.
  This only happens to me when (in xmuscan) I select a scanning
  region which is entirely in the bottom half of the page. No panics
  have been caused by these timeouts, but they're potentially
  dangerous. If you're concerned about this, use the scanner on a
  seperate host adapter.

- I use libscsi(3) for building and submitting SCSI commands, so any bugs in
  this library also affects muscan.

- If muscan dumps core or otherwise dies abnormally, be sure to power-cycle
  the scanner.

- There's no support for the SCSI controller card shipped with the scanner.


ATTENTION:
Sometimes the scanner seems to lock the SCSI bus. So you eventually have
to hard-reset your computer, which isn't too good for your filesystem.
Especially if you are using xmuscan with some windows in the middle half
of the whole image, this might happen.
One way to avoid this is to install a secondary SCSI-controller for the scanner,
like one cheap AHA1542B (at least I do this; I've got some trouble to run
the scanner as the only device at the adapter, finally I had to use at least
one device with a lower SCSI ID at the same adapter. This seems to be gone
with a new firmware, but I have version 1.81; the new scanners have a model
number unequal to MU... [I guess it was BI...]; the problem should be fixed)
Because this works fine for me, I do not to intend to support the shipped
card (NCR 53C400) and leave this to whoever is interested in doing so...
(the kernel does support some 53Cxxx cards, but 53C400 support woes)


TIPS (LINUX):
To get quick scan results, you should have SG_BIG_BUFF enabled (this enlargens
the SCSI buffer from 4096 bytes to the value in this constant). This is the
default behaviour in Linux 1.2.10 (and maybe other version, too). I guess it is
possible to set a higher value here. Maybe 64k or more... You have to recompile the
kernel and muscan to get a higher value working (if you set the value to a lower one,
muscan detects it by itself)

The shipped Trantor SCSI card (the one that comes with the scanner)
should work fine if you enable NCR5380 support and type 
"ncr5380=0x280,254" at the boot prompt (or add this to your lilo
configuration)


NOTES:
Read the LICENSE and COPYRIGHT, if you are interested in this stuff.

Please report any bugs (and if you like the program, this too ;-) to:
eichner@rhrk.uni-kl.de


THANKS:
Thanks to Gunther Mayer (gmayer@physik.uni-kl.de) for valuable tips about
backtracking and SG_BIG_BUFF support and the 6000CZ-part.

Thanks to Martin Butkus (M.Butkus@tu-bs.de) for the FreeBSD port.

Thanks to Roy Murphy (murphy@panix.com) for the note about how to
use the SCSI card that comes with the scanner.

Thanks to Chel van Gennip (chel@vangennip.nl) for deskjet support and tkmuscan.

Thanks to Peter Lienig (Peter_Lienig@t-online.de), Andreas Seltmann (seltmann@student.uni-kl.de)
and Thomas Schoebel (Schoebel@informatik.uni-stuttgart.de) for the SP support.


AUTHOR:
Torsten Eichner, eichner@rhrk.uni-kl.de
