EthernetTTY - Dave Dunfield - Jun 05 2013

use: ETTY [options]

opts:   /C      = accept Connect requests
        /V      = disable Vt100 control codes
        A=[mac] = Auto-connect to server (blank=first seen)     [none]
        I=n     = Identify poll interval        (milliseconds)  [1000]
        P=xx    = specify packet Interrupt                      [60-80]
        R=n     = Retransmit timeout            (milliseconds)  [500]
        T=xxxx  = specify packet Type                           [DD00]

EthernetTTY (ETTY) is a simple terminal emulator that operates over an
ethernet packet link using a very simple direct packet protocol. This allows
the use of a "system console" on devices which do not have serial port, and
do not support a TCP/IP stack as would be required for TELNET, SSH etc.

Using ETTY is very straightforward - when run, ETTY polls the network for
ETTY "servers" providing packet based terminal emulation, and presents a
list of the ethenet mac addresses of each server - simply select the one
you want, and ETTY will connect you to a virtual serial console of the
device. (** ETTY supports up to four simultanious servers on the network).

Once you are connected, you may interact with the device as you would via
a serial terminal. ETTY provides the following special function keys:

F1 = Sends <ESC>OP  \
F2 = Sends <ESC>OQ   >  VT100 function
F3 = Sends <ESC>OR   >  keys 1-4
F4 = Sends <ESC>OS  /


F5 = Enters "review" mode where you can scroll back up to 815 lines to
     see data which has previously scrolled off the screen. ETTY will
     continue to buffer data from all devices while you are reviewing,
     and will present it to you when you exit review mode.

F6 = Toggles line-wrap On/Off.

F7 = Toggles auto-scroll On/Off

F8 = Captures data to a file.
      "Capture buffered & live data"
         Writes data stored in the review buffer to the file, and continues
         to record data received from the device into the file until you
         explicitly close the file.
      "Capture buffered data only"
         Writes data stored in the review buffer to the file, then closes
         the file (saves up to 815 lines previously received).
      "Capture live data only"
         Does NOT save the review buffer data, begins recording data
         received from the device until you explictly close the file.
      "Close capture file"
         Closes an active "live data" capture.
 Notes: - ETTY maintains a separate capture file for each device.
        - Data from the review buffer will appear in the file as it was
          recorded in the buffer (ie: final screen layout).
          Live data is recorded byte-by-byte exactly is it is received
          from the device.

F9 = Returns to the device selection list, allowing you to make a connection
     to another device. ETTY supports up to four simultanious connections,
     allowing you to switch back and forth between them with ease. Data
     received from a particular device while you are connected to a different
     device is buffered by ETTY and presented with you switch back to the
     device. NOTE: ETTY can buffer 815 lines for each device.

F10 = Terminates ETTY.


ETTY Command line options:
--------------------------
/C
  Causes ETTY to identify itself as an available device and accept
  connection requests. NOTE: This is usually NOT desirable, as an
  incomming connection request will automatically switch ETTYs focus
  to the connecting device. It is mainly useful as a debug aid.

/V
  ETTY accepts a small subset of VT100 control codes. This option
  disables them (See listing at end).

A=[mac]
  Autoconnect, this option causes ETTY to automatically establish a
  connection to the device with the specified MAC address. If no mac
  is specified, connection is to the first device ETTY detects.
  NOTE: If ETTY.DAT name file exists (see below), you can also specify
        'mac' using a name defined in the file.

I=n
  Specifies the Identify polling interval (milliseconds) - this is how
  often ETTY sends a broadcast soliciting new devices to identify. The
  lower this number, the faster ETTY will detect devices, however more
  broadcast data will be generated on your network. The default is one
  second.

P=xx
  Specifies the DOS interrupt used for the packet driver. By default ETTY
  will scan the interrupt range 60-80 looking for a packet driver.

R=n
  Specifies how long ETTY will wait for an acknowlegment to a transmitted
  packet (milliseconds). The lower this number the more responsive ETTY
  will be when a network error occurs, however too low a value may result
  in unnecessary retransmissions and extra traffic on your network.

T=xxxx
  Specifies the network packet type used by ETTY - must match the packet
  type used by the clients. The default is DD00.


ETTY Name File:
---------------
If the file ETTY.DAT exists in the directory containing ETTY.COM, then it
will be read as a list of up to 50 MAC->Name translation records, The
format of the file is:
   xxxxxxxxxxxx name
   ... repeat up to 50 total records ...
where 'xxxxxxxxxxx' is the 12-hex-digit MAC address, and 'name' is a name
to display (max 12 characters).
NOTE1: Lines in ETTY.DAT begining with '$' serve to preset arguments.
 ++ If you use 'A=name' make sure 'name' is defined EARLIER in the file.
NOTE2: Lines in ETTY.DAT beginning with ';' are ignored (comments).
eg:  $I=500                      <- Speed up Identify polling
     $T=DD01                     <- use a different packet Type
     $/V                         <- disable Vt100 codes
     000F4D001234 MySys          <- map mac 000F4D001234 to name 'MySys'
     000F4D009876 TestSys        <- map mac 000F4D009876 to name 'TestSys'
     ; This line HAS to go AFTER the definition of 'MySys'
     $A=MySys                    <- Autoconnect to 'MySys'


ETTY Packet Protocol:
---------------------
ETTY's packet protocol is VERY simple, and is designed to be easy to
implement on small target devices without requiring much overhead (code
memory, data memory and processing).

The basic Packet structure looks like:

    To[6]     = Destination MAC address
    From[6]   = Source MAC address
    Type[2]   = Packet type (default os 0xDD00)
    Code[1]   = Control code
    Seq[1]    = Sequence number
    Length[1] = TTY data length
    Data[128] = TTY data

Code 0x00 - Transfer data
  'Seq' is incremented after each successful transmittion (ACK received).
  If ACK not received for 0.25 seconds, retrasmit packet up to 10 times
  before reporting failure.
  'Seq' is incremented once the ACK is received, however the receiver only
  cares that 'Seq' is different from the last one received. This indicates
  that the ACK has been received, and the packet contains new data.
  If 'Seq' is the same as the last packet received, then the ACK was lost,
  the receiver should ignore the packet, but resend the ACK.

Code 0x01 - Transfer data acknowlege
  'Seq' indicates the sequence number of the packet being acknowleged.
  Transmitter should NOT send a new data packet (new 'Seq') until any
  outstanding packet has been acknowleged.

Code 0x02 - Connect request
  'Seq' and 'Length' are ignored.
  'Text' contains the ETTY signature:
         0xAA, 0x55, 0x33, 0xCC, "$EthernetTTY", 0
  Far-end should respond with 'Connection Grant', if not re-transmit and
  retry as per a data packet.
  Receiver should record mac address for remote end and respond with:

Code 0x03 - Connection Grant
  'Seq' and 'Length' are ignored.
  'Text' contains the ETTY signature (see above).
  NOTE: Once connected, device should NOT respond to "Identify" broadcasts.

Code 0x04 - Disconnect Request
  'Seq' and 'Length' are ignored.
  'Text' contains the ETTY signature (see above).
  Handshake is the same as "Connection Grant"
  NOTE: Once disconnected, device SHOULD respond to "Identify" broadcasts.

Code 0x05 - Disconnect Grant
  'Seq' and 'Length' are ignored.
  'Text' contains the ETTY signature (see above).
  Handshake is the same as "Connection Grant"
  NOTE: Once disconnected, device SHOULD respond to "Identify" broadcasts.

code 0x06 - Identify
  'Seq' and 'Length' are ignored.
  'Text' contains the ETTY signature (see above).
  This is the ONLY message which is transmitted as an ethernet broadcast.
  All other packets should be unicast to the intended mac.
  Devices which are available to accept a connection (not connected to
  another device) should respond (unicast) with:

code 0x07 - Identify response
  'Seq' and 'Length' are ignored.
  'Text' contains the ETTY signature (see above).

NOTES:
- The "ETTY signature" contained in 'Text' should be checked to insure that
  the packet is actually intended for ETTY (in case there is a packet type
  conflict on your network).
- Once connected, Data should only be accepted from the connected MAC
  address.


ETTY control codes:
-------------------
  0x07 = Sound BELL
  0x08 = Backspace
  0x09 = Tab (stops at 8 character intervals)
  0x0A = Line-feed (scroll at bottom of screen if enabled)
  0x0D = Carriage return (cursor to left margin)
VT100 codes (can be disabled with /V):
  <ESC>[<n>A     = Move cursor Up
  <ESC>[<n>B     = Move cursor Down
  <ESC>[<n>C     = Move cursor Right
  <ESC>[<n>D     = Move cursor Left
  <ESC>[H        = Home cursor
  <ESC>[f        = ""
  <ESC>[<y>;<x>H = Position cursor   <y> = Ascii Row number
  <ESC>[<y>;<x>f = ""                <x> = Ascii Column number
  <ESC>[J        = Clear from cursor to end of line
  <ESC>[0J       = ""
  <ESC>[1J       = Clear from start of line to cursor
  <ESC>[2J       = Clear entire line
  <ESC>[K        = Clear from cursor to end of screen
  <ESC>[0K       = ""
  <ESC>[1K       = Clear from start of screen to cursor
  <ESC>[2K       = Clear entire screen
  <ESC>[m        = Attribute OFF (normal video)
  <ESC>[0m       = ""
  <ESC>[7m       = Inverse video enable
  <ESC>7         = Save cursor position
  <ESC>8         = Restore to previously saved cursor position


ETTY Function keys:
-------------------
   F1     = <ESC>OP
   F2     = <ESC>OQ
   F3     = <ESC>OR
   F4     = <ESC>OS
   Up     = <ESC>[A
   Down   = <ESC>[B
   Right  = <ESC>[C
   Left   = <ESC>[D
