[sane-devel] Third revision of Scanner HOWTO available

[Henning Meier-Geinitz]

Hi,

On Sat, Jul 19, 2003 at 04:45:12PM -0500, Howard Shane wrote:
> ...at http://66.25.191.66/docs/HOWTOS/Scanner/index.html
> 
> This is your last chance to point out any remaining technical errata
> prior to grammatical review and (hopefully) publication by TLDP.

Ok, lets see if I can nitpick a bit :-) I'm not a native english
speaker, so grammar/spelling corrections may be wrong.

| 1. Introduction
| 
| within X-windows

->"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" (from man X)

| It does not address how use the available software 

--> how to use (?)

| 2.1. SCSI Devices
| While most SCSI-cards that linux supports allow scanning, you should
| be aware that if your SCSI card came come bundled with your scanner
| you may run into problems, as these may not be complete SCSI cards
| (much like a winmodem). 

I don't think that's a very good comparison. While a winmodem is not a
modem at all (it's more a sound chip), the bundled SCSI adapter are
real SCSI cards. They may not be of good qquality, i.e. don't have
IRQ/DMA support. But at least the ones I know of can be used for e.g.
CDROMS, too. Well, I wouldn't do that but anyway.

| 3.1. USB Scanners and Libusb

| $ grep -e USB_DEVICEFS /boot/config-X.XX

--> I think it's easier to do
grep "\(usbfs\)\|\(usbdevfs\)" /proc/filesystems

This way you are checking the currently running kernel.

| If you have USB device filesystem running, and you have usb devices
| loaded already you can confirm this with cat /proc/bus/usb, which
| should give you a list of active devices the kernel is aware of.

--> It's "cat /proc/bus/usb/devices".

| IMPORTANT: You cannot have both kernel scanner support enabled (i.e.,
| compiled in statically or the module loaded if a module) and libusb
| installed and access the hardware at the same time, or nothing will
| work.

Well, I know what you mean but it's not completely true the way you
have written it.

If the scanner driver is loaded and has detected the scanner it will
"lock" it. So libusb can't use it. But the scanner driver can still
use it. After unloading the scanner driver, libusb can use it again.

So there is no real conflict. The scanner driver just has the higher
priority.

| (A hint for newbies: [...]
| where 'file.txt' will contain the info that can then be accessed with
| cat.)

--> with "less", otherwse it will scroll again too fast.

| 3.2.2. Kernel USB Support

| USB-ohci, USB-ehci,

--> lower case (usb-ohci)

| 3.3.2. Directio
| 
| Some parallel port scanners can be accessed with directio (a.k.a.
| direct_IO) instead; you will likely need to compile your own SANE
| binaries and have libieee1484 installed. You will need generic scsi
| device support in your kernel. At compile time use the
| --enable-parport-directio --enable-scsi-directio with the ./configure
| script.

I'm not an expert in these things but I think you are mixing different
topics here.

--enable-parport-directio means, that direct hardware access to the
ports (inb/outb assembler commands) is used. So you don't need
libieee1284 (not 1448) here. This is only used in the mustek_pp and
umax_pp backends.

--enable-scsi-directio 

From README.linux:

  SCSI Direct IO: Recent versions of the Linux SG driver for the 2.4
  kernels support direct IO, i.e., the SCSI adapter's DMA chip copies
  data directly to/from user memory. Direct IO reduces memory usage,
  but it can lead to access conflicts, if a backend uses shared
  memory. SANE does not use direct IO by default. If you want to use
  it, run

        configure --enable-scsi-directio=yes

	
I don't think you should mention --enable-scsi-directio in a HOWTO
document. it's seldomly (if at all?) used.
						      
| 5.1. Getting SANE

| that of the Software Building HOWTO. 

--> the link to the HOWTO seems to be wrong.

| For Debian users there is a sane package in stable (Woody), testing
| (Sarge) and unstable (Sid) package repositories, so a simple apt-get
| install sane is all that is required whatever version you are using.

The package in Woody is quite old but there are backports from 
Aurelien Jarno: http://people.debian.org/~aurel32/sane.html

| There is an excellent write-up of how to compile SANE from source and
| get an SCSI scanner working at Laurent-jan's HOWTO page originally
| written by Steve Sheriff (the graphics are interesting, too).

While his HOWTO is written very detailed, with fairly current
distributions it's not necessary to compile all the graphic libraries
yourself. You'll find some discussions about this howto on the
sane-devel list if I remeber correctly. I'd mention the fact that
compiling the glib/gtk/gimp stuff is not necessary otherwise it's
quite misleading for newbies.Even the newest versions of xsane and
xscanimage can be compiled with old gtk and gimp libraries.

| 5.2. Configuring SANE
| 5.2.1. Selecting the SANE Backend

--> Before doing anything else, I'd run "scanimage -L". Most scanners
will just run out-of-the-box so it's not necessary to go through all
your trouble-shooting steps. If it's not found, the user can still
check the files you mention.

| There are two important entries in the file named after the backend
| your scanner will use:

--> give an example (e.g. "epson.conf")

| 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,

Usually that's not needed. If there is no scsi device, it just won't
be detected. 

| and uncomment the line containing 'usb.'

If it's commented. Is there any backend but "epson", where this is the
case? Maybe it'd be possible to do automatic detection in the epson
backend, too? (without manipulating the config file). Well, I'll ask
the epson maintainer.

| In addition the device name may need to be changed, depending on your
| distribution (e.g., /dev/scanner0 may become /dev/usb/scanner0)

That's unlikely. Maybe you mean /dev/usbscanner0 --> /dev/usb/scanner0?

| though if you made the symlink I suggested in the section on making
| devices this probably isn't necessary.

You mean the /dev/scanner symlink? This is ONLY used for SCSI devices.
Don't use it for USB scanners. And even for SCSI, it's not necessary
for most backends on Linux and FreeBSD.

| For a full list try apropos sane. The exact protocols and
| manufacturers available may depend on your version of SANE.

A pointer to "man sane" may be useful, too, as it lists all the
backends and gives some hints which one may be the right one.

| 5.2.2. Across a Network

I still think you should make more clear that the saned server runs on
the machine that has the scanner and the frontend/net backend runs on
the client that want access to the server with the scanner. At least I
wouldn't have understaood that you mean the client when you talk about
the "target".

| In addition port 6566 will need to be open, accomplished by adding the
| following line to /etc/services:
| 
| sane 6566/tcp # SANE network scanner daemon

I think I already mentioned that he last time you asked for
corrections (?): /etc/services is just a list of name/number
combinations. It's not responsible for "opening the port". That#s done
by inetd/xinetd.

| Finally, be sure that the word "net" isn't commented out in the
| dll.conf file referenced in the previous section.

On the client machine. And you need to edit net.conf on the client to
add the hostname of the server.

| 6. Testing Your Scanner

| sane-find-scanner -v

First I would do it without the "-v" as you may miss the important
information. If the scanner is not found, "sane-find-scanner -v -v"
may be useful.

| If your scanner is a type not looked for by sane-find-scanner, you can
| try scanimage --test -v which may yield more information about
| attached devices (you may need to do this twice).

Well, "scanimage --test -v" jsut starts a test scan. It won't give you
any information. Try "scanimage -L" instead.

| 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.

It's highly unlikely that the scanner is dnot detected but scanning
works. That only happens when the backend is commented out in dll.conf
but the user selects the backend explicitely (with -d).

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

If the user did everything right until now, the following should just
work:

scanimage >image.pnm

| 7. Sane Frontends
| X-windows

see above

| A more spartan solution (though technically a meta-backend) is
| xscanimage, which is bundled with SANE and can be evoked from within
| an xterm. See man xscanimage for more info.

xscanimage is not a meta backend, it's just a normal frontend. Meta
backends are backends that call other backends (e.g. dll, net).

xscanimage is in the sane-frontends package so calling it "bundled
with SANE" may be a bit confusing.

xscanimage can not only be invoked "from an xterm" but can be started
like any other software from an icon or menu. It just depens on the
window manage you are using.

I'd add a link to the SANE frontends page so the user can have a look
at all the other frontends:
http://www.mostang.com/sane/sane-frontends.html

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

| If this isn't the problem, go to /etc/sane.d/ (or
| /usr/local/etc/sane.d) and edit the file sane.dll, commenting out any
| backend or other (e.g. v4l) protocol that you don't need. 

It's "dll.conf", not "sane.dll".

| If you have a usb scanner, you will usually need to comment out (make
| a # mark in front of) the 'scsi' line,

As I said, I don't remeber a case where that would be necessary.

The same comments as above apply.

| 8.2. What if SANE can't identify (or correctly identify) my USB scanner?
|
| Often when you first set up your scanner equipment it becomes
| necessary to help the kernel along in identifying the device you wish
| to access. If you've done everything by the book and it still doesn't
| work, and you don't see any obvious error messages in the steps
| leading up to this point, it may be necessary to give the kernel more
| parameters when loading modules, particularly if you have a USB device.

That's true. But you should mention that in this case the scanner is
not even detected by sane-find-scanner. If it's found by
sane-find-scanner that usually means that the kernel has detected the
scanner correctly.

| Within the kernel source is the cryptic data required. If you don't
| have the source code for your kernel installed you can obtain it from
| your linux distribution vendor. For a USB device, go to
| /usr/src/linux/drivers/usb and find the file scanner.h. then use grep
| for your particular model, in this example Epson:

I don't think that looking at the kernel source code helps in this
case. If the scanner is not detected by the kernel, it is not listed
in scanner.h. So looking at scanner.h for the ids does not help. 

Better check /proc/bus/usb/devices or /var/log/messages for the vendor
and product ids of the scanner.

An if you have libusb, you don't need to do anything like this.

Mabye I have missed it, but you should also point out that having more
than one version of SANE installed at the same time calls for trouble.

Thanks for your work!

Bye,
  Henning