
    Purpose:     transparent mode (terminal emulator)
     Usage :     tm [(+string | file)... ]

    Switches
     -x ccc      `esc', quit, shell  chars
      defaults:   \0    <->    <.>          (<ALT X> =quit, <ALT C> =shell)
     -d[dev#]    [COM device#] none: local                 (default:     1)
     -b baud     baud rate        0: no change             (default: 19200)
     -t[ms]      transparent mode [or timeout]    (default: timeout    999)
     -l[n]       leave transfer on receive [loop, transfer is done n times]
     -w ms[,n]   wait if a string is empty (!) [and after max. n filebytes]
     -c ms       delay after any char                    (string/file only)
     -s ms[,s]   delay after \n [or selected chars in s] (string/file only)
     -u ref      un-calibrated delays, ref-based  (default:  milli seconds)
     -i          ignore -cs during filetransfer
     -f s        filter out chars specified in s                (file only)
     -r c[s]     replace char with nothing [or s]               (file only)
     -k c[s]     `esc'-c key-sequence sends nothing [or s]
     -n          no message when entering transparent mode
     -m[c][... ] monitor receive-data [or c] on stderr  [options see below]
     -p[r]       packed  mode for transfer [or receive]
     -g WxH+X+Y  window geometry (see below)
     -e file     capture all KEYBOARD ENTRIES to file       (always binary)
     -v          verbose mode
     -a          all files ASCII mode

    DESCRIPTION  (see also: man util)

         TM is a program which allows communication with remote hardware
         via serial port.
         In the first place it is intended to be used with simple hardware
         such as single-board computers, providing features like command
         transmission, down-/upload and control functions via handshake
         lines.
         TM is a very flexible and therefore complex program. Its usage is
         not understandable at a glance, but you will find that it provides
         a solution for nearly any problem concerning serial communication
         within the above mentioned scope (see list of examples at the end
         of this description).

    DETAILS

     -x  `esc': This character (not to be mistaken for the ESC-key!)
                introduces a 2-byte sequence which is treated specially,
                depending on the second byte (see also -k).
          quit: `esc' followed by this character terminates transparent mode.
         shell: `esc' followed by this character invokes a shell from within
                transparent mode.
                The shell is taken from the environment variable OPT.SHL
                or defaults to simply calling the command interpreter.
                If OPT.SHL is invoked, `tm' is passed as parameter.

                Example: set opt.shl=sh!.bat
                         will call "sh!.bat tm".

                In case quit or shell has the same code as `esc', TM does
                NOT wait for the next key, \0 is used as second `esc'.

     -d: If no device specified, TM behaves exactly as if connected to a
         remote device that simply echoes all received data. This loopback
         is done by software, no physical interface device is involved
         (local mode), the baudrate parameter is ignored, default timeout
         is changed to zero.
         A capital letter (-D), causes TM to transmit stdin first (prior
         to all files and strings on the command line).

     -b: If baud =0, the current baudrate is not changed.
         If baud >0: no parity, 8 data bits, 1 stop bit.
         If baud <0: no parity, 8 data bits, 2 stop bits.
         The handshake lines DTR and RTS are made active by default. If
         baud is followed by a comma separated digit, the levels of these
         lines can be changed:

         digit      RTS          DTR     NOTE: The level of each line may
         ------------------------------        be INVERTED by setting the
           0    NOT active   NOT active        env. variable OPT.INV to a
           1    NOT active       active        corresponding value:
           2        active   NOT active        1 inverts DTR, 2 RTS,
           3        active       active        3 both, 0 none.

         In transparent mode these lines are also controlled by
                  `esc' 13h         (toggle  DTR)       default: <ALT R>
            and   `esc' 32h <digit> (set RTS/DTR)                <ALT M>
         (see also -k).

     -t: TM enters transparent mode by default if no strings or files
         specified (terminal emulator) and uses timeout otherwise after
         transfer.
         -t without argument forces transparent mode in either case.
         If timeout >=0, data received during transfer is written to
         stdout. When transfer done, TM waits for receive data until
         timeout terminates.
         Any data received during this time re-triggers timeout.
         Keyboard data is NOT transmitted during timeout.
         If timeout <0, only string/file transfer is done. TM does NOT
         receive any data and returns immediately after transfer. This
         send-only mode is faster because the receiver is NOT active.

     -l: Check mode, transfer is immediately terminated if something is
         received while string/file transfer is in progress. A message is
         output and exit-code bit3 set.
         If the optional n is zero, transfer is not terminated, but data
         received during transfer is ignored.
         Any other value of n causes loop mode, i.e. transfer is done
         n times, n <0 loops forever.

     -w: See also -c.
         A non-zero wait value with n <0 delays after EOF.
         If wait =0 and n >0, transmission of any file is stopped after n
         bytes (truncation). Replacestrings (see -r) count as one character,
         even if empty.
         Using verify (see -m) simultaneously results in a message if
         truncation occurs, exit-code bit4 is set.
         If wait =0 and n <0, the first n bytes of each file are skipped,
         the remainder is transmitted until EOF.

     -c: For values <0, TM waits until a character is received, the
         absolute value is the wait time limit. This feature can be used
         for synchronisation.
         Using verify (see -m) simultaneously results in a message if a
         transmitted byte is not answered after timing out exit-code bit2 
         is set.

     -s: See also -c.
         If delay =0 and s not empty, all strings on the command line
         beginning with s are taken as a delay value.

         Example: ... -s0,dly ... +dly1000 ... +dly5 ...
                  delays 1s and 5ms instead of transmitting the strings.

         If the delay string is followed by a comma separated digit, the
         handshake lines are set accordingly (see -b) before delay starts.

     -k: More than one key-sequence can be defined using this switch
         repeatedly.
         `esc' is NOT the ESC-key, see -x.

         Example: The DEL-key on your PC-keyboard produces `00h 53h'.
                  Calling TM with "-k\x53\x7f" sends `7fh' (ASCII-DEL)
                  when the DEL-key is pressed.

         If the same sequence is defined more than once, only the first
         will be valid. With -K all previously defined -k switches will
         be ignored.

     -m: Without argument receive-data is also copied to stderr.
         If the optional character is present, this character is put to
         stderr instead of receive-data (\0 and \xff can NOT be used as
         monitor characters, \0 cancels -m, \xff stands for receive-data).

         NOTE: Transmit-data is monitored instead of receive-data in case
               -t with negative argument (send-only mode) or -l without
               argument (or n =0) is used.

         In addition -m accepts three more parameters: [n[,c1[c2]]]
         n:  For each receive-data block of n bytes, the monitor character
             is output once.
             If n <0, the size of the receive-data block is adjusted to
             produce max. -n monitor characters when transmitting the first
             file.
         c1: If c1 (any character except \0) is a valid COM device number,
             the monitor character is put to this device instead of stderr.
             In case of ANY other character, a verify is made (useful with
             synchronisation, see -c). Each transmitted byte is compared
             with the following receive-byte. If they are different a
             message is output, exit-code bit2 is set.
             Two characters have a special meaning in case verify fails:
                b   beep for each verify error
                e   exit at first verify error.
         c2: If c2 (any character except \0) is present, receive-data is
             verified against c2 (\xff verifies ANY receive-byte).

     -p: In packed mode all transmitted files are preceeded by a ^P and
         their name (\0 terminated). The receiver uses this information to
         unpack the files.
         Receiving packed data is like multiple redirection. Anything
         received is written to stdout until the file information is
         detected, which then redirects output to the indicated file.
         (Date and time of the original files is lost!)
         If a filename contains a path, the corresponding directories are
         created if they do not exist.

         There should be a short delay after transmission of each filename
         to give the receiver time to create the file.

         Example: tm -p -s100,\0 -i files...

         NOTE: Any occurrence of ^P in files is replaced by ^P^P to
               maintain decoding capability. Strings and replacestrings
               are transmitted literally!

     -g: Window for stdout (monitor-data only, if -m).
            W  = width
            H  = height
            X  = X-postion  (left upper corner)
            Y  = Y-postion  (left upper corner)

            X/Y >=80/25: center X/Y
            X/Y < 0    : mirror X/Y

         In addition -g accepts three more parameters: [,FG[,BG[,CT]]]
            FG = foreground color    (<0: no change)
            BG = background color    (<0: no change)
            CT = cursortype (1: block, 2: line, 0: off)

            FG AND BG >=0: clear window

         This switch may be used repeatedly. The windows are created during
         switch processing. TM uses the last window (no window with -G) for
         transparent mode.
         To each window TM can write a string which follows spec, separated
         by colon (or semicolon, which ignores C `\-sequences').

     -e: This file is closed when the shell is invoked and reopened (cleared)
         on return.

    EXAMPLES

     -   tm send.dat                        transmits the file "send.dat"
                                            returns when nothing has been
                                            received for 999ms

     -   tm -t0 send.dat                    transmits the file "send.dat"
                                            returns immediately

     -   tm -t send.dat                     transmits the file "send.dat"
                                            enters transparent mode

     -   tm -d2 -b-9600,2                   enters transparent mode
                                            COM2, 9.6kbaud, 2 stop bits
                                            DTR not active, RTS active

     -   tm -t-1 -w1000 +cmd\r + send.dat   transmits the string "cmd" and
                                            a carriage return
                                            delays 1s (empty string)
                                            transmits the file "send.dat"
                                            returns immediately
                                            receive-data is ignored
                                            (send-only mode)

     -   tm -l0 -c-10 "+s1 s2" >rec.dat     transmits the string "s1 s2"
                                            including space (data received
                                            during transfer is ignored)
                                            data received after transfer
                                            is captured to "rec.dat"
                                            `-c-10' waits max. 10ms after
                                            each string-byte for echo to
                                            synchronize capturing with the
                                            end of string transmission
                                            returns after default timeout

     -   tm -s1000,abc send.dat             transmits the file "send.dat"
                                            with a 1s delay after every
                                            `a', `b' and `c'

     -   tm -s0,dl +dl-1000 +s1 +dl10 +s2   waits max. 1s for receive-byte
                                            transmits the string "s1"
                                            delays 10ms
                                            transmits the string "s2"

     -   set tm.opt=-d3 -b38400             all subsequent calls of TM
                                            will use COM3 with 38.4kbaud
                                            (see man util)

     -   tm -+iini.dat ...                  uses "ini.dat" instead of the
                                            default argument file TM.OPT
                                            (see man util)

     -   tm -c1000 send.dat                 transmits the file "send.dat"
                                            with 1s delay after every byte

     -   tm -c1000 -i +cmd send.dat         transmits the string "cmd"
                                            with 1s delay after every byte
                                            transmits the file "send.dat"
                                            without delays

     -   tm -fabc send.dat                  transmits the file "send.dat"
                                            skips every `a', `b' and `c'

     -   tm -r\n\r\n send.dat               transmits the file "send.dat"
                                            replaces every \n with \r\n

     -   tm -m send.dat >rec.dat            transmits the file "send.dat"
                                            receive-data is captured to
                                            to "rec.dat"
                                            receive-data is also monitored
                                            on stderr (screen)

     -   tm -m*1024 send.dat >nul           transmits the file "send.dat"
                                            receive-data not relevant
                                            for each receive-data block of
                                            1Kbyte `*' is put to stderr

     -   tm -m*1024,e -c-10 send.dat >nul   same as above, but with verify
                                            each transmitted byte must be
                                            echoed within 10ms, otherwise
                                            TM terminates due to verify
                                            failure

     -   tm -g10x10+80+25,4,1               receive-data shows red on blue
                                            in a centered window of 10 x 10
                                            characters size
