digitizer set up

Bill Brown brown at zorro.cecer.army.mil
Tue Aug 10 13:47:24 EDT 1993

Here's some info on setting up digitizers for use in GRASS 4.1:
(I don't use digitizers & know nothing about this stuff, just passing
along the info for Terry Baker, who put together this documentation.)

Setting up a digitizer for use with v.digit & xdigit

There are two necessary parts to setting up a digitizer for the grass4.1
digitizing programs: the digcap file and the digitizer description file.
The description file lives in $GISBASE/etc/digitizers. It describes the 
digitizer to the program so the program will know how to handle the 
digitizer input. The description file replaces the digitizer drivers necessary
with previous versions of grass and is (presumably) easier to write.
The digcap file replaces the digitcap file in earlier versions and lives
in $GISBASE/etc. Its only purpose is to list the digitizers available.

There are sample digcap and description files shown below. Sample files are
also distributed with the grass source code and copied to the correct 
directories when v.digit is compiled. If you have one of the digitizers for
which a sample file is included you should be able to use them directly.
You will want to delete from the digcap file the lines for the digitizers
you do not have, so that users don't choose them inadvertently. Some 
editing of the description file may be necessary if there is not
one that matches your format of choice. If you do not have one of the 
digitizers included in the sample files you will have to write your own.

Writing a Digcap File

A digcap file is simply a list of the available digitizers. Lines beginning 
with a pound sign are treated as comments and must come before the list of 
digitizers (that is, the digitizer list must come last). No blank lines are 
allowed. There should be one digitizer entry per line and each line should
have the format:

    name:tty:digitizer filename:description of digitizer

    name = the name that appears in the digitizer menu in the program.
	    (Name should be less than 20 characters.)

    tty = tty to which device is connected

    digitizer filename = name of the description file for this digitizer
    description of digitizer = a short description of the digitizer and format.
	 (this information is optional, but the colon preceding it is not)

Every digcap file should contain the line:


so that the user will have the option of running the program without a
digitizer. A sample digcap file is included below.

Writing a Digitizer Description File

The digitizer description file provides information to the program on how 
input from the digitizer should be interpreted. It allows the programs to work
with any digitizer without writing a new driver for each one. All the 
information in the description file should be available in the digitizer's 
operating manual. Probably the easiest way to write a description file is to
start with an existing file and modify it with the commands and parameters
specific to your digitizer.

Digitizer file names

The digitizer files included with v.digit follow a naming convention that,
while optional, is helpful in choosing from a list of files.
The first two characters of the name indicate the type of digitizer and the 
third and fourth characters (digits) are the model number. This is
followed by an 'f' and a number indicating the number of the input 
format this file supports. Next is an underscore ('_') followed by a number
which represents the number of buttons on the cursor of this particular

    cc95f23_16 -- Calcomp, model 9500, format 23, 16 button cursor.
    al30f8_16  -- Altek, model AC30, format 8, 16 button cursor.

Description file format

The description file is composed of seven groups, each followed by a group of
commands in brackets. The file may also contain comments preceded by a pound 
sign ('#'). Legal group names are: setup, startrun, startpoint, startquery,
query, stop, and format. Each group name is followed by a list of commands and 

	command1 = value1
	command2 = value2
	commandn = valuen
Brackets may be on the same line as text, but open and close brackets must be
on different lines. Each group listed must appear in the format listed above. 
These are the only legal entries in the description file. The maximum length
per line is 95 characters and the maximum number of non-blank, non-comment 
lines is 100.

Any ascii character may be specified as a backslash followed by a three-digit
ascii decimal number. In this way pound signs and unprintable characters may
be included in command values. Legal commands and values depend on the group.
The setup group lists parameters specific to the digitizer, the format group
specifies the format of the input stream, and the other groups all specify
actual commands to be sent to the digitizer. Legal values for each group will 
be described below.


    digname = string 
	    (optional) May be any name of one or more words.
    description = string 
	    (optional) May be one or more words.
    buttons = n  
	    Number of buttons on cursor.
    buttonstart = n 
    	    Number of first button on cursor (usually 0 or 1)
    buttonoffset = n 
	    Offset to get input button values to 1-16. If your 
	    digitizer format outputs 0-15, buttonoffset would be 1.
	    For an ascii input format, the offset is computed from the
	    ascii values of the buttons so any starting character may be 
	    converted to one. For example, if the digitizer output the
	    characters A-P for button values, buttonoffset would equal -16.
	    Characters representing button values must be consecutive.
    button_up_char = 
	    Character used by digitizer to indicate that no button is pressed
    baud = n
	    (optional) Must be one of 300, 600, 1200, 1800, 2400, 4800,
	    9600, 19200. Default is 9600.
    parity = string
	    (optional) Must be one of odd, even, or none. Default is
    data_bits = n
	    (optional) The number of data bits (does not include parity)
	    Must be one of 5, 6, 7, 8. Default is 8.
    stop_bits = n 
	    (optional) The number of stop bits used on the parity line.
	    Must be either 1 or 2. Default is 1.
    debounce = d [r] 
	    (optional) The delay and repeat rate rate for cursor buttons.
   	    Delay (d) is the number of continuous reports necessary before a 
	    report is taken for a second button press. Repeat is the number 
	    of reports necessary for subsequent presses. Default for d is
	    0, default for r is d/3.
    units_per_inch = n
	    (optional) Default is 1000.
    coordinates = string
	    (optional) Must be either absolute or relative. Default is
    sign_type = string 
	    (optional) Must be one of: none (all positive), 0negative
	    (0 indicates negative), 1negative (1 indicates negative),
	    or 2s-complement. Default is none. This is for binary formats 
	    only, ascii formats should send a minus sign ('-') to indicate 
    x_positive = string
	    (optional) The direction of positive x coordinates. Must be 
	    either right or left. Default is right.
    y_positive = string
	    (optional) The direction of positive y coordinates. Must be 
	    either up or down. Default is up.

startrun, startpoint, startquery, query, stop

Each of these groups has the same set of legal values, but are used for 
different purposes. Startrun, startquery, and startpoint are the actions
taken to put the digitizer in run, query, and point modes. The query group
lists the actions necessary to query the digitizer for input. The stop
group lists the actions which stop digitizer output. The actions in each group 
will be taken in the order they are listed. All the actions are optional and
may be repeated. There may be no more than 40 operations in the start groups 
and the stop group, and no more than 10 in the query group.

    send = string 
	    Send any ascii string to the digitizer.
    read = n
	    Read n bytes before taking next action. Used for reading prompt
	    characters not for reading data.
    wait = n
	    Wait n seconds before next action. Fractional seconds are allowed.
	    May need to be changed if program is run on a faster cpu, to give
	    digitizer time to keep up.
    baud = n
	    Changes baud rate. Not normally necessary.

As mentioned previously, any character may be specified by a backslash followed
by its ascii decimal value.  All characters to be sent must be specified, 
including carriage return (\013) and linefeed (\010).


The format groups may be one of two types, ascii or binary. The information in
the format group controls how the program interprets packets of information
from the digitizer.

ascii format

	ascii = format_string

The format string must contain no embedded blanks. Legal characters in the 
string are:
    x -- one character of the x coordinate.
    y -- one character of the y coordinate.
    b -- character which indicates button value
    p -- character which indicates if button is up or down
    , -- comma character
    ? -- any other character of information (including blanks). Used as a 
	    place-holder only.


	ascii = ?xxxxx,yyyyy,?pb

It is not necessary to specify carriage return or linefeed. The sign character
should be included as part of the coordinates (an x or y ).

binary format

    Lines in the binary format group are of the form:

	byten = bit bit bit bit bit bit bit bit 

where byten is the string byte0, bite1, ... up to the maximum number of bytes. 
Bits must be separated by a space. Legal values for each bit are:

	xN  or yN -- bit N of the coordinate value. Low-order bit is 0, maximum
		is 30. Sign bits (if any) should be the highest bit number for
		a coordinate.
	bN -- bit N of button press value. Low-order bit is 0 maximum is 7.

	0 or 1 -- Sync bits, indicate bit is always 0 or always 1. Should all
		occur in the same bit column.
	p -- Bit which indicates whether or not button is pressed.

	? -- Any other information. Eight bits must be specified so if fewer
		than 8 bits are used, pad the left bits with ?. 


        byte1 = 1   p  b3  b2  b1  b0 x15 x14
        byte2 = 0 x13 x12 x11 x10  x9  x8  x7
        byte3 = 0  x6  x5  x4  x3  x2  x1  x0
        byte4 = 0   ?   ?   ? x16 y16 y15 y14
        byte5 = 0 y13 y12 y11 y10  y9  y8  y7
        byte6 = 0  y6  y5  y4  y3  y2  y1  y0

Example digcap and description files are included below.

Digcap file:


#  There will be NO blank lines and the digitizer definitions MUST be at
#  the end of the file.
# Information in this file:
#    name : tty : digitizer filename : description of digitizer
# The 'name' should be less then 20 characters 
# Filename must match the name of the file in  directory:  
#	    $GISBASE/etc/digitizers .
# altek1:/dev/ttyb:al30f1_16:Altek digitizer, model AC30, format 1 (ascii)
# none:nodig:nofile:  Run digit without the digitizer.
Calcomp:/dev/ttya:cc95f23_16:Calcomp digitizer, format 23 (binary) 
Altek:/dev/ttyb:al30f8_16:Altek digitizer, model AC30, format 8 (binary) 
none:nodig:nofile:  Run digit without the digitizer.
Calcomp_ascii:/dev/ttya:cc95f5_16:Calcomp digitizer, format 4 (ascii) 
GTCO_ascii:/dev/ttya:gtslf00_16:GTCO digitizer, format (ascii) 
GTCO_bin:/dev/ttya:gtslf01_16:GTCO digitizer, format (binary) 
Altek8:/dev/ttya:al30f8_16:Altek digitizer, model AC30, format 8 (binary) 
Altek3:/dev/ttya:al30f3_16:Altek digitizer, model AC30, format 3 (ascii) 
Altek5:/dev/ttya:al30f5_16:Altek digitizer, model AC30, format 5 (ascii) 
Kurta_ascii:/dev/ttya:kus3f02_16:Kurta digitizer, format 2 (binary) 
Kurta_bin:/dev/ttya:kus3f05_16:Kurta digitizer, format 5 (ascii) 


Description file


#  Calcomp 9500 ASCII format 12
# Originally built and tested by 
#  Terry Baker and David Gerdes  USA-CERL  1992

    digname = Calcomp
    description = Calcomp digitizer, ascii format 12
    buttons = 16                #number of buttons on digitizer
    buttonstart = 0             #number buttons start with
    buttonoffset = 1            #offset to get buttons 1-15
    baud = 9600
    units_per_inch = 1000
    button_up_char = U

    send = \027%^12\013          #set output format to format 12
    send = \027%R\013           #set to run mode

    send = \027%^12\013          #set output format to format 12
    send = \027%P\013           #set to run mode

    send = \027%^12\013          #set output format to format 12
    send = \027%R\013           #set to run mode
    send = \027%Q!\013          #set prompt character to '!' and 
				              #put in prompt mode

    send = !\013                #send prompt

    send = \027%H\013            #halt

    ascii = xxxxx,yyyyy,b

Another description file


#  Altek AC30 binary format 8
# Originally build and tested by 
#  Terry Baker and David Gerdes  USA-CERL  1992

    digname = Altek
    description = altek digitizer, binary output format 8
    buttonoffset = 1      #button output starts at 0, we want 1
    buttonstart = 0       #first button is numbered 0
    buttons = 16          #number of buttons is 16
    baud = 9600
    units_per_inch = 1000
    stop_bits = 1
    data_bits = 8
    parity  = none


    send = S2\013         #set to run mode
    send = F8\013         #set output format to 8
    send = P\013         #set to point mode
    send = F8\013        #set output format to 8
    send = P\013         #altek has no specific prompt mode, but may be
			  #queried at any time, so set to point mode
    send = F8\013         #set output format to 8

    send = V\013          #request data

    send = \027\013       #reset

format    # output format 8
    byte1 = 1   p  b3  b2  b1  b0 x15 x14
    byte2 = 0 x13 x12 x11 x10  x9  x8  x7
    byte3 = 0  x6  x5  x4  x3  x2  x1  x0
    byte4 = 0   ?   ?   ? x16 y16 y15 y14
    byte5 = 0 y13 y12 y11 y10  y9  y8  y7
    byte6 = 0  y6  y5  y4  y3  y2  y1  y0

More information about the grass-user mailing list