Scanning details and troubleshooting

This file provides more detailed information about setting up scanning with the hpoj software, including possible troubleshooting steps in case something goes wrong.

Additional information may be found in the separate document pertaining to the libsane-hpoj backend.

Also, be sure to consult the connectivity details and troubleshooting document, because some issues here may actually be connectivity-related.

Question: What do the terms "frontend" and "backend" mean?

SANE separates scanning functionality into these two layers:

The frontend application, such as scanimage, xscanimage, or xsane, handles user interaction and saving images to disk, but generally knows nothing about the specific device it's accessing.
The backend driver, such as libsane-hpoj, implements a common API for frontends and performs all device-specific operations, such as reporting known devices and options, starting and stopping scan operations, and converting the received image data into a standardized format.

Question: Does SANE still need to be re-compiled after installing hpoj?

No. If you had previously done this to support an older hpoj version (0.8 or earlier), then you are now free to revert back to the sane-backends version supplied by your distribution if you'd like.

Problem: SANE can't find my scanner or reports an error such as "device busy" when trying to access it.

Make sure you set up and tested basic device connectivity, including running "ptal-init setup".
Don't run "ptal-connect -scan". On some models (that use MLC instead of 1284.4) this could break subsequent attempts to scan with libsane-hpoj.
Don't run sane-find-scanner. It will not properly detect hpoj devices.
Try power-cycling the device. On some models, such as the PSC 2100, 2200, and OfficeJet 6100 series, connecting the device to a Windows system (possibly due to taking advantage of a dual-boot configuration), regardless of whether you actually perform a scan operation on Windows, breaks scanning in Linux until you power-cycle the device.
Edit /etc/sane.d/dll.conf (may be in a different directory such as /usr/local/etc/sane.d in some cases) and make sure the line "hpoj" is present and un-commented. Add or un-comment (remove the leading "#" on) this line if necessary. Also, be careful not to leave any trailing text, such as a comment, on the same line, because this may confuse SANE's configuration-file parser.
cd into the directory where the SANE backend libraries are stored, for example, /usr/lib/sane or /usr/local/lib/sane. Run "ls -l libsane-hpoj.so.1" and/or "ldd libsane-hpoj.so.1". If libsane-hpoj.so.1 is missing or is a dangling symlink, then issue the following command, adjusting as necessary for the actual path where libsane-hpoj.so.1.0 was installed on your system:
```
ln -sf /usr/local/lib/libsane-hpoj.so.1.0 libsane-hpoj.so.1
```
(If you compiled and installed hpoj from the "upstream" source package and the ./configure script detected SANE on your system, then dll.conf and the libsane-hpoj.so.1 symlink above should have been set up properly. However, they probably won't be if you install or upgrade SANE after hpoj. Also, some "downstream" precompiled hpoj packages don't do these properly, which you may want to report as a bug to the "downstream" package maintainer.)
Try specifying the device name on the command line. For example, "scanimage -d hpoj:mlc:usb:OfficeJet_G85 --test". Normally this shouldn't be necessary, as long as dll.conf is set up correctly as described above.
If you have a LaserJet 1220, unplug the device's power cable, open up the side cover, and make sure the cable for the scanner attachment is securely plugged into the main circuit board.
See below for additional troubleshooting suggestions.

Problem: SANE tries to use my device through the `hp` instead of or in addition to the `hpoj` backend.

You probably upgraded from hpoj-0.8 or earlier and had the PTAL device name specified in hp.conf using "option connect-ptal". For best results, the SANE hp backend should no longer be used with hpoj-supported devices. Simply remove all references to PTAL devices in hp.conf, or comment out the "hp" line in dll.conf.

Recent versions of SANE no longer have OfficeJet scanning support enabled in the hp backend.

Problem: I tried editing the `hp.conf` or creating the `hpoj.conf` file, but that didn't help.

hp.conf is for the hp backend, which is for certain single-function ScanJet scanners only and (as described above) is no longer used for scanning on hpoj-managed devices.

There is no corresponding hpoj.conf file. libsane-hpoj automatically uses devices that have been registered with "ptal-init setup".

Problem: I tried to run "`ptal-hp scan`" as I did with hpoj-0.8, but it didn't work.

This functionality was replaced with the SANE-based scanning support for all models using libsane-hpoj.

Problem: When I start SANE, it segfaults, takes a long time, reports lots of syslog messages, or otherwise acts strangely.

Perhaps another SANE backend is causing trouble when probing for (and not finding) its devices. Try editing the dll.conf file and commenting out all backends (putting a "#" character at the beginning of the line) except hpoj, net, and any other backends you know you need.

Problem: SANE terminated abnormally while scanning on the LaserJet 1220/3200/3300 series, and now it can't find or access the scanner.

The scanner lock in the device probably didn't get released. You can manually release it by either power-cycling the device or passing the environment variable "SANE_HPOJ_RESET_SCAN_TOKEN=1" to libsane-hpoj.

Caution: Don't set this environment variable unless absolutely necessary, because the scanner-lock token is the only thing preventing multiple instances of libsane-hpoj from interfering with each other on these models, especially in a networked environment.

Problem: When I scanned a page through the ADF, all I got was a blank (white) image.

Try turning the page over.

Problem: I'm scanning from the glass, and every other time I try to scan I get a "no documents" error.

Turn off the "batch scan" option.

Problem: After scanning multiple pages in the ADF on a flatbed-capable model, the device starts endlessly scanning from the glass.

Turn on the "batch scan" option, which guarantees that a "no documents" condition is returned on the next scan attempt after the last page has been scanned from the ADF. Alternatively, you can set the "ADF mode" option to "ADF", which prevents scanning from the glass altogether.

Problem: I don't see a "batch scan" option.

For some frontends such as xscanimage, there's a menu option which you must select to make "advanced options" such as this one visible.

Also, there is no "batch scan" option for the OfficeJet LX and 300 series. Ignore all references to this option for these models. For ADF-only models in general, multi-page scans correctly stop after the last page, even if the "batch scan" option isn't available or enabled.

Question: Why must I specify both `--batch` and `--batch-scan=yes` on the `scanimage` command line?

--batch tells the scanimage frontend to perform multiple scans until the backend returns a "no documents" condition.

--batch-scan=yes tells the backend to return the necessary "no documents" condition after scanning the last page.

Problem: When scanning multiple pages with the OfficeJet 600 series, there's a long delay before the next page starts getting scanned.

Turning on the "batch scan" option should eliminate this delay.

Problem: When scanning multiple pages, I tried to change scan options (mode, resolution, etc.) between pages, but the settings didn't take effect on the next page.

For some models (OfficeJet 500/600/700/T series, PSC 300 series, and LaserJets), when the "batch scan" option is turned on, the scanner is left in a different state between pages, such that it's ready to start the next page more quickly but unable to accept scan option changes.

If you want to change scan options before the last page in the ADF has been scanned, then turn off the "batch scan" option, which has the side effect of completely resetting the scanner such that it can now accept option changes. You can then turn the "batch scan" option back on if you'd like.

Problem: With the LaserJet 1100A, if I wait too long between scanning each page, I get a "Scanner jammed" error on the next page.

Unfortunately, there seems to be no way around this, regardless of the value of the "batch scan" option. Just make sure you don't delay too long between pages in a multi-page job on this model, or else place only one page in the document feeder at a time.

Problem: With a "batch scan" on the LaserJet 1220/3200/3300 series, immediately after scanning one page it starts scanning the next page, even before I clicked on "Start" again.

This is another quirk of batch scans on these models. Just don't delay too long between pages in a "batch scan" on these models, or the device may discard the buffered image data when it reaches the end of the page if the new scan operation hasn't yet been started from the PC.

Problem: I set the "ADF mode" option to "Auto" on an ADF-only model. If I start a scan with the ADF empty, SANE hangs for a long time before returning an error message.

This is a known bug. Leave the "ADF mode" option set to "ADF" for ADF-only models.

Problem: I scanned a letter-sized page, but the resulting image file was padded to be much longer.

In some cases, especially for scroll-fed scanners, it is impossible to know in advance exactly how long the document will be, and SANE frontends generally don't go back and update the image-length field in the file header after the scan has completed. Therefore, by default libsane-hpoj makes a "best guess" estimate of the maximum image size, and pads it with white data or truncates it as needed.

If desired, you may use the "geometry" options to select a smaller scan area.

Alternatively, if you really want to scan the entire page but avoid the default padding, you can change the "length measurement" option from Padded to either Unknown, Unlimited, or Approximate. Save the resulting image to a PNM file, such as out.pnm. Then run something like the following command, which reads the image from out.pnm and writes it back out with the correct length field to out-fixed.pnm:

	hpojip-test out.pnm out-fixed.pnm -decpnm -encpnm

Problem: The right and/or bottom margins are cut off.

This has been fixed as much as possible in libsane-hpoj. Any remaining margin-cutoff issues may be the fault of the device and/or the SANE frontend (such as xsane). Try using a different frontend application, such as xscanimage or scanimage.

Problem: The device sometimes locks up in the middle of scanning a page, possibly with a "`SYSTEM ERROR`" message on the front panel.

This is a known issue on certain models (OfficeJet 500/600/700 and PSC 300 series). The workaround seems to be to increase the value of the "JPEG compression factor" option. The default value for this option is 10 on these models (0 otherwise), but try increasing it some more if you still experience this problem.

A list of "system error" codes on these models and possible fixes may be found here.

Problem: Scans on my parallel-connected model are very slow.

The following suggestions may help, depending on your system, device, budget, and image-quality needs:

Set your parallel port to ECP in your BIOS setup or on-board jumpers, as appropriate.
Connect via USB or JetDirect instead of parallel if possible.
Try turning on scanner compression if your model supports it: JPEG for color and grayscale; MH, MR, or MMR for lineart.
Use the lowest acceptable resolution possible, which normally happens automatically when performing a "preview" scan.
Use a lower scan mode for preview scans: grayscale for images, lineart for text. Then go back to the desired scan mode for non-preview scans.

Question: What is the difference between the two JPEG compression and quality options in `xsane`?

Some scanner models return JPEG-compressed image data, and the backend transparently decompresses it before delivering it to the frontend application. The backend "JPEG compression factor" option tells the scanner to what extent to compress the data (larger numbers mean more compression and faster scans but lower quality). On the other hand, xsane is able to save scanned data as JPEG files, but it must re-compress the data given a separate "JPEG quality factor" setting. Note that since JPEG is a "lossy" compression standard, for best final image quality you should use as little compression as possible, especially in the intermediate device-to-backend compression step. It is not currently possible to save the device-compressed image data directly to a JPEG file and avoid the redundant re-compression and associated quality loss, because the SANE API standard requires backends to deliver image data in an uncompressed format.

Problem: In the middle of a scan I pressed the "Cancel" button on the device's front panel, and SANE locked up.

This is a problem on certain models. Usually the application will un-freeze after a timeout period, which could be a minute or more depending on what state the scan operation was in at the time the Cancel button was pressed.

Problem: I pressed one of the "Scan" buttons on the device's front panel, but nothing happened.

The "Scan", "Scan To", and "Start Scan" buttons on the front panel are not currently supported by the hpoj software. Always use the SANE frontend application to initiate scans.

Question: How do I set up `xscanimage` or `xsane` to run as a GIMP plugin?

Invoke something like one of the following commands, adjusting the paths as necessary for the directory in which the application is installed and the version of GIMP you're using:

	ln -s /usr/local/bin/xscanimage ~/.gimp/plug-ins
	ln -s /usr/local/bin/xsane ~/.gimp-1.2/plug-ins

See http://www.xsane.org/doc/sane-xsane-gimp-doc.html for more information. This may not be necessary if you are using SANE and GIMP packages provided by your distribution which automatically set up the appropriate links.

Question: How can I share my scanner with other network clients?

Using saned, you can share the device's scanning function with other network clients that are also running SANE.

You may be able to connect the device directly to the network with a JetDirect print server. However, not all products' Windows drivers support this configuration.

Question: How do I debug scanning problems?

If you have problems, in some cases it may be helpful to enable debug output, which is fully enabled with the following command before running the application:

	export SANE_DEBUG_DLL=128
	export PTAL_DEBUG=2

The debug output is sent to standard error. To capture this to a file named log.txt, add 2>log.txt to the command line. Put it before the ampersand if running xscanimage or xsane in the background.

Next steps

Use the Back button on your browser to return to the previous document, or click here to return to the index.