[sane-devel] Third revision of Scanner HOWTO available

[Howard Shane]

Thanks to everyone for all the suggestions. I though I had addressed
most of the concerns up to now, but it looks like there will need to be
one more revision prior to publication. A few of the comments I've
received are contradictory; I'm going out of town for a week and upon
return I'll negotiate/incorporate everyone's ideas and corrections, so
definitely keep the comments coming.

Also, its not nitpicking if it makes the document more accurate and
effective. :^)

Henning Meier-Geinitz wrote:
> 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
> 
> 
> 
> 
> 
>