JMRI: Monitor LocoNet Traffic
Author: Bob Jacobsen
Keywords: JMRI help monitor loconet traffic message packet

# Monitor LocoNet Traffic

The LocoNet Monitor tool displays LocoNet traffic in a human-readable form. The most recent messages are available in a scrolling window. Optionally, you can include the time the message was received, and/or the raw packet bytes. The log information can also be stored in a text file.

## LocoNet Monitor "Controls"

For more information on the various controls and options, please see the Communications Monitor Window page.

## LocoNet Monitor "Raw Data"

When the LocoNet Monitor is configured to include "raw data" in its output, it differentiates between messages sent by JMRI to the interface hardware and those messages coming back from the LocoNet interface hardware. The "Raw data" for those messages which JMRI sends to the LocoNet interface hardware are prefixed with "Tx - ". The "Raw data" for those messages which the LocoNet interface hardware provides to JMRI are prefixed with "Rx - ".

## LocoNet Monitor Timestamps

When Timestamps are enabled, each message is preceeded by the computer time when JMRI sees the message. For a variety of technical reasons, these timestamps cannot reflect the actual time when the message is on the LocoNet data wires.

Because of this, a wide range of odd effects can be seen. Two different messages can be shown with the same timestamp. A transmit message and a receive message can have the same timestamp. And a "Rx" message show up in the display before the "Tx" message is shown.

These behaviors are normal and expected, even though they can be annoying. These behaviors result from a combination of the implementations of JMRI, Java, the computer operating system, the computer hardware and the LocoNet interface hardware. As such, the JMRI implementation has very little control over these odd behaviors, although the JMRI developers have attempted to minimize the influence of these odd behaviors upon JMRI.

## Filtering LocoNet Messages

Users may specify LocoNet "OpCode" values which should be filtered (ignored) by LocoNet Monitor. Filtering messages in LocoNet monitor does not prevent messages from getting to other JMRI components, and does not prevent messages from being sent to the LocoNet interface hardware; filtering only affects the display of LocoNet messages.

The "Filter Bytes:" text entry area on the LocoNet monitor window may be used to specify one or more LocoNet message "OpCode(s)". When the LocoNet monitor is notified of a LocoNet message, the message's OpCode value is compared to the hexadecimal value(s) in the "Filter Bytes:" text entry area. If the message's OpCode value is specified in the text entry area, then the LocoNet monitor will ignore the message.

A LocoNet OpCode value is entered as a two character hexadecimal value, such as "81", "A0" and "E5", without quotes. When multiple OpCode values are to be filtered, provide a space between each value, such as "81 E5 A0" (without quotes).

The filtering mechanism checks only the first byte of the LocoNet message. This means that the filtering mechanism cannot specifically ignore those LocoNet messages which rely on more than the OpCode value to define the specific LocoNet message. This is a known limitation of the message filtering mechanism.

Specific information on many LocoNet OpCode values can be found in documentation provided by Digitrax, while others are not publicly documented. Below is a short list of some OpCode values and the associated LocoNet functionality.

Some LocoNet OpCode values and their functionality
OpCode Value (Hexadecimal) | Functionality
81 | Master (command station) is busy
B0 | Control switch position (without acknowledgment)
B1 | Switch position report
B2 | General sensor state report
B4 | Long acknowledge - sent by command station in response to a large variety of LocoNet messages
B8 | Unlink (de-consist) two slots
B9 | Link (consist) two slots
BC | Request current position of Switch
BD | Control switch position
E7 | Slot data report - locomotive control, programming track, fast clock, etc.
ED | Mobile decoder function control (F9-F28), control of some stationary decoders, etc.
EF | Write slot - locomotive control, programming track, fast clock, etc.

Detailed descriptions of LocoNet message OpCodes are beyond the scope of this document.