adio: (version 0.4beta) 3Nov2010

NAME:
        adio  -  Simple command line program to access the TS7200 DIO and
	         LCD ports and the 8 channel ADC if fitted.

SYNOPSIS:

        adio [-v] [-i file] [-o file] commands

DESCRIPTION:

adio implements a simple set of commands that enable general IO tasks
to be implemented. There are commands for:
 
 - reading individual lines from DIO and LCD interface 
 - reading voltages from individual channels of the ADC
 - setting lines in the DIO and LCD interfaces to be input or output lines
 - setting lines in the DIO and LCD interfaces to a logic '0' or '1',
 - waiting for a DIO line to become a logic '0' or '1'
 - waiting for an ADC channel to become less or greater than fixed values
 - pausing for preset times
 - outputing text and ADC, DIO and LCD values
 - looping & repeating a set of commands a number of times or until 
   certain conditions are met.
 - commands to set timers and output timer values or general timestamps

adio is meant to be of use in fairly slow IO jobs where high speed
accuracy is not necessary. The basic timing only has a resolution of
aprox 10msec, and the accuracy is determined by the accuracy of the
basic Linux jiffy implementation.

adio allows DIO, LCD and ADC lines to be monitored and logged, allows
complicated sets of outputs to arbitrary lines etc.  To get an idea of
what it can do skip down to the Examples section.  The rest of this
section details the commands implemented.

adio also works with the TS7250/TS7260 boards.

adio executes commands given on the command line, then any commands
from any file specified in an -i option (see below).

There are 9 lines on the DIO header - these are numbered 0 to 8. There
are 11 lines on the LCD header data 0 to 7, EN, RS and WR, these are
accessed as DIO lines 10 to 20. Each line is controlled individually.
When setting a line to a value, a Read-Modify-Write sequence is used
to prevent interfering with the state of other lines in the port.
Setting a DIO or LCD line to 0 or 1 automatically causes the DIO DDR
bit for that line to be set to output.

There are 8 12 bit channels in the ADC option, these are numbered 0 to 7.
Each ADC channel can operate in 4 different ranges:

Range  0 is unipolar 0-5v         LSB = 1.2mV
       1 is bipolar -5v-0-5v            2.4mV
       2 is unipolar 0-10v              2.4mV
       3 is bipolar -10v-0-10v          4.9mV

Voltages are displayed to 3 places of decimal, but it must be
remembered that the accuracy of the measurement is only that
equivalent to, at best, 12 bits covering the full voltage range
selected. The ADC (MAX197) has errors assocaited with its voltage
reference, amplifier offset and gain (see the MAX197 data sheet).
Without reference voltage adjustment, and offset and gain error
correction the basic accuracy is probably aprox. 2%. However the
linearity is claimed to be very good at +/-1 LSB for the 'B' part and
+/- 1/2 LSB for the 'A' part.

Commands can be......

 dN        read DIO line N and print value
 dN=0|1    set DIO line N to 0 or 1. Using this sets that line as
           an output line in the DDR

             N = 0  to 8     DIO Header lines D0-8
             N = 10 to 17    LCD Header lines LCD D0-7
             N = 18,19,20    LCD Header lines EN, RS, WR respectively

 DN        read DDR (data direction register) for DIO line N
           '0' means an input line, '1' means an output line
 DN=0|1    set the DDR for DIO line N to '0' or '1'
             values of N as above

 aN[,R]    read ADC channel N in optional range R. If R is not
           specified then range 3 (+/-10v) is used.

 sTn       start timer n. There are 10 timers numbered 0 to 9.
           see the output command '.' for outputing the timers.

 pN        pause for N millisecs. However this only has a resolution
           of aprox 10mS.

 PN        pause for N seconds. Useful for very long pauses.

 wdN=[0|1] wait for DIO line N to become a 0 or a 1.
             values of N as above 

 waN[,R]<V wait for ADC chan N, range R, voltage to be less than V
 waN[,R]>V wait for ADC chan N, range R, voltage to be greater than V

 wAN[,R]<V wait for ADC chan N, range R, raw measurement to be less than V
 wAN[,R]<V wait for ADC chan N, range R, raw measurement to be greater than V

 Wt        set a maximum time to wait on any future wait command.
           t is in millisecs. This is only aproximate and is subjec to
           10mS aprox. accuracy. The initial value is set to 1 hour.
	   If set to 0 then the wait is infinite.

 lN command|(SEQUENCE)|iFILE
           loop N times repeating the commands in SEQUENCE or from FILE.
           SEQUENCE is simply a set of space seperated commands quoted 
	   together. If N is 0 or omitted then the loop is infinite.

 lCOND  command|(SEQUENCE)|iFILE
           loop until the condition COND is met, repeating the command or the
           commands in the compound command (SEQUENCE) or the commands in FILE
           see the 'w' command for the various possible conditions.        

 .STRING   output STRING. Remember if it contains spaces to enclose in quotes.
           As for printf, various control codes can be output by using
           the escape character '\' e.g. \n for a newline, \t for a tab,
           \\ for a '\' etc. If using '\' on the command line remember to 
           quote the whole string in single quotes.

           There are some specials escape sequences....

            \T    output  a timestamp, giving elapsed time from the start
                  of the program

            \Th   output time of day as hh:mm:ss.mmm

            \Tn   output the value of one of the 10 timers numbered 0-9
                  as secs.millisecs

	    \Thn  output the value of timer n in hh:mm:ss.mmm format

 iFILE     read command from FILE.
           If file is '-' then read commands from stdin
	   if stdin is the tty then enter interactive mode, like a shell.

 q[N]      quit, setting exit code to N, or 0 if not specified.
 
 ( command command .... )  a compound command. This must be all on one 

           logical line, and there is an implicit ')' at the end of a
           line. As in shell scripting a logical line can be 
           broken over one or more extension lines by making the last
           character on the previous line a '\'. see examples below.
           A single command cannot be split over real lines - there is 
           an implicit space seperator at the '\'.


Command line options & Flags:

 -v       verbose output

 -o file  output to file instead of stdout

 -i file  read commands from file 


Examples:

A simple interactive command interpreter....

  adio

  prompt for commands and executes them. Useful for testing and
  messing around. The line parsing may currently be a bit buggy
  when using quotes (" or ') or braces '(' to make one command.
  The next version will be better - it might need a redesign.
  Nested loops might be problematic.

A DIO Line monitor with time stamp......

  adio  D0=0 D1=0 D3=0 'l100 .\T\  d0 .\   d1 .\  d3 p1000 .\n '

  set all lines 0, 1 and 3 to input, loop 100 times:
  output timestamp, a ' ', then read bit 0 and output its value, 
  then a ' ', then ditto for bits 1 and 3, then pause for 1 sec (1000mS)
  and output a newline before repeating.

An ADC monitor with timeofday stamp....

  adio 'l1000 .\Th\  a0.0 p500'

  Print time of day and a space followed by voltage reading from
  channel 0 on range 0 (0-5v) every 500millisecs for 1000 times. 
  
A simple traffic light sequence.....

  adio 'l100 d0=1 d1=0 d2=0 p5000 d0=0 d1=1 p1000 d1=0 d2=1 \
     p5000 d1=1 p1000 d2=0 d1=0 d0=1 p5000'
     
  With a green led (and limiting resistor) connected to line 0, an amber
  (yellow/orange) to bit 1, and a red to bit 2, this simulates a UK
  traffic light sequence running 1000 times.
  
A 1Hz generator.....

  adio 'l d0=0 p500 d0=1 p500'

  outputs a continous 1Hz square wave on bit 0

2 x 1Hz generators one with a 2% mark/space ratio the other in antiphase.....

  adio 'l d0=1 d1=0 p20 d0=0 d1=1 p980'

  outputs a 20mS pulse on bit 0 every second. Bit 1 is
  the inverse of bit 0.

Monitor and timestamp rising DIO line transitions.......

  adio D0=0 'l wd0=0 wd0=1 .\T\n' 

  set line 0 as an input line, wait for bit 0 to goto 0
  then wait for it to goto 1 and output a timestamp and newline
  then repeat forever. This records the time of rising edges
  of a signal on pin 1.

Time the period between a line going to 1 then going back to 0....

  adio D0=0 'l wd0=1 sT0 wd0=0 .\T0\n'

  sets line 0 to an input line, then loop forever waiting for line 0 to
  go to 1, setting timer 0, waiting for a 0, and output value of timer 0
  and a newline.

Wait for a 0 to 1 transition then record the ADC channels 0 and 2....

  adio D0=0 'l wd0=0 p50 wd0=1 .\Th\  a0 .\  a2 .\n'

  sets line 0 as input, then loops. wait for a 0 on line 0 then a
  small pause, then wait for a 1 on line 0 (this does some simple
  "debouncing"), then output the time of day, a space, voltage on ADC
  ch 0, a space and voltage on ADC ch2 and a newline.



NOTES:

When entering commands from the shell command line be very very VERY 
careful about shell metachars, quoting and other shell funnies.

When outputing space with the '.' print command, remember there needs
to be a space to terminate the print command, otherwise you might find
the next command becomes part of the output, e.g. try these

  adio '.\ a0 .\n'
  adio '.\  a0 .\n'


BUGS:

Of course! This is beta s/w knocked together in my free time (precious
little) over a week. 

Too many error reports, and not enough diagnostics.

Let me know if you use this software.  Any bugs, questions,
suggestions or problems, etc. should be sent to

Jim Jackson   <jj@franjam.org.uk>
