The following is derived from the manual for Line Trace Plus (LTPlus) by
John Dabritz and the Forest Service.  The code for the digitizer drivers
was taken from LTPlus and modified.  The 'additions' file describes what
has been changed from the original version.  Note that LTPlus supports
mice and trackballs as well as digitizers. These can be ignored for v.digit.


-------------------------------------------------------------------------------


digitizer/mouse/trackball ( dgt) files

Rules for digitizer/mouse/trackball files.


1.  No line may exceed 95 characters in length.

2.  In a line, all characters following (and including) a pound sigh (#) are 
    considered comments (ignored).  To put a pound sign into a string not to 
    be ignored, use a \035.  Any ascii character can be specified in this way: 
    a backslash followed by a 3-digit (ascii decimal) number specifying the 
    ascii decimal value of the character.

3.  All other non-blank characters must be within brackets {} OR be one of the 
    following (which are followed by brackets):
         setup
         startrun
	 startpoint
	 startquery
         stop
         query
         format
    These represent the groups of information used to initiate, gather,
    and stop input from a graphics input device (digitizer, mouse,
    track-ball ect.).  Only one (left or right) bracket may be on a
    single line, although text and brackets may share a line.

4.  Limits:
    a)  The file can have no more than 100 non-blank, non-comment lines.
    b)  Other limits are listed with their data type, below.

5.  The legal lines within brackets depend on the group to which the brackets 
    belong.  ALL DATA LINES ARE DEPENDENT ON THE PARTICULAR DEVICE.
    YOU MUST REFER TO THE TECHNICAL REFERENCE MANUAL FOR THE PARTICULAR
    DEVICE (mouse/digitizer/track-ball) in order to determine which
    parameters and which values need to be used.  The groups (setup,
    startrun, startpoint, startquery, stop, query , format) may be 
    in any order.  Within the groups: startrun, startpoint, startquery, 
    query, and stop the order of command lines is
    important.  These are the legal line formats for each grouping:

------------------------------
SETUP (this data is to setup the communication link with the digitizer and is 
used during interpretation of the digitizer data):

   (serial line characteristics)
a.  baud=n        This line is optional, default = 9600 if not specified.  If
                  specified, n must be one of : 300, 600, 1200, 1800, 2400, 4800
                  9600, 19200.

b.  parity=str    str must be "odd", "even", or "none".  This item is optional,
                  and defaults to none if not specified.  

c   data_bits=n   The number of data bits used (does NOT include parity bits,
                  if any).  Choices = 5,6,7,8 (default = 8)

d.  stop_bits =n  The number of stop bits used on the serial line.  Choices are
                   1, or 2.  Optional, default = 1.


e.  buttons = n.  Number of buttons on digitizer cursor. This entry
    		  lets v.digit know if digitizer keys are available for input. 
                  Default is 0, so an entry must be made if the digitizer 
		  cursor is to be used for input. If the value of buttons is 
		  less than 5, keyboard keys will also be used for input.

f.  buttonstart = n. Number of the first key on the digitizer cursor.
                  Usually 0 or 1. Default is 0. This is strictly for 
		  comunicating with the user.  If you have arrow keys
		  on your puck, you can set buttonstart to whatever you 
		  want.

g.  buttonoffset = n. Difference between 1 and the value sent by the lowest
                  digitizer button. In other words, if the digitizer keys sent 
		  the values 0, 1, ..., n, buttonoffset would equal one, if the
		  button output already starts with one, buttonoffset would be 
		  zero (the default value).  Although these are the two most 
		  common cases, it is legal for buttonoffset to be any integer 
		  value.  For instance if your keys for some reason output the 
		  values 16-32, it would be legal to use the value -15 as the 
		  buttonoffset.

h.  footswitch =  0 or 1. Does the digitizer have a footswitch? Zero for no, 
		  one for yes.

i.  digname = string. Name of the digitizer.

j.  description = string. One line description of digitizer, format, etc.

k.  button_up_char = c. Character that indicates that no button is pressed.
                  Only appropriate if format is ascii and includes a button
		  press byte.
  
  (data interpretation characteristics)
l.  debounce=d [r]   These values control the delay and repeat rate for a 
		     digitizer/mouse button that is held down (who says
		     you can't hold a good button down!)  The first
		     value (delay) specifies the number of continuous
		     reports with the same button press which may be
		     received before it is taken as a second button
		     press.  The second value (repeat rate) (separated
		     by a space), specifies the number of continuous
		     reports between further reports received which
		     will be taken as subsequent button presses.  The
		     second value (repeat rate) is optional (default
		     =1/3 first value).  A O for the first value
		     indicates an infinite delay.  For this value
		     indicates an indefinite delay.  For this value,
		     only 1 key press will be taken no matter how long
		     a button is held down.  If no debounce values are
		     listed, the default of 0s will be used.

m.  units_per_inch=n  Helps to set sensitivity (on absolute type devices 
		     see next item below) & map-inch size.  dflt=1000.  
		     Not used for relative type devices (mice), see     
                      below:

h.  coordinates=str  str must be 'absolute' or 'relative', dflt=absolute.  
		     In general, mouse/trackball devices are relative, and 
		     digitizers coordinates are absolute.

i.  sign_type =aaa   This indicates the sign type for binary formats:
                     none  (all +) (default for absolute crds).
                     0negative (o=neg, used for some abs coords).
                     1negative (1=neg, used for some abs coords).
                     2s-complement (default for relative coords).

                     Note: for binary formats the sign bit should be coded as 
			   highest bit number for a coordinate.

                     Note: for ascii formats, minus (-) sign is expected from 
		     the raw device to indicate a negative number.

j.  x_positive = dd  This indicates the direction of x-positive coordinates.  
		     dd is a sting which may have the value right or left. 
		     The default is right.  All digitizers and mice have 
		     x-positive to the right as of this writing.

k.  y_positive = dd  This indicates the direction of y-positive coordinates.  
		     dd is a string which may have the value up or down. 
		     The default is up.  The microsoft mouse is a digitizing 
		     device which has y-positive coordinates to indicate a 
		     downward movement.

l.  digcursor=fname  Specifies the cursor file to be used while this digitizer 
                     is in use with LTPlus program. The digcursor file defines 
                     which command each digitizer button generates. v.digit does
                     not need a cursor file, and ignores this line.
 
Note:  Order of items is unimportant within the setup group.

example of a setup

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
}

___________________________________________

    STARTRUN, STARTPOINT, STARTQUERY, STOP, QUERY.  All of these allow the 
    same operations, but are used at different times when communicating 
    with the digitizer/mouse.  The START groupings are used to initialize the 
    digitizer each time communication is switched to that mode.  The QUERY 
    grouping is used when (and if) the digitizer is queried/prompted to send 
    data information.  The STOP grouping is used to stop digitizer output and 
    put the digitizer to bed.  All of these groupings are optional but at least 
    one start group must be included (to use the file with v.digit, the 
    startquery group must be included). If the digitizer is configured by 
    default or switch settings to output data in the desired form of a certain
    mode, it is desirable to include that start group anyway, with some 
    innocuous action (such as sending a carriage return) as the only action.
    If a start group is not included for a given mode, the program assumes
    that the digitizer is unable to operate in that mode.
        There may be no more than 40 operations within each start group or 
    the stop group.  There may be no more than 10 operations in the query 
    group.  The operations allowed in any of these groups are:

a.  send=aaaa    This allows the sending of any ascii string to the digitizer 
		 (at the current baud rate and parity)

b.  read=n       This tells the program to read n bytes from the digitizer 
		 before trying to read again (gives up trying to read after 
		 1 second).  This is for reading digitizer prompts during 
		 start & stop groups and is NOT used for querying the 
		 digitizer, unless a non-data string is to be read (like 
		 a prompt character).

c.  wait=n       wait n seconds (decimal seconds allowed) before next 
		 communication with the digitizer.  Many computers are quicker 
		 than digitizers and need to allow time for the digitizer
                 to change baud rate before resuming communication.  Maximum 
		 resolution for wait is 0.001 second.

d.  baud=n       This allows changing of baud rate which was set during setup 
		 and is normally not used otherwise.  If only 1 baud rate is 
		 used, then it is put in the setup group only.  This is
                 the normal case for most digitizers.

NOTE:  control, extention, space, and all other characters can be specified 
in sent strings by using the backslash followed by the ascii decimal value to 
be sent (up to 3 digits).  Example: send=/027 (indicates the escape character).

NOTE:  The lines/commands communicating with the digitizer will be executed 
in the SAME ORDER as they are in the start/stop/query grouping.  Order is very 
important.  Wait commands may be necessary to give the digitizer time to 
execute the command sent.  Wait commands may need to be added/changed when
the main programs is run on a faster cpu (in order to give the digitizer enough
time to keep up).

NOTE:  A maximum of 40 non-comment lines can be in a start, stop, or query 
group.

NOTE:  All characters to be sent must be specified, including carriage return 
(\013) and linefeed (\010).

NOTE:  Each time a QUERY group is executed, a 0.001 second wait is done 
automatically after all query group commands.  This allows time for the 
graphics input device to send a packet of information before the serail line 
is read by the program.  

DIGIT_NOTE:  v.digit requires that a STARTQUERY group exists.


example of start groupings:

startrun
{ 
  send = \027%R
  baud = 2400
  wait = 0.6
  read = 3
  wait = 0.1
  send = \027%S
}

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
}
example of a query grouping:

query
{ 
   send = !\013                #send prompt
}

example of a stop grouping:

stop
{  send = \027%K
   wait = 0.1
   send = \027%*
}
____________________________________

format     (this data is used each time a packet of information from the 
	   digitizer is interpreted).  This group must be one of 2 types, 
	   ascii or binary.  The digitizer file MUST contain a format 
	   group (either ascii or binary).

       Ascii format groups have only 1 line:
              a.  ascii = format_string

       Binary format groups have one line for each byte in the form:
              b.  byteN = format_string  (where N is the byte number, 1 
		  or greater) or byte No = format_string  (similar to
		  above for OPTIONAL bytes).  NOTE:  The program
		  assumes the optional bytes containing ONLY button
		  press information (no x or y information).

The legal format strings depend on the type (ascii or byteN)

a.  ASCII format strings have these characteristics:
   1.  There are no imbedded blanks.
   2.  Legal characters are:
       x - denotes 1 character of the x-coordinate value (sign included).
       y - denotes 1 character of the y-coordinate value (sign included).   
       b - denotes 1 character of button information.
       p - denotes 1 character of button press information (up  or down).
       , - denotes the comma character (used to sync data if present).
       c - denotes a carriage return (optionally specified)
       l - denotes a line-feed (optionally specified) 
       ? - denotes any other character of information (including blanks).

NOTE:  The sign (+ or -) should be coded as part of the x or y value.

NOTE:  The specifications of the carriage-return and linefeed are totally 
       optional.  They will be ignored whether they are specified or
       not.  Their only use is to separate one ascii grouping of incoming 
       data from another.  Any combination of carriage-returns and/or 
       linefeeds will serve this purpose in any case os ascii format use.

example of ascii format grouping:

format
{
    ascii =?xxxxx,yyyyy,??bcl
}

b.   Binary format string: have these characteristics

    0.  byteNo form is used only for bytes which are sometimes, but not always 
	sent by the digitizing devices.  These byte (s) must be at the
	end of the grouping/packet.  For example, the Logitech Mouseman
        sends an optional 4th bytes only when the middle button is
        pressed.  Very few digitizing devices use optional bytes.

    1.  8 bits are specified with at least 1 blank between bit groupings, even 
	if fewer bits are used (fill the left [high] bits with ? if necessary).

    2.  Legal characters are:
        xN - denotes bit N of the x-coordinate value (low-order bit is 0, 
	     maximum bit allowed is 30) (include sign bit as highest bit used)
        yN - denotes bit N of the y-coordinate value (low-order bit is 0, 
	     maximum bit allowed is 30) (include sign bit as highest bit used) 
        bN - denotes bit N of button press value (low-order bit is 0, maximum 
	     bit allowed is 7).
        p - denotes button press bit (will be 1 if button is pressed, 0
	    otherwise).
        0 - denotes bit is always zero (used for sync bit).
        1 - denotes bit is always one (used for sync bit).
        ? - denoted any other information (bit not used).

NOTE: There cannot be more than 100 lines of byten = in the format group.

NOTE: Sign bits (if any) should be coded as the highest bit number for a 
      given coordinate.

NOTE: Parity bits (if in the lowest 8 bits), and fill bits (if fewer than 8 
      bits used) should be coded as ?.  No bits above the lowest 8
      should be specified ar all (sometimes there is a 9th parity bit).

NOTE: 0s and 1s are used for syncing the input, and should all occur in the 
      same bit column.

examples of a binary format grouping:
       (example with odd or even parity and 7 data bits)

format
{ byte1 =  ?    1    ?    ?    ?    ?     ?    ?
  byte2 =  ?    0    ?   b4   b3   b2    b1    b0
  byte3 =  ?    0   x5   x4   x3   x2    x2    x0
  byte4 =  ?    0  x11  x10   x9   x8    x7    x6
  byte5 =  ?    0  x16  x17  x15  x14   x13   x12
  byte6 =  ?    0   y5   y4   y3   y2    y1    y0
  byte7 =  ?    0  y11  y10   y9   y8    y7    y6
  byte8 =  ?    0  y16  y17  y15  y14   y13   y12
}
or
       (example with 8 data bits [with or without parity])
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 1. of an entire file:


setup
{
    digname = Calcomp
    description = Calcomp digitizer, ascii format 5
    buttonoffset = 1
    buttons = 16
    buttonstart = 0
    baud = 9600
    units_per_inch = 1000
}


startrun
{
    send = \027%^5\013 #set to format 5
    send = \027%R\013
}

startpoint
{
    send = \027%^5\013 #set to format 5
    send = \027%P\013
}

startquery
{
    send = \027%^5\013 #set to format 5
    send = \027%R\013
    send = \027%Q!\013
}

query
{
    send = !\013
}

stop
{
    send = \027%H\013
}

format 
{
    ascii = xxxxx,yyyyy,??b
}
____________________________________________________________________

Example 2.  of an entire file:

setup
{
 digname = Altek
 description = altek digitizer, model AC30, 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
 parity = none
 stop_bits = 1
 sign_type = none
 units_per_inch = 1000
 coordinates = absolute
 sign_type = none
}

startrun
{ 
    send=S2\13           #set to run mode
    send=F8\13           #set output format to 8
    send=R6\13           #enter rate mode 6
}
startpoint
{
    send = P\013         #set to point mode
    send = F8\013        #set output format to 8
}
startquery
{
    send = S2\013         #altek has no specific prompt mode, but may be
                          #queried at any time, so set to run mode
    send = F8\013         #set output format to 8
}

query
{
    send = V\013          #request data
}

stop
{
    send = \027\013       #reset
}


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
}
__________________________________________________________________
