Appendix

Introduction

DigiScope is a program to collect, log and interpret realtime the datastreams between a Digital modelrailroad and a controlling computer. Data is presented in 2 ways on the screen:

1. a character and/or hexadecimal representation in a rolling window
2. a formatted pseudo graphical representation in color of the datastream for
   • loc and function decoders
   • switchpoint and signal decoders
   • feedback signals

DigiScope can record the datastream with a timestamp per 'frame' in a file for later formatting. It can also record the raw datastreams (not the demo versions).

Requirements and Preparation

The data is collected from the Transmit and Receive wires of the connection between computer and Digital modelrailroad Interface. Since a COM-port has only 1 receive-data wire, 2 COM-ports are needed to collect both datastreams simultaneously. If you are interested only in one of both datastreams just don't connect the other port.

A schematic of the hardware setup is given in the figure below:

---

Fig 1: Overview of DigiScope

---

COM1 monitors the command's from computer to Interface, COM2 monitors the data from the Interface to the computer (not interchangeable). As you can see, DigiScope does not intercept and retransmit the datastreams, but just copy the data over the transmit and receive wires. Other COM-port signals are not set and ignored. Therefore DigiScope needs not be active while your computer controls the model railroad. It can be started and stopped at any convenient moment, but of course data collection happens only during its active state!

You need a proper 'T'-cable. The connections depend on the type of connectors on your COM-ports. Wiring for both 25-pin and 9-pin RS232 connectors is shown below:

---

Fig 2: Wiring for Märklin Digital

---

Fig 3: Wiring for Lenz Digital Plus

---

If the COM-ports of your PC have different connectors, you must make the proper selection from the left and right part of this picture! The CTS signal is not monitored by DigiScope, so you won't need a wire for that signal to the DigiScope computer, nor any other wire!

The function of each port is fixed. If you connect the COM-ports to the wrong lead, DigiScope will misinterpret the data.

Usage

To start DigiScope simply call it from an OS/2 command prompt.

The following parameters may be specified

1. The first parameter is mandatory, it indicates the protocol being used between computer and modelrailroad:
   • 'D' - DigiTrax Loconet
   • 'L' - Lenz Digital+
   • 'M' - Maerklin Digital
   • 'T' - Trix Selectrix
   • 'U' - Uhlenbrock Intellibox (P50X and P50 protocol)
   DigiScope refuses to run when no valid protocol letter is specified.
2. Optionally you may specify the port speed, which will be used in stead of the system default (for Märklin: 2400, for Lenz and Selectrix: 9600 bps). It must be an acceptable bps-value for the port, and may not exceed 115200 (Warp 4), and will then be used for both ports.
3. Optionally you may also specify 2 COM-port names. The first name is assigned to Port#1, the second to Port#2. This gives you the freedom to use any available port on your system. The defaults are COM1 and COM2.
   Specifying the name "nul" for Port#1 is the signal for DigiScope to ignore Port#1. This allows you to listen to the input datastream only and is especially useful for listening to Loconet with a normal modem cable.
   When you specify the same name twice, DigiScope assumes that a 2-to-1 adapter is used. With this adapter you can listen to 2 datastreams while using a single COM-port, provided the datastream is half-duplex (one of both streams is quiet while the other is active). The 2-to-1 adapter is described in detail in the documentation of the AsynMon package.

For video-performance it is recommended to run DigiScope in an OS/2 full-screen session. The number of lines on the screen (VGA assumed may be changed at any moment with keys F2 through F6 in resp. 25, 34, 43 50 or 60. In a full-screen session the font will change automatically to fit all lines on the screen. In a windowed session, the font will not change automatically, but you may change it with the window properties. Otherwise you may have to use the scrollbar to view hidden parts of the window.

F1 shows some Help information. 'Home' starts a new data collection phase: the screen is cleared, all counters and states are reset to zero and data collection starts as if the program was just started.
DigiScope is terminated with the ESC-key or F12. It may take a second or two before all buffers have been saved on disk!

Presentation

The figure below gives an impression of the screen layout. The left half of the screen is a logging window, the right half a realtime pseudo graphical presentation of the state of the model railroad.

---

Fig 4: Screen capture of realtime animation (Märklin sample)

---

The presentation space contains the following areas:

1. The topline shows the current version of the program.
2. In the left half of the screen is the log. In the picture only a hexadecimal format is shown. Each line has a timestamp in milliseconds of the time the last byte of the unit of transmission (command, feedback data) was received (with an accuracy of about 5 milliseconds).
   LENZ: The number between brackets [xx] is the received checksum byte. If the value is not OK then it will be followed by '??'. A character interpretation may be activated as well, the contents of which is rather obvious and easier readable for the non-programmer. When the window is full, new lines will be written at the top, giving a 'rolling' effect. A separator line shows below the latest received data.
3. The right half of the screen is a pseudo graphical representation of the actual status of model railroad. The status is built up from data collected during the current observation period only. It contains a number of distinctive areas:
   • The left column contains switch information address and position, in which '|' straight and '/' branch. The OFF status of a signal is shown on a black background, the ON position with a red background.
   • The upper-right area contains loc/function decoder information. The middle column gives type and address of the decoder.
     • For loc-decoders a 'speed-bar' shows the last observed speed-command of a loc. Forward movement is displayed to the right, backward to the left, and in a different color.
     • If the function-bit of the loc decoder is ON, the address is shown in reverse video. If speed is zero the current direction setting is shown.
     • The functions F1..F4 are shown in the far right column (digit = ON).
       Märklin: this presentation is also used for the 'old' function decoders
   • The lower area contains feedback information. A 'dot' means an 'OFF' (free) state, a digit an 'ON' state of the corresponding position of the decoder. There are 9 lines reserved for feedback information. If there are more present than can be displayed: no problem the log and trace will contain all data.
     MäRKLIN: At most 18 S88's will be displayed (2 per line). An S88 will be shown only after the first status change, and will be positioned relative to its place in the physical chain.
     LENZ: At most 36 feedback units are displayed (4 per line), and only the active ones. Newly detected feedback encoders area added on the fly, and will be displayed sorted on address. This means that a decoder status may change position when a one with a lower address becomes active!
     Trix: At most 36 feedback units are displayed (4 per line), and only the selected range.
4. The bottom line shows from left to right:
   • Interpresentation flags (see "Operation Keys" below): an UPPERCASE letter means the state of the flag is ON, a lower case letter off (inactive). See Data Selection below for the usage of these flags.
   • Number of bytes from computer to Interface and vice versa and number of 'frames' during this observation interval (start of program or 'clear screen' command).
   • The approximate utilisation of the connection between PC and Interface. The utilisation is expressed in the percentage of the theoretical maximum for a half duplex connection at the actual speed of the COM-ports.
     Märklin: Documented delays (in the Interface booklet) are counted as occupation time (nothing else can take place).
     Lenz: Delays in the conversation between computer and Interface are not considered (since such figures cannot be found in the user documentation of Lenz).
     Trix: Simple utilisation by data is considered (like with Lenz).

Data Selection

The presented data in the logging window may be selected (filtered). Toggling between ON (display) and OFF (suppress) is done with keys:

Note:

Logging data and Trace formatting

By toggling 'L' DigiScope starts or stops logging data to disk. The logfile contains binary data that can be formatted with DIGITRC, available separately. To format a trace enter:

    DIGITRC  DIGISCP.TRC >DIGISCP.FMT

DIGISCP.TRC is the input logfile. DIGISCP.FMT is the output file. If no output file is specified the output goes to the screen.

Note: Records of input and output data streams may not always be in the proper sequence in the tracefile, observe the timestamps!

The demo version of DigiScope writes only a limited number of frames to the trace file.

Recording raw data

When recording raw data each of both datastreams goes to a separate file (DIGICOPE.RW1 for what is received by COM1, and DIGISCPE.RW2 for COM2). Recording is done at the moment a receive buffer is full. When you disable recording (change 'R' flag to 'r'), the current buffer contents are not recorded and lost, and when enabling recording the buffer may contain data from before this enabling time. There is no way to distinguish one piece of data from the other.

The recording files are opened in append-mode. Contents of previous recordings are preserved. You may want to erase old datasets before starting DigiScope to prevent confusion and undesired growth of files!

This facility is just a 'double check' in case you seem to receive many incomplete frames or garbled data. There is not formatting program for this type of file delivered with this package. You'll need a hexadecimal editor to examine the data and a manufacturer's manual for its interpretation.

Internals and usability hints

DigiScope is a 32-bits multithreaded (internally multitasking) application for OS/2 Warp 4.0 or higher. This design ensures that all data is captured, even at high data transfer rates. The data collection threads (one for each COM-port) have minimal function, run at a high priority level and have a large buffer. The received frames are sent with a timestamp via a queue to the display and logging thread, which runs at a lower priority level than the monitoring threads.

With heavy traffic and when using a relatively slow machine for DigiScope you may notice a delay in the actual display of the data. However the timestamps are taken at the moment the data is received in the COM-port buffer and will be close to reality. When the delay becomes very large buffer, one of two conditions may arise:

• Overrun of the receive buffer.
  Currently DigiScope does not signal buffer overrun by itself. It will show on the screen as garbled timestamps and data (on screen and in log). The delay will have to be more than 1 minute before overrun occurs.
• Trace queue overflow (error 334).
  This situation is reported, but DigiScope does not take any action to prevent or to cure this problem. Frames will simply be lost. To prevent these situations reduction of system load may help, for example:
  • Stop or suspend other active programs, especially those in DOS sessions.
  • Run DigiScope in a full screen session rather than a windowed session.
  • Disable parts of the realtime data interpretation of DigiScope by means of the 'Data Selection' flags.
  • Disable realtime display completely but enable 'Logging', and format the trace file afterwards with DIGITRC.

When DigiScope is terminated the data collection threads will be stopped first. The program finishes only after all collected data has been displayed and written to disk if any of the recording facilities were active.

Shareware Registration, etc.

The DEMO version of DigiScope may be used and distributed for free as long as you don't change anything and keep it as a complete self-contained package. There are only slight restrictions in the DEMO versions compared to the full-function version:

The full function version of DigiScope is available to registered users of the DigiAPI package (see below).

Comments and suggestions are welcome!

Enjoy!

Rob Hamerling

E-mail: r.hamerling@planet.nl

APPENDIX

Summary of changes

Other Digital Modelrailroad Software

For much more information about computer controlled (model)railroading, you may have a look at the authors homepage on Internet: http://www.geocities.com/digithalys/

This homepage contains among others: