LINUX SDK

LINUX SDK

ADU Command Line Utility

The adu command line utility allows an ADU device to be
controlled from a console or from a script.

The adu source code is liberally licenced so you
may copy it to develop your own programs.
(Easy-Use Home)

adu Command Line Utility Documentation

Input commands can be placed on the command line,
typed in from a console, piped in from another program
or delivered through a file.

Results are written to stdout so they can be piped to
other programs.

Usage

    adu -f filename -i id -r -v command

Options

        -f filename  the name of a file containg commands to
                     be written to the ADU device
        -i id        the id of the ADU device, This is used to
                     form the path used to access the ADU.
                     (ie -i 0 means /dev/adutux0)
        -r           Causes adu to read the response from the 
                     ADU device. If a command is present on the
                     command line then it is written to the ADU
                     device before the read is attempted. If no
                     command is present on the command line then
                     you must request a response from the ADU
                     with a prior operation first.
        -v           Causes adu to print its version number.
        command      Command that is sent to the ADU device.

Modes

adu can be used in 5 ways
 (1) specify a command on the command line
     eg adu mk3
 (2) place commands in a file identified by the -f option
     eg adu -f command.file
 (3) enter commands through the console interactively
     eg adu
     
 (4) pipe commands in from another program
     eg cat command.file | adu
 (5) redirect input from a file
     eg adu < command.file

Command Formats

Lines entered from the console, a file or a pipe consist
of an action followed by an optional command.
The action w (for write) causes the command to be written
to the ADU device.
The action r (for read) causes the response from the ADU
device to be read.

NOTE: In console or file mode the action MUST be the first
byte of the input line, optionally followed by a space and
a command. (ie first character must be w or r or s.)

Example (using ADU208, other models may use different commands)

    w mk3
    w pk
    r
    r pk

The above lines cause the mk3 command to be written to the
ADU device. This is followed by the pk command that asks
the ADU device to return the relay settings. The r action
causes the response to be read. If the r action is accompanied
by a command on the same line then the command is written
before the response is read from the ADU device.

Buffering

The adutux driver contains buffers for I/O. The buffers
are cycled for each block of data processed. Once the buffers
are full then the ADU device will appear unresponsive.
This means that each responsive command must be followed by
a read operation to release the buffer.

If you write a responsive commands without an accompanying
read operation then the response is left in the buffer.
Then if you write a second responsive command and do a
read you will get the response to the first command. The
response to the second command will be sitting in the buffer
waiting for your next read operation.

Example:
Consider a command file containing

    w db1
    w db
    w mk3
    w pk
    r
    r

The "w db1" instructs the ADU to set the debounce
value to 1.
The "w db" line instructs the ADU to return the
debounce setting BUT does not read the response
(note the action is w). The response is left
sitting in a buffer.
The "w mk3" command sets the relays to 003.
The "w pk" command instructs the ADU to return
the value of the relays but does not read the response.
The first "r" action does a read and gets a 1, the debounce
setting from the first responsive command.
The second "r" action does a read and gets 003, the relay
value.
Taken in isolation the "w pk" followed by a response
of 1 appears incorrect. However in context with the
preceding unread "w db" response the results are
predictable.

It does not hurt to do extra reads to insure that the buffers
are clear. (ie repeatedly read until a timeout occurs).

Scripting Example

(Gasp.... an example ..... Richard Stallman will NOT be pleased.)

Here is a simple bash shell script to monitor an event
counter and turn on a relay for 1 second.

    #!/bin/bash 
    echo == ADU bash shell script event counter demo ==
    while [ 1 -eq 1 ] 
    do
            # the re0 response is piped to the basic calculator
            Count0=$(./adu -r re0 | bc)
            echo count is $Count0
            if [ $Count0 -gt 20 ]
            then
                    echo counter exceeds 20 hits -- value is $Count0
                    # toggle relay k0 to simulate an action
                    ./adu mk1
                    sleep 1 # keep relay k0 on for a while
                    ./adu mk0
                    echo now resetting the counter
                    ./adu -r rc0
            fi
            sleep 1 # for a real application you may want to
                    # be more responsive
    done

Demonstration of the Script

A wire was hooked up to the VDD terminal of an ADU208.
The wire was rapidly dragged across the PA0 terminal
while the script was running. This fed a large number
of brief pulses to the PA0 event counter.
The resulting console output is shown below.

    $ ./demo.sh
    == ADU bash shell script event counter demo ==
    count is 1
    count is 6
    count is 10
    count is 21
    :counter exceeds 20 hits -- value is 21
    now resetting the counter
    00027
    count is 8
    count is 15
    count is 21
    counter exceeds 20 hits -- value is 21
    now resetting the counter
    00030
    count is 2
    count is 13
    count is 23
    counter exceeds 20 hits -- value is 23
    now resetting the counter
    00025
    count is 0
    count is 0
    count is 0

Credits

Thanks to Steven Haigh for instigating the development.
Thanks to Vasudev Ram for his article about command line
utility development (available from IBM Developer Works).
Thanks to Ulrich Drepper and Torbjorn Granlund for
providing GPL source that served as a good example.
Thanks to Tom Fortin at Ontrak Control Systems for
providing ADU devices.

Licensing

I am not a lawyer. The adu utility is not a copy of
any other utility, however I did inspect GPLed code
to figure out how best to use the Gnu libraries.
Depending upon your juridiction, this may affect your
rights and obligations.
The adu utility is copyright 2005-2008 by John Homppi.
You may choose to license the adu utility by your
choice of
(1) public domain. No royalties, no attributions,
no restrictions
or (2) Lesser GPL
or (3) GPL
depending on the legislation in force in your
country.
I cannot speak for the owners of copyrights on
the Gnu libraries or the Linux operating system.

Fedora Core

adu was developed on a Fedora Core Linux distribution.
It makes use of standard Gnu libraries provided by the
Free Software Foundation. Hopefully it will run on other
Linux distributions that utilize the standard Gnu
libraries.
-------------------------------------------------------
readme.text version 0.0.0.3