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
where:
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:
none:nodig:nofile:
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
digitizer.
Examples:
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
values:
groupname
{
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.
setup
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
none.
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
absolute.
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
negative.
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).
format
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.
Example:
format
{
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 ?.
Example:
format
{
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:
--------------------------------------------
# DIGITIZER DEFINITION 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.
#
# EVERYTHING BELOW THIS LINE ARE ACTUAL DESCRIPTIONS:
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
setup
{
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
}
startrun
{
send = \027%^12\013 #set output format to format 12
send = \027%R\013 #set to run mode
}
startpoint
{
send = \027%^12\013 #set output format to format 12
send = \027%P\013 #set to run mode
}
startquery
{
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
}
query
{
send = !\013 #send prompt
}
stop
{
send = \027%H\013 #halt
}
format
{
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
setup
{
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
}
startrun
{
send = S2\013 #set to run mode
send = F8\013 #set output format to 8
}
startpoint
{
send = P\013 #set to point mode
send = F8\013 #set output format to 8
}
startquery
{
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
}
query
{
send = V\013 #request data
}
stop
{
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