multi SERial-MONitor - Dave Dunfield - Apr 04 2010

Use: SERMON options... [@file]

opts:   C=<1-4|address>[:<speed>[<parity><data-bits><stop-bits>[!]]]
        L=file          - Log to file   (use 'L=' (blank) to skip)
        N=string        - set Name      (use 'N=' (blank) to skip)
        Sx=string       - preset Send string (x=0-9, A-Z)
        Wx=bf           - set Window color   (x=1-4, 'Z'oom or 'S'tatus)
        /F              - start logs Fresh   (otherwise append)

COM port may be specified as 1-4 or hex address (5-FFFF), and may have
optional data format. <parity> is 'N'one 'E'ven 'O'dd 'M'ark or 'S'pace:
   C=1                  - COM1 [9600  NoParity   8-Data 1-Stop]
   C=2:57600            - COM2 [57600 NoParity   8-Data 1-Stop]
   C=2F8:38400E71       - COM2 [38400 EvenParity 7-Data 1-Stop]
   C=3C0:19200N82!      - 03C0 [19200 NoParity   8-Data 2-Stop NoFiFo]

Up to four sets of C= L= and N= may be specified to monitor/log up to
four serial devices.

Options can be placed in a file (one per line) and invoked with '@file'
If SERMON.OPT exists in launch or home directory, it will be invoked if
no options are specified on the command line.


-------------------------------- USAGE NOTES --------------------------------

SERMON is a program which can monitor and log received data from up to four
COM (serial) devices at the same time. It functions as a basic TTY (no cursor
positioning or special control codes) - It was designed specifically to record
and interact with "dumb serial consoles" of equipment under test.

SERMON displays the data from all serial devices simultaniously in separate
"windows" on the screen - Data entered at the keyboard is sent to the "active"
device, which is indicated by the label at the bottom of the screen and the
presence of a cursor in the display window. The "active" device can be switched
to any of the monitored serial devices with a single keypress (F1-F4).

The "active" window can be "zoomed" with a single keypress (F5) - when zoomed
the window displays a full 24 lines, while the others are hidden. Data will
continue to be read and recorded for all devices, and displayed when the
window is "unzoomed" (press F5 again, or select another device).

The "zoom" window can be scrolled back and forth up to 255 lines by pressing
the Up/Down arrow keys. To return to the real-time display, press HOME or END.

If a device is logging to a file (L= command line option), you may press F8
to toggle recording to the log OFF and ON. When not zoomed, logging for all
devices is toggled. When zoomed, only the active device is toggled. When F8
is pressed while zoomed to a device that does not already have a logfile,
you will be prompted to enter a filename to begin logging. To cancel without
entering a filename, press ESC.

The 'Sx=' command line option (x=0-9 or A-Z) may be used to preset up to 36
strings which can be sent to the active device with two keystrokes.
Use '^y' to represent control-y (eg: ^M = RETURN), '^=' to send '^'.
To send a preset string, simply press INSERT followed by x (0-9 or A-Z).

The 'Wx=' command line option (x=0-4, Z or S) can be used to set the color
displayed for the corresponding window (capture window 1-4, Zoom or Status).
A two-digit hex value must be provided, which gives the video attributes for
the window. Use the enclosed VIDEO.COM utility to see the colors generated by
various attribute values.

When entering a number (COM address, Window attribute, Baudrate etc.) the
number base can be overridden with the following prefixes:
     % = 2  Binary
     @ = 8  Octal
     & = 10 Decimal
     $ = 16 Hexidecimal
If no prefix is given, COM addresses and window attributes are expected in
hexidecimal, and baudrates are expected in decimal.

Command line options can be read from a file using the syntax: @filename
Arguments in the file must occur one per line. Blank lines, and lines
beginning with ';' (comments) are ignored.

If SERMON is not given ANY commnd line arguments, it will look for a file
called SERMON.OPT, first in the current directory, and then in the directory
where the SERMON.COM program resides - if this file is found it is processed
as command line arguments.

To exit SERMON and return to the DOS prompt, press Ctrl-END or CTRL-HOME.


------------------------------ TECHNICAL NOTES -----------------------------

SERMON should be run under vanilla DOS, as it is real-time intensive and
interacts directly with the system timer and interrupt controller. TSR's
and other "extensions" should be avoided as these may interfere with SERMON
(I use SERMON on a stand-alone system reserved for logging serial consoles).

The standard PC hardware does not support the use of interrupts on all four
COM ports at the same time - and interrupts from non-standard ports can be
difficult to configure. SERMON resolves these issues by not using any COM
interrupts.

"Normal" software polling will lose data at higher baud rates when the system
is busy writing files or scrolling the screen - SERMON works by reprogramming
the system timer to run at a suitably high rate and polling all devices in
the timer interrupt handler. At higher baud rates (38400-115200) the rate at
which the timer runs is quite high, and may cause trouble on slower systems.
I've run it at 115200 on a 486 with no problems, but "your mileage may vary".

To help mitigate the chances of data loss in the event that something on
your system disables interrupts for an extended period of time (at 115200
bps the time between N71 characters is only 78 microseconds) - SERMON
attempts to enable the FiFo buffers on 16550 devices (most modern PC COM
ports are 16550 or compatible devices) - if this causes trouble with your
COM ports, you can prevent SERMON from writing the FiFo control register
by appending '!' to the device data format (C= option).

SERMON has a 64k buffer for each COM port which are filled by the timer
interrupt, and then polled and displayed/logged by the higher application.
At the bottom right-hand corner of the screen SERMON displays the largest
number of characters it has ever seen in a buffer between polls by the
application - if this number keeps increasing and approaches 60000, then
your system is not fast enough to continuously log the serial data that
it is receiving.

SERMON uses 64k of memory for the program, + 64k of memory for each COM
port ... worst case memory usage is 320k (4 ports active).


Dunfield Development Services (DDS) offers software and firmware
development services specializing in systems and embedded applications.
For more information, visit: http://www.dunfield.com
