AFNI program: serial_helper

------------------------------------------------------------
/var/www/html/pub/dist/bin/linux_gcc32/serial_helper - pass motion parameters from socket to serial port

    This program is meant to receive registration (motion?)
    correction parameters from afni's realtime plugin, and to
    pass that data on to a serial port.

    The program is meant to run as a tcp server.  It listens
    for a connection, then processes data until a termination
    flag is received (sending data from the tcp socket to the
    serial port), closes the new connection, and goes back
    to a listening state.

    The basic outline is:

    open tcp server socket
    repeat forever:
        wait for a tcp client connection
        open a serial port
        while the client sends new data
            write that data to the serial port
        close the serial port and client socket

    The expected client is the realtime plugin to afni,
    plug_realtime.so.  If the afni user has their environment
    variable AFNI_REALTIME_MP_HOST_PORT set as HOST:PORT,
    then for EACH RUN, the realtime plugin will open a tcp
    connection to the given HOST and PORT, pass the magic hello
    data (0xabcdefab), pass the 6 motion parameters for each
    time point, and signal a closure by passing the magic bye
    data (0xdeaddead).

    On this server end, the 'repeat forever' loop will do the
    following.  First it will establish the connection by
    checking for the magic hello data.  If that data is found,
    the serial port will be opened.

    Then it will repeatedly check the incoming data for the
    magic bye data.  As long as that check fails, the data is
    assumed to be valid motion parameters.  And so 6 floats at a
    time are read from the incoming socket and passed to the
    serial port.

  usage: /var/www/html/pub/dist/bin/linux_gcc32/serial_helper [options] -serial_port FILENAME
------------------------------------------------------------
  examples:

    1. display this help :

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -help

    2. display the module history :

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -hist

    3. display the current version number :

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -ver

  * 4. run normally, using the serial port file /dev/ttyS0 :

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -serial_port /dev/ttyS0

  * 5. same as 4, but specify socket number 53214 :

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -serial_port /dev/ttyS0 -sock_num 53214

    6. same as 5, but specify minmum and maximum bounds on
       the values :

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper                       \
            -serial_port /dev/ttyS0            \
            -sock_num 53214                    \
            -mp_min -12.7                      \
            -mp_max  12.7

    7. run the program in socket test mode, without serial
       communication, and printing all the incoming data

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -no_serial -debug 3

    8. same as 4, but use debug level 3 to see the parameters
       that will be passed on, and duplicate all output to the
       file, helper.output

       note: this command is for the t-shell, and will not work
             under bash (for bash do the 2>&1 thingy...)

        /var/www/html/pub/dist/bin/linux_gcc32/serial_helper -serial_port /dev/ttyS0 -debug 3 |& tee helper.out
------------------------------------------------------------
  program setup:

    1. Start '/var/www/html/pub/dist/bin/linux_gcc32/serial_helper' on the computer with the serial port that
       the motion parameters should be written to.  Example 3
       is the most likely case, though it might be useful to
       use example 8.

    2. On the computer which will be used to run 'afni -rt',
       set the environment variable AFNI_REALTIME_MP_HOST_PORT
       to the appropriate host:port pair.  See the '-sock_num'
       option below for more details.

       This variable can also be set in the ~/.cshrc file, or
       as part of the AFNI environment via the ~/.afnirc file.

    3. Start 'afni -rt'.  Be sure to request 'realtime' graphing
       of the '3D: realtime' Registration parameters.

    4. Start receiving data (sending it to the realtime plugin).

       Note that for testing purposes, I may work well to get a
       set of I-files (say, in directories 003, 023, etc.), and
       to use Imon to send not-so-real-time data to afni.  An
       example of Imon for this purpose might be:

           Imon -start_dir 003 -quit -rt -host localhost

       See 'Imon -help' for more information.
------------------------------------------------------------
  'required' parameter:

    -serial_port FILENAME : specify output serial port
                          : -serial_port /dev/ttyS0

        If the user is not using any of the 'special' options,
        below, then this parameter is required.

        The FILENAME is the device file for the serial port
        which will be used for output.
------------------------------
  special options (for information or testing):

    -help            : show this help information

    -hist            : show the module history

    -debug LEVEL     : set the debugging level to LEVEL
                     : e.g. -debug 2
                     : default is 0, max is 3

    -no_serial       : turn of serial port output

        This option is used for testing the incoming data,
        when output to a serial port is not desired.  The
        program will otherwise operate normally.

    -version         : show the current version number
------------------------------
  'normal' options:

    -mp_max MAX_VAL  : limit the maximum value of the MP data
                     : e.g. -mp_max 12.7
                     : default is 12.7

        If any incoming data is greater than this value, it will
        be set to this value.  The default of 12.7 is used to
        scale incoming floats to signed bytes.

    -mp_min MIN_VAL  : limit the minimum value of the MP data
                     : e.g. -mp_min -12.7
                     : default is -12.7

        If any incoming data is less than this value, it will
        be set to this value.  The default of -12.7 is used to
        scale incoming floats to signed bytes.

    -sock_num SOCK   : specify socket number to serve
                     : e.g. -sock_num 53214
                     : default is 53214

        This is the socket the program will use to listen for
        new connections.  This is the socket number that should
        be provided to the realtime plugin via the environment
        variable, AFNI_REALTIME_MP_HOST_PORT.

        On the machine the user run afni from, that environment
        variable should have the form HOST:PORT, where a basic
        example might be localhost:53214.
------------------------------------------------------------
  Authors: R. Reynolds, T. Ross  (March, 2004)
------------------------------------------------------------