[sane-devel] Announcing Scanner-HOWTO at tldp.org

[Henning Meier-Geinitz]

Hi,

On Mon, Jun 02, 2003 at 10:18:39AM -0500, Howard Shane wrote:
> I would like to announce the completion of the initial draft of the 
> Scanner-HOWTO for the linux documentation project, and invite 
> participants on the SANE-devel mailing list to comment on it.

Cool! Nice work.

> Any help you can suggest to clarify or otherwise improve the draft will 
> be greatly appreciated and may even result in you being mentioned in the 
> credits if you so desire.

Ok, if you want corrections/comments you'll get them :-). I'm not a
native English speaker, so I have misunderstood some of the
documentation.

| 2.1. SCSI Devices
|  In general if you have one of the following SCSI adapters, your
|  scanner should work without difficulty:

Pretty much any SCSI adapter should work. Some may need some tweaking.
I'm not sure if it helps to select just a few ones.

|  Acard/Advance

At least with older kernels, there was a lot of trouble with those. 

|  Adaptec AHA-1505/AHA-1542/AHA-2940
|  ASUS SC200
|  BusLogic BT958
|  NCR/Symbios 53c400/53c400 ISA card
|  Domex DTC3181E/L/LE (DTCT436/436P) ISA card

The last two are very low level cards that come with SCSI scanners
(e.g. Mustek ones). I wouldn't call them "work without difficulty".
While they can be made to work, they are slow and the driver tends to
crash quite often.

| Again, consult the above referenced link if you are unsure.

That's the SANE backend list link? Maybe linking to the sane-scsi
manpage makes sense here. The manpages are online on mostang.com in
html format.

| 2.3. Parallel Port Devices
| If your scanner is really old and has a 25-pin connector it is
| probably of this type. 

SOme SCSI scanners have the same db25 connector and the same cable. So
be careful...

| I recommend checking out the page on the subject by Jonathan Buzzard
| for the working list, though as of this writing the page had not been
| updated in some time so there may be hope if yours isn't listed.

The scanner search engine can also print a list of all supported
parport devices if you just select "parport" and don't enter any
keywords.

| 3. Kernel Support of your Scanner Device
| $  ls -R /lib/modules/X.XX/drivers 

LC_ALL=C ls -R /lib/modules/2.4.21-rc6/drivers
ls: /lib/modules/2.4.21-rc6/drivers: No such file or directory

The directory structure changed in recent kernels. It's now 
/lib/modules/X.XX/kernel/drivers 

| (A hint for newbies: if the info in dmesg or the above module list
| scrolls by too fast, you can catch the info in a file like so: dmesg >
| file.txt, where 'file.txt' will contain the needed info.)

If a newbie doesn't know how to deal with that kind of problem, he may
not know ho to view the file. What about "dmesg|less"?

| 3.1. SCSI Support
|
| If you have an SCSI card in your computer, there is no kernel option
| for SCSI support other than that for your card plus generic SCSI
| device support (usually named /dev/sg0, /dev/sg1 etc.).

I don't really understand that part. "You only need to enable the two
SCSI options ... in the kernel..."?

| Since you
| probably already know if your card is supported from the next page,
| all that is necessary is to load the module like so:

Which next page?

| 3.2. USB Support

Instead of the kernel scanner module, using libusb is also possible.
In fact, it may be the only way in Linux 2.6. If you don't use libusb,
you may need a really recent kernel (2.4.21-pre) to get some scanners
working. 

| 3.3. Parallel Port Scanners

Maybe the maintainers of the parport backends can give some more
comments here. Some backends access the parport directly with inb/outb
commands or via /dev/port. Loading the "parport" module may interfere
with that (?).

| Your parallel port should be set to preferably "ECP" mode, or
| "bidirectional" (also known as "BPP" or "PS/2") at a minimum.
| "Unidirectional" (also known as "SPP") and "EPP" may work, although
| more slowly. There is usually a BIOS setting for this.

At least the umax_pp backend manpage says "EPP only".

| Depending on whether your parallel port scanner requires SCSI support,
| you may need to patch your kernel for paraport-SCSI support. 

Typo: parport.

| 4.2. Creating Devices Manually

Nice, but are there really any distributions that don't have
/dev/MAKEDEV or a similar script that takes care of these details if
the devices haven't been created when installing Linux?

| 4.2.3. Manually creating Parallel Port Devices

Depending on the backend you may need /dev/port, /dev/parport or none
of those.

| 4.3. Groups and Permissions

| # chmod u+rw /dev/usb/scanner0
| ...where u+rw means add read and write access for user. See the
| documentation for chmod (man chmod or info chmod) for further info.

Didn't you want to give the permission to the group, not the user?

| 5. SANE
| The final prerequisite for scanner access is the SANE tools and a
| suitable SANE-frontend. The former are the drivers and low-level
| access tools that interface with your scanner, and the latter are
| graphical tools for complex functions used within the X-windows
| system. Only the former are required for scanner access, though a
| frontend is highly recommended in order to manipulate images and to
| actually be able to see your images in a windowed environment without
| having to print them.

That's a bit confusing IMHO. What do you mean by "SANE tools"? Better
use the package name "sane-backends" or the terms "backends" and
"frontends".

| 5.2. Configuring SANE
| 5.2.1. By Scanner Manufacturer

| find / -name saned.conf 

Better don't mention that, because people may start to edit
saned.conf... Further more, it may take ages, "locate" is faster.
But the rule of thumb is pretty much accurate: "If you compiled the
source from mostang.com yourself, it's in /usr/local/etc, otherwise in
/etc."

| Change to the indicated directory and look for the name of your
| manufacturer. For example, if you have an HP scanner, hp.conf or an
| Epson scanner epson.conf and so on. 

That doesn't work for many scanners. E.g. Epson scanners may also be
supported by the plustek backend. Mustek scanners may be supported by
mustek, mustek_usb, mustek_pp, gt68xx, plustek or ma1509 backends.
Better point the user to the devicel ists, they contain the name of
the backend.

| You should see two items in the file: interface type (scsi vs. usb),
| and the device name. If you have a usb scanner, you will usually need
| to comment out (make a # mark in front of) the 'scsi' line, and
| uncomment the line containing 'usb.'

While this may work with most backends, it's not a general rule. E.g.
the plustek backend uses "device /dev/something". I wouldn't comment
on these details without listing (and testing) every single backend
that works this way.

Most USB and SCSI scanners should work out-of-the-box. So better tell
the user to first try "scanimage -L" and only if that doesn't show the
scanner give some trouble-shooting tips.

| (including sane-plustek, sane-qcam, sane-ricoh
|  sane-sharpsane-snapscansane-umax and so on.

Typos: Missing space and closing parenthesis.

| For a full list try apropos sane.

Mentioning "man sane" may also make sense here.

Don't forget to point to dll.conf. Some distributions tend to modify
this file and some backends are commented out by default.

| 5.2.2. Across a Network
| 
| If you are interested in making scanner services available across a
| network from or to a remote machine, you will need to edit the
| saned.conf file 

...the saned.conf file on the server (where the scanner is)...

| in the same directory as outlined in the previous
| section. It usually consists of an entry 'scan-client.somedomain.firm'
| that will need to be replaced with the hostname of the target machine. 

...the hostname of the client (without the scanner)...

net.conf of the client should contain the host name of the server.

| The saned daemon will need to be run as well as inetd or xined.

The saned is run through inetd or xinetd. Typo: xinetd.

| In addition port 6566 will need to be open, accomplished by adding the
| following line to /etc/services:

/etc/services is just a list of aliases, so you can use "sane" instead
of "6566". It doesn't open the port itsself, that's done by (x)inetd.

| WARNING: If you plan on running saned across a network it would be
| wise to use a separate 'saned' group for those with scanner
| privileges, as allowing suid root processed in a network setting is
| highly discouraged for security reasons.

The saned user/group should be used in (x)inetd.conf. It shouldn't be
used by the users themselves. The idea is to give saned as little
permissions as possible.

| 5.2.3. Using SANE with a Video4linux Device
|
| Check the configuration directory where you found sane.conf.

saned.conf.

| There should be a file named 'v4l' 

v4l.conf.

| Opening this file yields the following content (at least on my system):
| #/dev/bttv0
| #/dev/video0
[...]

The device files are not commented out in original sane-backends
source code. Probably this was your distributor.

| 6. Testing Your Scanner
| sane-find-scanner -v

Start with the easy stuff. Nobody likes to scroll through all these
details. If "sane-find-scanner" doesn't print anything, "-v" or even
"-v -v" can be added later.

| If your scanner isn't identified by any of the above, but you're
| pretty sure you've done everything right up to now, you can try
| scanning as outlined in the next paragraph.

If the scanner is not listed with -L, but scanning works with
-d backend:/device, the reason is that the backend is commented out in
dll.conf.

| scanimage -d /dev/scanner0 --format pnm > outfile.pnm

The format of -d is "backend:/device_name". The device_name is
backend-specific.

| 7. Sane Frontends

scanimage is also a SANE frontend.

| Now that you've got the hardware working, you should probably acquire
| a suitable frontend if you plan on using your scanner device in
| X-windows (which unless you have SVGAlib installed is probably a good
| idea so you can see what you've scanned).

Just nitpicking :-):

|       The  X Consortium requests that the following names be used
|       when referring to this software:
|
|                                          X
|                                   X Window System
|                                    X Version 11
|                             X Window System, Version 11
|                                         X11


There are more frontends than just xsane and xscanimage. You can add a
link to the SANE frontends web page, which provides a list of them.

| 8.1. If your device cannot be found...

It's relatively easy to check if it's a permission problem: Try as
root. If it works now, it's most probably casued by permissions.

| 8.2. What if SANE can't identify (or correctly identify) my USB scanner?

I wouldn't mention the Linux source code at all. There is no need to
download or install it. If the device is listed there, it will be
detected by the scanner driver. If not, it won't help at all. Better
point to the list of USHB devices on linux-usb.org or explain how to
read /proc/bus/usb/devices or syslog to get the numbers.

Bye,
  Henning