What you need

A scanner with a GT6801 or GT6816 chip

Your scanner must be equipped with a GrandTech GT6801 or GT6816 USB chipset. To find out if your scanner uses such a chipset, run "sane-find-scanner -q" of a current version of sane-backends. The output will look like this:

found USB scanner (vendor=0x055f, product=0x0210 [USB Scanner], chip=GT-6816) at libusb:001:004
    

The output "chip=GT6816" means that the scanner uses a GrandTech GT6816 chip. If you get a question mark after the chispet type ("chip=GT6816?"), please make sure that the kernel scanner module is not loaded (if you run Linux: "rmmod scanner"). Also run the command as root.

If the scanner is not found at all, that's probably trouble swith your operating system or hardware. If it's found but with a different or no chipset type: bad luck, that scanner can't be supported by the gt68xx backend.

You can also open the scanner and check if there is a GrandTech chipset inside. Keep in mind that warranty may be void that way.

The source code of sane-backends

Please get the latest source code of sane-backends (development version) from our CVS server or use our snapshot. Double-check that your scanner is not supported yet. Unpack the source code.

The firmware

You need the firmware of your scanner. See the firmware information on the main page. Install the firmware as mentioned there.

Some basic computer knowledge

You should know how to compile/build software on Unix systems, use an editor and at least in principle, how a programming language like C works. Also you should be able to set permissions on USB device files (see README.linux and man sane-usb).

Some basic knowledge about SANE

If you haven't done so far, read some documentation (man sane, man sane-gt68xx) so you know what sane, a backend and a frontend is. Also read README and README.linux (if you use Linux).

Some knowledge about your scanner

Check the documentation for at least the following data: Maximum physical resolution (X and Y), size (A4, A3, whatever), sensor type. Sensor type is CIS or CCD. Usually CCD sensors use a white neon-like lamp and CIS are only light when actually scanning. With CIS you can sometimes see the red/green/blue light from the LEDs.

Some time

You'll need some time to understand how the cahnges work and some more time for testing. Depending on how different from existing models your scanner is, this can take from 30 minutes to some days.

Warning: possible damage

Before you go ahead, you should know that the gt68xx scanners don't have a "shut-off switch" when the scan head reaches the end of the scan area. So if something is wrong in the backend or you just enter wrong data, the scanhead will bump on the back of the scanner. You'll hear a nois like "taktaktak" or "brrrrrrrrrr". Turn off the scanner by pulling the power plug immediately. For scanners without external power cable, pull the USB plug. While I personally haven't ever destroyed a scanner that way, the motor or gear could be damaged.

Building sane-backends

Unpack the latest sane-backends archive. Run "./configure", "make" and "make install" as explained in README. If you have already installed SANE on your system, you should probably run "make uninstall" before "make install". Otherwise the old configuration files are not overwritten and your scanner won't be detected.

Adding the scanner to gt68xx.conf

First we try to get the scanner working without modifying the source code. Later on, it may be necessary to add the scanner to the code but for testing, it's easier to just modify gt68xx.conf because you don't have to rebuild the backend after every change.

Edit "/usr/local/etc/gt68xx.conf" (or wherever you have installed it). At the beginning of that file, there is a commented out "usb vendor product" line. Remove the comment character and exchange "vendor" and "product" by the vendor and product ids you got from sane-find-scanner. Have a look at the already existing lines for examples.

Trying to find a working model

Run scanimage -L. You should get an "unknown scanner". If not, you have either made a mistake in gt68xx.conf or are not running the latest sane-backends version.

Run scanimage >/dev/null. This should print some warnings and an error because you haven't selected the type of scanner. There is also a list of overrides you can use. Select one that is as similar to your scanner as possible by looking at the scanners list. At least the chipset and type of sensor (CCD/CIS) should be the same. If you find one or more models that use the same firmware name, chnaces are high that this is the right override. Uncomment the override "something" line in gt68xx.conf and exchange something by the override you have just selected. scanimage -L should now print the name of the scanner you selected. Enable the firmware line in gt68xx.conf and insert the path to your firmware. Try scanning (scanimage >image.pnm). If it doesn't work, replug your scanner and try a different override until it works. Enable debugging to watch what happens.

Source code overview

Once the scanner is detected and somehow works you can add it to the source code and do finetuning.

The directory of main interest is "backend/". It contains the code of all backends and the configuration files. The file "backend/gt68xx.c" is the main gt68xx backend file. "backend/gt68xx_devices.c" contains the scanner-specific data and "backend/gt68xx.conf" is the configuration file.

At the end of the "backend/gt68xx_devices.c" file there is a list of all currently supported scanners. The lines contain the vendor and product id and a pointer to the model struct of that scanner. The individual model structs are above the list of scanners. They contain all the data that depends on the scanner including the chipset type used, resolutions and sensor type. At the top of the files there are "command sets". These define the way how the chipsets are accessed. There is one for each chipset and some other ones for Plustek and sheetfed scanners.

Adding the scanner to gt68xx_devices.c

Edit "backend/gt68xx_devices.c" and look at the end of that file. Add a line containing the ids of your scanner and a pointer to a new model (e.g. "mymanufacturer_mymodel_model"). Look at the model structs and select one that is similar to you scanner (probably the one that you chose for the override). Copy the complete struct. Rename it to the name you used in the list (e.g. "mymanufacturer_mymodel_model). Change the settings at the top of the newly created record according to your scanner's data (name, vendor, model, firmware). "Dynamic allocation flag" is always SANE_FALSE.

Comment out the "override" line in /usr/local/etc/sane.de/gt68xx.conf. Rebuild sane as mentioned above. If you get any errors, check that you haven't made a typo while modifying gt68xx_devices.c.

Testing

First let's find out if the scanner is detected: run "scanimage -L" as root. If the scanner is not detected, you either made a mistake in gt68xx.conf or gt68xx_devices.c. Also check that you really use the version of sane-backends you thik "which scanimage", "scanimage --version").

If your scanner is detected by "scanimage -L" as root but not as normal user, something is wrong with permissions. Read "man sane-usb" and README.linux for some hints.

Now try scanning. I recommend to use xsane or another graphical frontend as it's much easier to try out some settings. scanimage also works, however. Try scanning a small area, e.g. 5 x 5 cm in gray mode at e.g. 100 or 150 dpi. Check and write down what happens. If that works, try other modes (color), resolutions and bit depths. Also write down what happens. Increase the size of the scan area. If something does not work, you must change the settings in gt68xx_devices.c as explained below.

For the scanning tests, use a test image. In my experience it's best to use a white piece of paper. Draw some horizontal, vertical and diagonal lines in black, red, blue and green. Also draw a circle.

If the scanner freezes or you get a timeout unplug and replug the scanner before the next test. Otherwise it may be still blocked by the earlier test.

Debugging

If you get errors or the scanner is not detected or you just want to see what happens turn on debugging: "export SANE_DEBUG_GT68XX=255" (for bash). When you run a frontend now, the backend will print quite a lot of debugging information. If you use a lower debug level, you'll get only important messages.

Adjusting the model settings

If something does not work correctly, e.g. colors are wrong or the image is distorted, you must adjust the settings in the model struct in "backend/gt68xx_devices.c". Keep in mind that you must do a "touch backend/gt68xx.c" each time before you build and install SANE again. Here is some explanation what some of the entries in the model struct mean:

static GT68xx_Model mustek_2400ta_model = {
  "mustek-bearpaw-2400-ta",     /* Name */
  "Mustek",                     /* Device vendor string */
  "BearPaw 2400 TA",            /* Device model name */
  "A2fw.usb",                   /* Name of the firmware file */
  SANE_FALSE,                   /* Dynamic allocation flag */
    

That's the easy part. The name should not contain any spaces nor upper case letters. The firmware should be mixed case. "Dynamic allocation flag" is always SANE_FALSE.

  &mustek_gt6816_command_set,   /* Command set used by this scanner */

  1200,                         /* maximum optical sensor resolution */
  2400,                         /* maximum motor resolution */
  1200,                         /* base x-res used to calculate geometry */
  1200,                         /* base y-res used to calculate geometry */
  1200,				/* if ydpi is equal or higher, disable backtracking */
  SANE_FALSE,                   /* Use base_ydpi for all resolutions */
    

The command set is one of the most important settings. Usually the mustek_* command sets are used but some Plustek and compatible scanners need the plustek_* ones. If the backend outputs I/O errors or runs into timeouts, try another command set. The next two values are the maximum physical resolution in X and Y direction. For most scanners the X-resolution is lower or the same as the Y-resolution. "Base x-res to calculate geometry" is the same as the sensor resolution for most scanners. It's only lower if you have a scanner with 6 CCD scan lines (see below). "Base y-res" is usually half of the motor resolution. If your circle is distorted, check if that value is correct. For now, you can ignore the backtracking and "Use base_ydpi for all resolutions" lines.

  {1200, 600, 300, 200, 100, 50, 0},    /* possible x-resolutions */
  {2400, 1200, 600, 300, 200, 100, 50, 0}, /* possible y-resolutions */
  {16, 12, 8, 0},               /* possible depths in gray mode */
  {16, 12, 8, 0},               /* possible depths in color mode */
    

That's a list of resolutions and color depths which is displayed by the frontend. The maximum resolutions should be those of the sensor and motor. The last value is always 0. Try adding some more values like 400, 150 and 75. Delete those which don't work. Concerning the bit depths: GT6816 supports 8, 12 and 16 bits/color the GT6801 only 8 and 12 bits/color. With some scanners some combinations of mode and the bit depth don't work.

  SANE_FIX (3.67),              /* Start of scan area in mm  (x) */
  SANE_FIX (7.4),               /* Start of scan area in mm (y) */
  SANE_FIX (219.0),             /* Size of scan area in mm (x) */
  SANE_FIX (298.0),             /* Size of scan area in mm (y) */
    

These values set the borders of the scan area. Once all the other settings are ok, use a ruler to adjust the values so the complete scan area can be scanned but no parts of the scanner's case are visible in the scanned image.

  SANE_FIX (0.0),               /* Start of white strip in mm (y) */
  SANE_FIX (0.635),             /* Start of black mark in mm (x) */
    

The white strip is the calibration area of the scanner. Every scanner has such a white strip. It's usually located just above the scan area. It's only visible if you open the scanner. The first value defines how many milimeters the scan slider must be moved before it can scan the calibration strip. It usually is in the range of 0 to 12 milimeters. The second value is only needed for CCD scanners. The white calibration strip contains a vertical black strip (thickness about 1-2 mm) on its left border. That black mark is used for the dark calibration of CCD scanners. The value is the horizontal distance from the start of the scan area to the start of the black mark.

If your images have wrong colors, are too dark or too bright or if the calibration before the scan takes ages, changing these values may help. As it's not easy to guess the values without opening the scanner, there is a trick: You can actually scan the white strip! Enable debugging (at least level 1) to be able to set the debugging options. Enable "Full scan", and disable "Coarse calibration" and "Quality calibration". Set the top y value of the scan area to 0 and the height to about 5 cm. The width can be full width. Try a scan but remember to pull the plug if the scan head bumps at the end of the scan area. If everything works well, you'll see the white strip and the black mark (CCD only) now. By comparison with a ruler on the scan area you can estimate the distance of the white strip from the top of the acquired image and the distance of the black mark from the left.

  SANE_FIX (94.0),              /* Start of scan area in TA mode in mm (x) */
  SANE_FIX (107.0),             /* Start of scan area in TA mode in mm (y) */
  SANE_FIX (37.0),              /* Size of scan area in TA mode in mm (x) */
  SANE_FIX (165.0),             /* Size of scan area in TA mode in mm (y) */
  SANE_FIX (95.0),              /* Start of white strip in TA mode in mm (y) */
    

The same settings again but this time for the transoarency adapter. If you don't have such a device just ignore the values. If you have one: There is no white strip in this case but a calibration window near the scan area for the slides.

  0, 24, 48,                    /* RGB CCD Line-distance correction in pixel */
  0,                            /* CCD distcance for CCD with 6 lines) */
    

These values define the distance between the single lines of the CCD sensor. Set them to 0 for CIS scanners. If the colors of the scanned images are not aligned, you must change the first three values. One of them is alway 0, the others are ususally powers of 2. Scan you test image and look at it in a magnified view. Black lines may have bluish/redish lines above/below them. Change the settings until black lines are only black. The last value is for CCD sensor with 6 scan lines. An example is the Mustek BearPaw 2400 TA Plus. For each color there are two slightly offset lines of 600 dpi resulting in 1200 dpi in total. If scans upto 600 dpi look normal but at higher resolutions every second pixels seems to belong to something else, you have such a scanner.

  COLOR_ORDER_RGB,              /* Order of the CCD/CIS colors */
  {0x2a, 0x0c, 0x2e, 0x06, 0x2d, 0x07}, /* Default offset/gain */
  {0x157, 0x157, 0x157},        /* Default exposure parameters */
  SANE_FIX (2.0),               /* Default gamma value */
    

The color order just defines which color comes first when scanning. If you get images which completely wrong colors, try changing this to BGR. The other values can be ignored for now. Offset and exposure can be set to the values the automatic calibration find later so it is faster.

  SANE_FALSE,                   /* Is this a CIS scanner? */
  0                             /* Which flags are needed for this scanner? */
    

The CIS/CCD setting is important. The flags are needed for some scanners. Here is a list:

GT68XX_FLAG_MIRROR_X
The CIS sensor is mounted the other way round. If you images look mirrored and scan area setting is strange, try this flag.
GT68XX_FLAG_MOTOR_HOME
Only needed by the Artec Ultima 2000. If the scanhead doesn't move home after the scan, try this flag.
GT68XX_FLAG_OFFSET_INV
That flag is needed if calibrating offset works the other way round. If your calibration always fails (completely dark or bright images), try this flag.
GT68XX_FLAG_UNTESTED
That just prints a warning message.
GT68XX_FLAG_SE_2400
Needed if the images look like one byte is missing in every line (vertically distorted).
GT68XX_FLAG_NO_STOP
Don't stop the scan before starting. If you can't scan at all, try this flag.
GT68XX_FLAG_CIS_LAMP
Is used for CIS scanners which come with a lamp like the Mustek A3 USB.
GT68XX_FLAG_NO_POWER_STATUS
If you get an error with the command get_power_status in the log file, use this flag.
GT68XX_FLAG_NO_LINEMODE
If color scans don't work,but gray mode does, try this one.
GT68XX_FLAG_SCAN_FROM_HOME
If the scanner's starting position changes with resolution ,try this flag.
GT68XX_FLAG_USE_OPTICAL_X
If the scanner's width is always wrong, try this one.
GT68XX_FLAG_ALWAYS_LINEMODE
If color scans don't work,but gray mode does, try this one.
GT68XX_FLAG_SHEET_FED
Use for sheetfed scanners.

Telling me about the results

Please tell me everything you found out. I need at least an output of "sane-find-scanner -v -v". Even if you haven't changed any code, please send me that output. If you have any questions, contact me. Also, please send me a patch for gt68xx.conf and gt68xx_devices.c or the complete files. Tell me what works and what doesn't work. If you get an error, please send me a logfile (export SANE_DEBUG_GT68XX=255).



Last modified: 2008-03-02 16:24:26 CET by Henning Geinitz.

Back to the general SANE page
To my homepage (in German)
Impressum (in German)