Asynchronous Datacommunications Monitor

and protocol analyzer for Digital Modelrailroads


Users Manual for AsynMon and AsynFmt


Version 2.3


Rob Hamerling
Vianen, The Netherlands
E-mail: r.hamerling@hccnet.nl
homepage: http://www.robh.nl/

Copyright © R. Hamerling, 1998, 2003
All Rights Reserved



Table of Contents

Appendix


Overview

AsynMon is a general purpose program to monitor a datacommunications connection using an asynchronous protocol. It has special features to view and analyse the dataflow between the Interface of a digital modelrailroad and a computer with a modelrailroad control program. In addition to the input and output dataflow also the status changes of control signals (such as the CTS signal) are being monitored. All events are recorded with a high resolution time stamp in a trace file. This makes AsynMon suitable to check the timing of data characters and control signals, in particular the working of CTS flow control used by most digital model railroad control systems.
A facility to perform protocol analysis on the command-level is provided with a separate utility.

Acknowledgements go to

AsynMon is Freeware for private users. The aim of this gesture is to collect performance data, communications properties and peculiarities of all digital modelrailroad systems. When you use AsynMon for these purposes you are obliged to report the results of your findings by e-mail to the author.

The use of AsynMon for commercial purposes without explicit permission by the author is prohibited.


Requirements and Wiring

The minimum hardware requirements for AsynMon are:

  1. IBM compatible Personal Computer with at least a 80386 processor. A 386 or better processor is required because AsynMon uses 32-bit arithmatic for some frequently executed calculations. For high volume traffic, like Marklin Digital Packet protocol and Lenz X-bus protocol a much faster processor is recommended (Pentium).
  2. About 350 KB of free memory, of which 256KB for the recording buffer.
  3. Preferrably 2 COM-ports, in some cases 1 will be sufficient.
    AsynMon will function with standard PC COM-ports, COM1 at 03F8/IRQ4, COM2 at 02F8/IRQ3, COM3 at 03E8/IRQ4 and COM4 at 02E8/IRQ3. Ports with a non-standard address or non-standard IRQ can be used, and the selected ports may use the same IRQ! Also newer PCI cards with multiple COM-ports are supported.
    Cards capable of running at higher speeds than 115200 bps are supported too. These cards may use a higher base frequency than legacy COM-ports. This will be detected by AsynMon automatically. The assumed base frequency is doubled with each next attempt, up till 32 times 115200 Hz (3686400 Hz). The maximum speed supported by AsynMon is still 115200 bps.
  4. Free disk space for the trace file, normally a few MB will be sufficient.
    The diskspace requirements of the log file may vary widely, depending on the amount of traffic and number of control signal changes on the link. Each databyte transmitted or received and each recorded change of a control signal requires 8 bytes of disk space. With a high volume of recording activity the writing to disk might become a bottle-neck and the faster disk-access you have the better. A large RAM-disk might be an alternative. Don't record on diskette.
  5. A special tap-cable. For details see Wiring Overview.
  6. MS/PC-DOS version 3.3 or higher.
    Note: ANSI.SYS should not be active (check in Config.Sys).

AsynMon is a DOS-program. Although it will run also in a DOS-session under OS/2 Warp or Windows, the timing will not be as accurate and there is a higher chance of overruns.

Wiring Overview

Below an overview of the connection of the monitoring computer with the digital modelrailroad and the controlling computer.

The logical ports 'Port#1' and 'Port#2' can be any physical COM-port (COM1 to COM4). By default AsynMon assigns COM1 to Port#1 and COM2 to Port#2, but these assignements can modified by the user.

Universal tap-cable

A fully wired cable will be required if you want to use AsynMon for multiple purposes, not only for modelrailroads. But before you start to make any cable, read the Wiring considerations.

When a 25-pins Sub-D connector is required on one of these connections, the following 'translate table' may help:

  signal     9-pins Sub-D     25-pins Sub-D

   DCD           1                 8
   RxD           2                 3
   TxD           3                 2
   DTR           4                20
   GND           5                 7
   DSR           6                 6
   RTS           7                 4
   CTS           8                 5
   RI            9                22

Simple tap-cable (for Digital Modelrailroads)

For most Digital modelrailroads only 3 signal wires will be 'tapped' (some require only 2, like Selectrix), plus ground.

Tap-cable for 2-to-1 adapter

When the 2-to-1 adapter is used, both the transmit and receive leads are monitored by a single COM-port, a variant of the simple tap-cable is required. See the scheme below for the connections of the involved components.

Note: The connections to RTS and RxD provide the 2-to-1 adapter with the necessary positive and negative power.

Wiring considerations

In general the quality of the tap-cable for AsynMon will not be of much importance when the total cable length does not exceed 10 meters, including the cable between controlling computer and Interface. With longer cables you may get signal distortion due to crosstalk or external influences, which will become manifest not only in the observations by AsynMon, but which will also have a negative influence on the communication between controlling computer and modelrailroad. If you have to use longer cables, then it is recommended to use 'twisted pair' cabling: every signal wire twisted with a ground wire.

A more important consideration is the choice between a 'universal' or a 'simple' cable. A universal cable might look preferable, but under certain conditions this may cause problems. Asynmon normally monitors all input leads of each COM-port, even the unconnected ones (it doesn't know which is wired and which not). When a wire is connected to one of the monitored leads, but is 'open' on the other end, false signals may be picked up. Transmitted data may cause pulses on the 'open' control signal wires (crosstalk). AsynMon considers these pulses as control signal activity and will report false modem status signal changes. This may not only lead to wrong interpretation of the communications protocol, it may also disturb the proper working of AsynMon itself, due to the extra interrupts.

Is is recommended to 'tap' only the signals which are really used and omit others.

Special wiring situations

Single datastream

AsynMon is designed to listen to the two-way conversation between 2 parties (point-to-point connection with two datastreams). But of course it can also be used to listen to a single datastream (such as a simplex datastream, a bus or one half of a duplex datastream) and then only one COM-port is required. Examples of these are Märklin/Motorola packet traffic and Lenz X-bus. For example on a system with only a COM1 port, when you want to monitor the Märklin Motorola packetstream, the following commandline would work:

   AsynMon $ nul COM1
This may also be specified the profile.
The tap-cable could be simplified a little more, but this is normally not needed.

Digitrax Loconet

The DigiTrax MS-100 is not suitable to be tapped, its characteristics do not match the RS-232 standard completely. When you connect the tap-cable to the ports of the system running AsynMon then the signal levels drop below the required values. This results in data distortion, not only visible by the AsynMon machine, but also to the machine running the Modelrailroad software!
John Jabour's LocoBuffer can be tapped without these effects.

To simply listen to Loconet activity (not monitoring the traffic between a controlling computer and the Loconet) with an MS-100 works fine, like with LocoBuffer. In this case an ordinary modem-cable (all leads straight over) is required in stead of a tap-cable.
Note: The MS-100 requires DTR=false and RTS=true, which is provided for this purpose by AsynMon when Digitrax Loconet protocol is selected. Since DTR and RTS of the system running AsynMon are not wired through in the tap-cables, setting the voltage of DTR and RTS is not of influence on the datastream being monitored when using AsynMon 'normally' with a tap-cable!

There is no special commandline option or profile parameter for 'listen-only'. Since there is only incoming data, only Port#2 will show activity (Port#1 may be disabled). With the MS-100 the Loconet signal is echoed on the DCD lead. Beware this will be reported as Ring Indicate (RI) activity. Normally you won't need this information, and since it generates several interrupts for each data-byte(!), it may disturb data recording, especially on slower systems. Therefore it is recommended to disable all modem status monitoring for Port#2 by specifying "DTR- RTS- RI-" on the commandline or in the profile file AsynMon.Pro, in which case AsynMon does not enable modem status interrupts of the physical port. Alternately you may not connect (cut) the CD lead of the cable between MS-100 and PC running AsynMon!

Digitrax Loconet with Intellibox

The Loconet attachment of the Intellibox can be used very well to monitor the traffic generated on its P50X interface, as far as loc and turnout commands are concerned. But there are some special effects:

Monitoring Lenz X-bus

AsynMon supports the Lenz X-bus protocol, but it has some special requirements, since:

  1. speed of the X-bus is 62500 bps
  2. a special TTL level connection between PC and LZ100 is used (not RS-232 or RS-485 (X-bus native)!)
  3. traffic volume is very high

    This requires globally the following:

    1. The crystal of a standard COM-port must be replaced by one of higher frequency. AsynMon is not aware of this and handles the COM-port as if it runs at 57600 bps!
    2. The physical interface is hidden to AsynMon! See Appendix B: X-bus connection for instructions how to make the physical connection between the Lenz LZ100 and the COM-port.
    3. To be able to handle the high volume of data on the X-bus, for the computer to run AsynMon a system of the Pentium class is recommended (tests with a 486/66 showed this is about the lower limit).

    AsynMon supports Lenz X-bus protocol as follows:


    Using AsynMon

    This chapter describes how to use AsynMon effectively.

    Installation

    Create a separate directory for AsynMon and unZIP the file ASYMONxy.ZIP archive in this directory. Check the packinglist to see if you have received what you may expect.

    Although AsynMon is strictly a DOS program it may run with some restrictions in a DOS session under OS/2 or W95/98. In these cases the timing information will not be accurate, and it requires at least double the system performance compared to pure DOS.

    When you want to run AsynMon in a DOS session under OS/2 the required DOS session properties are:

    Make sure these are set properly before you start AsynMon.
    I have no idea if there are any requirements or parameters to be able to run AsynMon in a DOS session under W95/98. Maybe somebody will fill in this gap in my knowledge.

    Using AsynMon to monitor high volume traffic ('direct drive', X-bus protocol, etc) in a DOS session of OS/2 or W95/98 will require a pretty fast computer (Pentium).

    Starting

    The commandline syntax is:

    AsynMon Protocol   [Speed]   [Port#1]   [Port#2]   [{MSR-signal[+|-]}]   [@Filespec]

    In which:

    Protocol
    A single letter or digit to initialize the COM-ports according to the properties of the datacommunication between the controlling computer and the modelrailroad. Select a letter from the table of protocols for your digital modelrailroad systems.
    Both ports will use the same settings.
    Speed
    A numeric value of 10 or higher to override the default speed of the selected protocol. Specifying a speed will have the following effects:
    • this speed will override the protocol default
    • even when changing protocol dynamically
    • and applies to both ports
    AsynMon replaces 'odd' speed values with a value supported by regular COM-port hardware (mostly higher, sometimes lower).
    Default: protocol dependent (see Table of supported protocols).
    Port#
    Specification of physical COM-port to be used for corresponding logical port. The first specified COM-port will be used for logical Port#1, the second for Port#2.
    Default: Port#1=COM1, Port#2=COM2.
    Notes:
    • When specified, both ports must be specified, otherwise the second port will not be activated.
    • The string 'nul' may be specified to indicate this logical port will not be used, and you will be using AsynMon to simply listen only to a single port.
    • When the same COM-port is specified for both, only one port will be used and AsynMon assumes that a 2-to-1 adapter is attached to this port.
    • See Non-standard COM-ports for instructions how to specify a non-standard address or non-standard IRQ.
    {MSR-signals[+|-]}
    The monitoring of the modem status signals DTR, RTS, DSR, CTS, DCD and RI may be enabled or disabled by trailing their names with a '+' or '-' character. For example to enable CTS and disable RTS monitoring specify:   CTS+  RTS-
    Default: all signals monitored.
    @Filespec
    Specification of the name of the log file. 'Filespec' should be a valid DOS file specification. When no 'Filespec' string follows the '@'-character no logging will take place.

    Note: When no logfile is specified "AsynMon.Trc" will contain the log. When the file already exists the last characters will be modified into 1 -> 99 until a 'free' name will be found. Ultimately the logfile ending with 99 will be overwritten. When a logfile is specified on the commandline it will always be overwritten if it exists (you are supposed to know what you are doing!). After termination the actually used name will be reported.

    When a profile file is present, protocol, speed, MSR signal monitoring and logical port assignments are taken from the profile, overriding the program defaults. Parameters specified on the commandline will override those of the profile and the defaults.
    If you need a non-default speed, specify speed after protocol, because a protocol specification resets the default speed.

    Builtin Protocol support

    The table below shows the protocols AsynMon recognises and has special support for. This includes at least the speed and character format, but in some cases this may also include features for the online display of data.
    The support of AsynMon is not limited to the protocols in the table. When no line matches with the required COM-port parameters for your purpose, you can still use AsynMon, as follows:

    1. Initialise both COM-ports with the required values, for example with the MODE-command.
    2. Select the parameter '-' when starting AsynMon. This is the signal for AsynMon to respect and use the current settings.
      Even different settings for each of the ports is no problem for AsynMon!

    Protocol
    letter
    Protocol description Default
    speed
    Line
    control
    Modelrailroad systems
    B DigiTrax LocoNet with John Jabour's LocoBuffer 57600 N,8,1
    D DigiTrax LocoNet with DigiTrax MS-100 16457 N,8,1
    E EDiTS 4800 N,8,2
    I Märklin Digital 6023 (TRAIN-ING Set) 19200 N,8,2
    L Lenz Digital Plus (LI-100) 9600 N,8,1
    M Märklin Digital and many other systems
    (default if no protocol specified)
    2400 N,8,2
    T Trix Selectrix 9600 N,8,2
    U Uhlenbrock Intellibox 19200 N,8,2
    X Lenz X-bus (note 5). 57600 S,8,1
    $ Special for the Märklin/Motorola packet stream on the rail
    (note 1 and note 2).
    38400 N,6,1
    Generic (note 3)
    1 Generic 1200 bps 1200 N,8,1
    2 Generic 2400 bps 2400 N,8,1
    3 Generic 4800 bps 4800 N,8,1
    4 Generic 9600 bps 9600 N,8,1
    5 Generic 19200 bps 19200 N,8,1
    6 Generic 28800 bps 28800 N,8,1
    7 Generic 38400 bps 38400 N,8,1
    8 Generic 57600 bps 57600 N,8,1
    9 Generic 115200 bps 115200 N,8,1
    ­ Explicit "no protocol" selection (note 4). (asis) (asis)
    Notes:
    1. When capturing the Marklin/Motorola digital signal AsynMon will have to handle about 3000 characters per second. It will not be useful to display this vast amount of data on the screen. And in combination with this number of interrupts on the COM-port, only fast systems would be able to handle this load without missing interrupts! Without online data display however it will be possible even for modest computers to record the datastream to disk for later 'offline' analysis. Therefore AsynMon will suppress video output when the '$' protocol is selected, but otherwise it works like with any other protocol.
    2. Monitoring the packet stream on the tracks will give framing or parity errors when commands for switches/signals or for the original function decoders are generated with Märklin hardware. Only loc commands can be monitored properly.
      When using 'direct drive' software like Booster of the author of AsynMon, or other software based on the method of Dr. K. Froitzheim, the recording will work without problems.
    3. Although for all generic protocols AsynMon initialises a port to 1 stopbit this will work evenly well when the monitored communication actually uses 2 stopbits.
    4. With the '-' protocol selection AsynMon will not change speed and character format of the COM-ports. This selection may be useful for 'unsupported' protocols, for example with an unlisted combination of character format and speed, or when these are different for each of both COM-ports.
    5. The support of Lenz X-bus protocol requires a special COM-port, which can run at 62500 bps, but is handled by AsynMon as if it is runs at 57600 bps (default).
      AsynMon expects the X-bus data on Port#1. If you use Port#2 by specification of 'nul' for Port#1 polling traffic will not be suppressed and the distinction between master->slave or slave->master data is also lost.
      See the chapter
      Lenz X-bus for more details.

    Other settings may be added on request!

    After AsynMon has been started the protocol may be changed, see Protocol Selection.

    Non-standard COM-ports

    In most situations only the name of the port needs to be specified, in which case the specification is limited to COM1 to COM4. Asynmon obtains the address of each COM-port from BIOS information and will use IRQ4 for COM1 and COM3, and IRQ3 for COM2 and COM4.

    When a non-standard COM-port is used an extended specification should be used:

    (Port,HexAddr,IRQ)
    This should be specified as a single string including the brackets and commas, and no embedded spaces.
    Port
    is specified as normally (like COM1, COM2, etc). In the extended format COM1 to COM8 are allowed, but have merely a symbolic meaning. The port number is used by AsynMon only to determine if the specified COM-portd for Port#1 and Port#2 are the same or different. There is no check on equal address, and the IRQ may be the same (IRQ sharing is supported by AsynMon).
    HexAddr
    specifies the hexadecimal value of the base address of the COM-port. The value must be above 100 (hexadecimal) and a value of up to FFF8 (hexadecimal) is accepted.
    IRQ
    specifies the hardware interrupt (IRQ number) used by this port. Only a value in the range 3..7, and 9..12 is accepted.

    Example: (COM4,FFE8,11) indicates that COM4 on address FFE8h uses IRQ 11.
    Note: Asynmon doesn't check if these specifications correspond to the actually installed hardware, it just tries and may succeed or fail.

    Profile

    All commandline parameters (except log file) are stored in a profile file at termination, and restored when started a next time before interpreting the commandline. The profile is an ASCII file "AsynMon.Pro" in the current working directory. There is no initial profile file delivered with AsynMon, the default is Marklin Interface protocol ('M'), monitor all signals and use COM1 and COM2.

    parameter description
    Protocol-id Single letter or digit: protocol identifier
    MSR
    signals
    Up to 6 abbreviations of the control signals: DTR, DSR, RTS, CTS, DCD and RI. The presence of one or more of the mentioned abbreviations (optionally followed by a '+' character) is the indication for AsynMon to monitor the corresponding signals. A trailing '-' character means that monitoring of that signal should be disabled.
    Ports COM-ports to be used for Asynmon, specified as COM1, COM2, etc. The specification-sequence determines the function of the port. AsynMon interprets the data and control signals on the first logical port, Port#1, as transmitted data and control signals CTS, DSR and DCD. The data and control signals of the second logical port, Port#2, are interpreted as received data and control signals DTR, RTS and RI.
    Speed Interface speed when different than the default speed for the selected protocol. When a speed is specified, it is used for both ports.

    Notes:

    When alternating between different environments (for example sometimes with 2 COM-ports, sometimes with a single COM-port and 2-to-1 adapter), it might be advisable to delete the old profile and copy a 'spare' profile file to AsynMon.Pro.

    Online Data Monitoring

    Below a screen shot of a testrun with a 2-to-1 adapter and an Uhlenbrock Intellibox using P50X binary protocol (P50Xb) as impression of what you may expect to see with AsynMon.

    The top-line shows the actual port settings and the recording time. On the bottom line you'll see which control signals are involved: the actually monitored signals are displayed bright, others dimmed. Also the actual protocol letter and name are shown.
    The captured data is displayed in hexadecimal format on pairs of lines. The upper line of a pair displays the data of Port#1 (transmitted data) in normal video, the lower line the data of Port#2 (received data) in reverse video. For some digital model railroad protocols the first byte of a frame or command is highlighted.
    Two other types of events will be displayed inline with the data:

    All recorded events can be analysed later 'offline' in detail.

    For performance reasons AsynMon writes directly to screen memory, and therefore wil operate only in 80x25 mode. ANSI.SYS should not be active (changed since version 2.3).

    The partial screen capture below is similar, but in this case an Intellibox is controlled from a program using P50X ASCII (P50Xa) protocol. It shows a bad and a good behaviour of a computer(application) with respect to CTS output flow control.

    The Intellibox uses CTS output flow control to stop transmission of data by the computer when its receive buffer becomes full, generally after it has received 4 or 5 bytes. After CTS is turned off the PC should stop transmitting data (one byte may follow).

    On the first pair of lines you can see that a long command was sent to the Intellibox:

      F20, 1, 1, 1, 1, 1, 1, 1, 1
    

    You'll see that the computer continues sending data even during periods that the the Intellibox keeps CTS down. Obviously the sending computer(program) does not handle CTS output flow control correctly.

    On the second pair of lines the IB is reset after the application has changed it flow parameters, followed on the third line by some empty commands (only for alignment!). On the end of the third line-pair, continued on the fourth a new long command was sent to the Intellibox:

      F20, 0, 0, 0, 0, 0, 0, 0, 0
    

    Now the computer(application) behaves correctly: as soon as CTS is dropped by the Intellibox, no more data is sent, and after CTS has become high again, the transmission is resumed.

    Protocol Change

    At startup AsynMon initialises the port(s) to the settings corresponding to the selected protocol (see Table with built-in Protocol selections).
    During monitoring the protocol may be changed by hitting the key corresponding to the desired protocol identifier. At that moment the settings of both ports will be changed and the screen re-initialised. This activity may cause temporary errors being reported in the log due to current line activity, even when the protocol is not changed.
    Unsupported keys are simply ignored.
    Note: When an explicit speed was specified on the commandline this setting will not be changed, regardless protocol selection.

    Suppressing Online Data Display

    For most protocols AsynMon will show the data traffic realtime on the screen. This is not very useful with protocols with a very high traffic volume, like Märklin Packet protocol, and may have a severe negative influence on the performance, possibly resulting in lost events (see also Performance Considerations). For these protocols realtime data display is suppressed by default. Hitting the space bar will switch online data display between 'on' and 'off' (toggle switch).
    Recording of traffic in the trace file is independent of the realtime display.

    Suppressing Control Signal Monitoring

    By default AsynMon monitors and records not only data, but also changes in 'modem' status and control signals (DTR, CTS, etc). With commandline parameters or in the profile this can be selective. Of non-monitored signals the changes are ignored and not recorded (since AsynMon version 2.3).
    Monitoring can also temporary be suppressed with the '!'-key (exclamation mark) for both ports and for all signals simultaneously. In this situation MSR interrupts are disabled, with the effect that control signal activity is not passed to AsynMon, which may improve AsynMon functioning on slower systems with a high traffic volume or a high rate of modem status changes. Consequently also the log will not contain any control signal activity!
    Pressing the '!'-key again re-estabishles the monitoring of the previous set of control signals. The bottom line of the screen shows always the actual monitoring selection, with different colors for 'actively monitored', 'temporarilly not monitored' and 'permanently not monitored'.
    The '!'-key has no effect when during startup of AsynMon monitoring of all modem status signals has been disabled.
    When a 2-to-1 adapter is used, DCD and DSR monitoring will remain enabled, because these are used by AsynMon internally.

    Terminating

    AsynMon is terminated by hitting the 'Esc'-key. The COM-ports are quiesced, the logs closed, the profile written, the screen cleared (except for the top-line) and a termination message is displayed.
    During monitoring Ctrl-Break and Ctrl-C are intercepted and ignored to prevent erroneous termination and not quiescing the COM-ports properly.
    AsynMon may terminate prematurely due to errors. An error message appears, indicating the reason of the problem.

    Statistics

    After termination AsynMon displays some statistical information in the form of interrupt counts. These statistics are mainly meant to check if an excessive number of interrupts have occurred, which may adversely influence the proper working of AsynMon. For example, when there are many MSR-interrupts, other events like incoming data (even on the other port) might have been missed.
    This check is particularly important when you have suppressed monitoring of one MSR signal of a port but not the others, since the formatting utility will not show suppressed interrupts. Without being aware of missed events you might be misleaded by the results.
    See also Suppressing Control Signal Monitoring, Profile for how to suppress control signal monitoring and Appendix A for information which signal is monitored by which Port#.

    Performance Considerations

    Although AsynMon is optimized for performance to be able to monitor and record high volume datastreams, there is always a limit! AsynMon uses hardware interrupts to timestamp events (every incoming byte, every modem signal change and every transmission error), it may have to handle thousands of interrupts per second. Obviously the higher the traffic volume and the more signal changes the faster the system has to be. When the system is not fast enough interrupts may be missed. In most cases this will remain unnoticed, but it will definitely make proper data analysis impossible. Sometimes it will lead to system hang-ups or spontaneous system resets.
    Two relevant question are:

    1. "How do I know if my system is fast enough"?
    2. "How can I improve the performance"?

    In case of system hang-up or system-reset then it is simple, otherwise you have to watch for signals that indicate possible performance problems.

    When you observe one or more of these signals you may consider the following

    Known Bugs and Restrictions


    Data analysis

    The logfile created by AsynMon is in a binary encoded compact format for optimal performance. The formatting utility AsynFmt is provided for detailed analysis of the recorded traffic.

    Remember that the name of the logfile may be changed by AsynMon with start-up when a logfile already exists! At termination of AsynMon the name of the actual logfile is reported.

    Formatting the log

    The log or trace file can be formatted with the utility AsynFmt. AsynFmt requires the name of the binary encoded logfile of AsynMon, and optionally some other parameters. The commandline syntax is:

    AsynFmt   [LogFile]   [FormatFile]   [FrameTraceFile]   [FormatFlag]   [#[TimeCorrection]]

    In which:

    LogFile
    Specification of the AsynMon trace file. When not specified "AsynMon.Trc" is used as the default for the input file specification.
    FormatFile
    Specification of the formatted output file. When not specified the output will be sent to 'stdout' (the screen).
    FrameTraceFile
    Specification of the output file for DigiTrc (frame level trace file). When not specified the default 'AsynFmt.Trc' will be used.
    FormatFlag
    A single letter or digit to modify the behaviour of AsynFmt. Supported flags are:
    Flag Description
    * Force display of polling activity of Lenz X-bus protocol, which is suppressed by default.
    This is only possible when DCD monitoring has not been suppressed with AsynMon.

    #[TimeCorrection]
    Display time in 'absolute' format (hh:mm:ss.tttt) in stead of offset to start of trace.
    TimeCorrection allows correction of time difference between the system time of the computer running AsynMon and the system running the communications program. It must be specified as number of whole seconds between monitored system and AsynMon system. A negative value (a minus preceeding the value) is allowed. For example: specification of #-565 would mean:
    • the output must show the time in hh:mm:ss.tttt format
    • the clock of the system running AsynMon was 9 minutes and 25 seconds ahead of the clock in the traced system.
    Note: The time correction value will be passed to the frame level trace, which means no correction is needed with DigiTrc.

    The internal format of the log records is not documented here yet, maybe later. Since the format of the recorded data may change between versions, AsynFmt accepts only traces of the corresponding version of AsynMon.

    Output format

    Sample Log

    The listing below shows the start of a monitoring session of a Märklin modelrailroad.

                    AsynMon  version 2.3c -  by Rob Hamerling
            Log file 'AsynMon.Trc', recording started on 2001/12/20 at 11:49:07
     ---------------------------------------------------------------------------
          time   | Port#1     xmt  | Port#2     rcv  | Status event details
         (secs)  | status    data  | status    data  |
                 |        |xx c asc|        |xx c asc|
     ------------+--------+--+-+---+--------+--+-+---+--------------------------
          0.0000 | MSR 10 |        |        |        | [init] DCD 0  DSR 0  CTS 1
          0.0000 |        |        | MSR 00 |        | [init] DTR 0  RTS 0  RI 0
          8.3889 |        |        | MSR 33 |        | DTR 1  RTS 1
          8.6740 | MSR 01 |        |        |        | CTS 0
          8.6778 |        |60 `  96|        |        |
          8.9248 | MSR 11 |        |        |        | CTS 1
          8.9551 | MSR 01 |        |        |        | CTS 0
          8.9590 |        |C0 . 192|        |        |
          8.9593 | MSR 11 |        |        |        | CTS 1
          8.9865 | MSR 01 |        |        |        | CTS 0
          8.9902 |        |81 . 129|        |        |
          9.0033 |        |        |        |F0 . 240|
          9.0083 |        |        |        |00 .   0|
          9.0083 | MSR 11 |        |        |        | CTS 1
          9.0177 | MSR 01 |        |        |        | CTS 0
          9.0215 |        |00 .   0|        |        |
          9.0218 | MSR 11 |        |        |        | CTS 1
          9.0223 | MSR 01 |        |        |        | CTS 0
          9.0261 |        |0A .  10|        |        |
          9.0663 | MSR 11 |        |        |        | CTS 1
    

    Every line in the formatted log is the representation of an event (interrupt on any of the COM-ports). This can either be a data byte being sent or received, a change of one or more control signals or the detection of an error situation. After a state change a control signal is displayed as '1' when the signal is currently 'true', or as '0' when 'false'.

    Looking at this sample output of AsynFmt you can see the following sequence of events:

    You'll notice that the Märklin Interface drops CTS immediately at the start of reception of every byte (see Hints and Tips for more details).
    The summary report is not shown here, but straight forward: it contains the count of log records in and out. When possible to determine it shows also some performance information. For example with a Märklin Interface it shows runtime and the totals of the time of CTS=true and CTS=false, giving an impression of how busy the Interface was. Note: 'runtime' is defined as the time between the first time CTS became false and the last time it became true.
    For generic protocols this data is not presented.

    Special effects

    For some situations AsynFmt provides extra help with the analysis of the recorded data:

    Hints and tips

    When looking at the output of AsynFmt you may sometimes be puzzled by what you see. If you are not so familiar with the internals of a COM-port, you might draw wrong conclusions. Here are some Internals to prevent misinterpretation:

    A character is transmitted while CTS just became false.
    With hardware flow control CTS is dropped by the receiver (Interface) before the last acceptable has been transmitted completely. But AsynMon can only show which data byte was involved after it has been transmitted completely. The time AsynMon shows with the data byte is the time the byte arrived in AsynMon, which is the same time it arrived at the Interface too!
    With the Märklin Interface a line with 'drop CTS' can be considered as the beginning and the line with the data byte as the end of the transmission of a byte! The proof is in the time difference: 4.5 msecs at 2400 bps.
    This is an example, other systems may behave differently!
    The output shows sequence errors.
    Some protocols, like DigiTrax Loconet, echo data bit-by bit, so a transmitted character is received almost immediately. Due to interrupt priority of the PC-hardware, databytes may be recorded by AsynMon in the wrong order (the echoed byte may be recorded before the transmitted byte). When you observe such effects, it may help to interchange the plugs of the tap-cable on the site of the PC running AsynMon compared to the normal wiring as depicted in Wiring Considerations. The profile file AsynMon.Pro should reflect this interchange, and may look like:
       D COM2 COM1
    Note: Modem control leads should better not be monitored with Loconet. This will generate lots of interrupts and does not provide useful information in most cases.
    See also Performance Considerations.
    There are no LSR events in the list.
    LSR events will generally mean datacommunications errors. This can either be a problem with the communication between computer and modem or Interface, or a problem with the monitoring of AsynMon itself. Some of the most common causes of excessive LSR events are:
    • The settings of AsynMon do not match those of the communication between PC and modelrailroad, you probably selected the wrong protocol for AsynMon (reported as parity error or framing error).
    • AsynMon cannot handle the heavy traffic load (overrun errors).
    • An error in your tap-cable.
    • Open ends in the wires, causing 'cross-talk'.
    But an LSR event may also appear with a 'break' being transmitted, to reset the communications or with automatic speed detection.

    Frame (Command/Reply) Level Analysis

    For some protocols AsynFmt creates an output file in DigiAPI-trace format in addition to the character / modem-signal level output. This file can be formatted with the DigiTrc utility.

    Data characters are assembled into frames (commands or replies) for the following protocols:

    The frame-level output file is in binary format and can be formatted with DigiTrc1, provided with this AsynMon package. There are some dependencies that have influence on success:

    A possible procedure for this multi-stage analysis may look like:

    1. Run AsynMon as follows:

      AsynMon U
      The first parameter determines P50/P50X(a/b).
      An optional second parameter should be the speed which the application will use (AsynMon defaults to 19200 for 'U').

    2. Run the AsynMon formatting utility as follows:

      AsynFmt AsynMon.Trc AsynMon.Fmt AsynFrm.Trc
      It will pickup AsynMon.Trc as input file.
      Produce a char-level report in the file AsynMon.Fmt.
      Build a frame level binary trace file in AsynFrm.Trc.

    3. Run the DigiTrace formatting utility as follows:

      DigiTrc1 AsynFrm.Trc AsynFrm.Fmt.
      This will pickup AsynFrm.Trc as input file.
      Produce a frame level report in AsynFrm.Fmt.

    Specification of '#' in steps 2 and 3 on the commandline of AsynFmt and DigiTrc1 will give you the time in the format 'hh:mm:ss.ttt'.


    Appendix


    A: Control Signal Information

    Technical background information about COM-ports.

    MSR and LSR

    The meaning of the bits of MSR (Modem Status Register) and LSR (Line Status Register) as used by AsynMon are explained here briefly. For a more general reference you'll have to see the technical information of the family of UARTs commonly used in PCs (8250, 16450, 16550, etc) and/or datacommunications manuals.

    AsynMon monitors both on Port#1 and Port#2 a part of the control signals.

    Modem Status Register

    The Modem Status Register contains information about the behaviour of the control signals. A change in any of 4 control signals results in an Interrupt on the COM-port, which is registered by AsynMon and the contents of the MSR is stored in a log record. The least significant 4 bits indicate which signal-change caused the interrupt, and the most significant 4 bits give the current status of all 4 control signals.

    AsynMon monitors on each port at most 3 control signals, depending on the wiring of the tap-cable. The universal tap-cable has 3 signals wired to Port#1, and the other 3 to Port#2.

    The bits of the MSR are assigned as follows (bits counted from right to left):

    RS232 AsynMon Port#1 AsynMon Port#2
    bit abbrev description use use
    7 DCD Data Carrier Detect Data Carrier Detect Note 1 Ring Indicate
    6 RI Ring Indicate (not used) (not used)
    5 DSR Data Set Ready Data Set Ready Note 2 Data Terminal Ready
    4 CTS Clear to Send Clear to Send Request to Send
    3 deltaDCD change of Data Carrier Detect DCD status change RI status change
    2 trailRI Trailing Edge Ring Indicate (not applicable) (not applicable)
    1 deltaDSR DSR status change DSR status change DTR status change
    0 deltaCTS change of Clear To Send CTS status change RTS status change

    Notes:

    1. In some situations DCD has a different function for AsynMon:
      • With Lenz X-bus monitoring DCD=1 (true) indicates data is flowing from master to slave, and DCD=1 (true) data is flowing from slave to master.
      • When the 2-to-1 adapter is used DCD=0 signals that the captured data is from TxD (transmit), and DCD=1 data is from RxD (receive).
    2. When a 2-to-1 adapter is used DSR should normally be 0. DSR=1 indicates that a simultaneous transmit and receive of data occurred, which means that the datastream is not strictly half duplex and the use of the 2-to-1 adapter gives unreliable results. This situation will be reported by AsynFmt as "TxD<->RxD collision".

    Line Status Register

    The Line Status Register contains information about the status of the transmission process. Its use by AsynMon is limited, because AsynMon is just listening to a communication of others (eavesdropping).
    One exception is the occurrence of a 'break' signal. A break signal is used by some hardware to reset both partners of a (probably failing) communication to a predetermined state.
    The correct functioning of AsynMon is dependent on the setting of its port parameters! If errors occur you'll definitely see it in the data being displayed. Via LSR-events it will also report problems of its own functioning, which will be logged for later analysis.

    bit AsynMon Port#1 and Port#2
    7 (not used)
    6 (not used)
    5 (not used)
    4 Break
    (may also be caused by incorrect speed)
    3 Framing Error
    (incorrect character format or speed)
    2 Parity Error
    (maybe incorrect parity setting)
    1 Overrun Error
    (AsynMon system too slow!)
    0 Data in buffer
    (not explicitly used)


    B: X-bus Physical Connection

    Instructions on how to connect the LZ100 to the COM-port of a PC to monitor X-bus traffic.

    Work carefully, the exercise may damage your LZ100 and your computer if you make the wrong connections: shortcuts or wrong voltage levels! Make or break connections only with all devices powered off!!

    A separate COM-port card is recommended for at least 2 reasons:

    The 1.8432 MHz crystal on the COM-port has to be replaced with a 2.0000 MHz crystal. When a port uses a crystal with a different frequency the new crystal should have a proportional frequency (20000/18432). For example a crystal of 2.2118 MHz should be replaced by one of 2.4000 MHz.
    Desolder the old crystal, solder a suitable socket and insert the new crystal in this socket. Clean the pins of the old crystal for later replacement (in the socket).

    The Lenz LZ100 works internally with TTL level power (5V). The cable will be a direct connection between the TTL-level of the LZ100, and the TTL level on the COM-port (not to the RS232 connector). A 3-wire cable is used to make the following connections:

    The cable should be kept as short as possible (recommended: not longer than 1 meter).

    This text has been checked carefully, and verified by knowledgable people, but may still contain errors!
    The author can not be hold responsible for any damage to modelrailroad or computer equipment.


    C: Single COM-port and half duplex traffic

    "By hook or by crook" it is possible to use AsynMon with a single COM-port and still be able to watch and record both transmit and receive datastreams. To make this work:

    With a '2-to-1' adapter the transmit and receive datastreams are combined to a single datastream and fed to the COM-port RxD input data lead. The direction of the corresponding data is signaled on the DCD lead of the COM-port of the AsynMon computer. When DCD is true, the captured data is of the transmit datastream, when DCD is false, the captured data is of the receive datastream.
    The 2-to-1 adapter contains also a circuit to check if the datastream is really half duplex. Although the detection is not full proof, in most cases it will signal (on DSR) simultaneous transmit and receive activity. This 'collision detection' is not reported by AsynMon on the screen, but only shown in the output of AsynFmt.

    2-to-1 adapter

    The scheme of the adapter is:

    The leftmost pair of NOR gates is switched as set-reset flipflop. Without data traffic both TxD and RxD are negative. A positive pulse - typically a startbit - on TxD or RxD turns over the flipflop to the active side. This flipflop has 2 functions: (1) to derive a signal to indicate which datastream is active, and (2) to control a filter to pass only the active datastream.
    The filter is formed by a second pair of NOR gates. It selects either the TxD or RxD datastream to be passed. A final NOR-gate restores the original polarity of the data signal.
    The flipflop turns over with any data activity on the 'other' side. When the traffic is not strictly half duplex, this could be in the middle of a character! When this happens you may (or may not!) observe distorted characters, framing errors and parity errors.
    The remaining three NOR-gates form a collision detection circuit. When both TxD and RxD are positive (meaning simultaneous data transport) this condition is passed to DSR. This collision warning can occur several times per transmitted character. But it is not full-proof, some collisions may not be detected at all.

    The adapter needs a dual voltage power supply of at least +4.5V and -4.5V. Since a only few milliAmperes are required the power can easily be delivered by the COM-port of the computer running AsynMon, see the schematics below.

    As you can see RTS provides the positive power voltage, and TxD provides the negative power voltage.

    Below a layout of a sample experimental strip-board ('VERO-board') of approximately 6 by 3.5 cm. It includes power supply for the adapter, provided by the COM-port of the computer running AsynMon.

    The component side of the sample adapter then looks like:

    Since both the transmit and receive leads are monitored by a single COM-port, a variant of the simple tap-cable is required. The cable between the 2-to-1 adapter and the computer with AsynMon should be sufficiently wired. A regular modem-cable will do.

    The photograph below gives an impression for a possible housing. This the authors prototype, the components are slightly differently positioned than on the final design.

    To indicate to AsynMon that a single COM-port with 2-to-1 adapter is used the same COM-port must be specified for both logical ports, either on the commandline or in the profile file. This is the signal for AsynMon to:

    The display of data and events by AsynMon will be as if two physical COM-ports were being used.


    D: Summary of Changes

    Overview of history of AsynMon and AsynFmt.

    17 Dec 1998
    Version 1.0, Initial release.
    24 Dec 1998
    Version 1.1
    • documentation extended with graphics and appendices
    • set of selectable protocols made more general purpose
    • data display suppression by AsynMon with protocol '$' (direct drive)
    • automatic adaptation to actual screen size (rows and columns)
    28 Dec 1998
    Version 1.2
    • extended AsynFmt to present data in hexadecimal notation, ASCII value and as character (if ASCII value between 32 and 128)
    • protocol may now be changed while AsynMon is running
    • added a section about wiring to docs
    8 Jan 1999
    Version 1.3
    • control signal monitoring can now be disabled
    • protocol selection now also logged
    • AsynFmt checks log for version of AsynMon: should match
    • cosmetic changes in output of AsynFmt
    15 Jan 1999
    Version 1.4
    • 'break' events visible on screen as 2 special characters
    • DTR and RTS set 'true' while port active
    • monitoring of control signals selectable and selection displayed on bottom line of screen
    • working parameters selectable and remembered in 'profile' file
    • '!'-key respects control signal monitoring selection: toggles MSR interrupts 'off' for all, but 'on' only for actual selection
    • receive buffer increased significantly and writing log records in blocks for improved performance
    31 Jan 1999
    Version 1.5
    • starttime of recording stored in logfile and displayed by AsymFmt
    • DigiTrax header bytes highlighted on screen and in formatted output
    12 Feb 1999
    Version 1.6
    • physical COM-port now mapped to 'logical' Port#1 and Port#2, allowing COM1 to COM4 to be used for either purpose.
    • now also probable 'start_of_packet' highlighted for Marklin/Motorola packet protocol (identifier '$')
    • display distinction between active, temporary inactive and permanently inactive control signals
    • bugfix of incorrect handling of 'DTR' in profile file
    23 Apr 1999
    Version 1.7
    • added support for Lenz X-bus protocol (see Lenz X-bus)
    • Space bar now toggles online display of data on/off
    • Logfile can now be specified by user on the commandline, including the possibility to have no logging to disk at all
    • Output file of AsynFmt can now be specified: redirection of stdout is not needed anymore
    16 July 1999
    Version 1.8
    • For Märklin Packet protocol an extra output file is generated by AsynFmt with the name AsynFmt.Trc. Its format is of a 'DigiScope'-like trace file and its contents will be on Märklin/Motorola packet level. This file can be formatted with DigiTrc (a separately available utility).
    • No more runtime statistics for 'generic' protocols (1..9).
    • Minor changes in time recording (in sync with DigiTrc)
    28 January 2000
    Version 1.9
    • Speed can now be specified on commandline of AsynMon (when deviating from protocol default), for example with Intellibox in P50 mode (protocol 'M') at 19200 bps. The specified speed will be used regardless protocol selection, even with dynamic protocol changes.
    • The commandline of AsynFmt now allows specification of a formatting flag. Currently the only supported use is to force display of polling activity with Lenz X-bus protocol. Support of the 'Y' protocol specification (Lenz X-bus 'raw') has therefore been dropped.
    • Lenz X-bus data splitted by AsynFmt into separate columns for master->slave and slave->master data.
    • More protocols are now converted to 'frame' (packet/command) level, but not for all protocols, see Frame Level Analysis for details. The frame-trace output can be formatted with DigiTrc.
    • Default name of recording file of AsynMon is now AsynMon.Trc.
    23 October 2000
    Version 2.0p
    • Support for a special 2-to-1 adapter to combine transmit and receive leads, to be able to use AsynMon with a single COM-port, provided the datastream is half-duplex. See for details Appendix C (new).
    • Enhancements of online display:
      • Data display consequently: xmt=normal video, rcv=reverse video.
      • Actual state of control signals now permanently displayed on bottomline of AsynMon screen.
      • Letter and name of actual protocol now also on bottomline.
      • Datastream splitting during online display now also for Lenz X-bus: master->slave displayed as transmitted data and slave->master as received data. Inline display of CTS state therefore redundant and removed.
    • Parameter enhancements
      • No more commandline protocol default. When no protocol specified on commandline and no profile present a help text with command syntax will be displayed.
      • 'Odd' speeds rounded to acceptable value for COM-port hardware.
      • Speed now stored in profile and printed in output of AsynFmt when different from protocol default.
      • Added option for display of 'absolute' time by AsynFmt with optional correction of time difference between systems.
      • The frame level outputfile may now be specified on the commandline of AsynFmt.
    • Direction detection with Lenz X-bus protocol moved from CTS to DCD.
    • Bug fix of cross-program date/time handling.
    • Control signal monitoring better documented.
    • Added a sample screen capture of a good and bad CTS flow control behaviour of the computer(application).
    • Changes in DigiTrc for improved support of AsynFmt frame trace.
    7 December 2000
    Version 2.1
    • Setting of DTR and RTS now protocol dependent.
    • The positive power for the 2-to-1 adapter now supplied by RTS (was DTR).
    3 September 2001
    Version 2.2
    • If a LogFile already exists, the extension is modified to prevent the overwrite a previous log.
    • The use of the keyword TWO2ONE in the profile is now obsolete. In stead when the same COM-port is specified for both logical ports it implies the use of the 2-to-1 adapter.
    • One of both logical ports may be specified as 'nul' (=not used).
    • MSR signals for both ports are retained in the profile even when only 1 port is used.
    • MSR signal monitoring enabling or disabling now also possible with commandline parameters, like with profile.
    • Beep added after every 500th Framing Error (as warning when actual speed does not match monitoring speed).
    • Correction of time on screen (was running factor 10 too fast!)
    • Fixed bug in reporting of Ring Indicate activity (AsynFmt).
    • Some optimisation in writing log data to disk.
    • Updated docs for the new or changed features. Also some explanations and examples are enhanced.
    2 May 2003
    Version 2.3m
    • Added support for non-standard COM-port addresses and IRQs. Ports sharing the same IRQ are now supported too!
    • Minimum speed changed to 10 bps (was 1200).
    • Added RS-232 interrupt activity statistics, displayed at end of run.
    • Enhanced timestamping (no more time jumps in output).
    • Removed CTS ('busy') analysis from AsynFmt (limited usefulness)
    • Extended documentation: explanation of working of AsynMon
    • Several performance improvements:
      • Small memory model with compiler, same for some assembler subroutines.
      • Direct screen writes in stead of BIOS services.
        (ANSI.SYS should not be active).
      • Recording to disk now with 'lazy writes' (write only when buffer half full).
      • Not-monitored modem control and status signals not recorded anymore.
      • IN and OUT port I/O delays reduced.
    • Bug fixes:
      • No more writes beyond buffer boundary with buffer wrap around.
      • X-bus traffic display corrected. Problem with Lenz LZ100 dropping TX-enable during stop-bit solved.
      • DCD and DSR permanently monitored with X-bus protocol (not user selectable, not dynamically to be disabled).