Skip to main content

JMRI: Reporters Documentation

What is a Reporter?

A Reporter is JMRI's way of representing information reported back from the layout.

A Reporter can contain arbitrary text, unlike a Sensor which is only ACTIVE or INACTIVE. Each Reporter is associated with a specific source of information on the layout and makes that device's information available to the rest of JMRI.

Reporters are created automatically in certain cases, such as when an RFID Reader sees a tag referencing a specific reader for the first time. For all other uses, they must be created manually by updating the Reporter Table or via a script.

Reporters are populated automatically as noted below or manually by updating the Reporter Table, using a LogixNG or via a script.

The Reporter Table

The Reporter Table provides easy access to the contents of all Reporters that JMRI knows about. JMRI automatically creates Reporter objects for certain connection types (currently LocoNet transponders and RFID readers). There is also an "Add..." button for creating your own Reporters, either "internal" or for any MQTT connections.

Creating and Updating Reporters

Reporters can be created manually by direct entry or via script into the Reporter Table. For some hardware reporters, Reporters are automatically created in the Reporter Table. Current Report is populated and cleared by some implementations (including being cleared when the same reported object appears in another Reporter). For example, for an RFID Reporter, if an ID tag is seen at second reporter, it will be removed from the first reporter. For other types of Reporters (e.g. Internal REporters), this must be done manually or via a script.

Last Report is always set equal to the Current Report and is only changed by a new (non-blank) Current Report. This is to handle the situation where a report may not be able to sent a timely report but it is useful to know the last report received. [Advanced: See the Java documentation

The following table provides details for implementations as of JMRI Release 5.3.7 [Asterisk (*) indicates additional information below the table. Number sign (#) indicates information that had not been verified when this page was updated.] [Advanced Reference Info: Code Source is the java program defining this type of Reporter. See this diagram. ]

Source When Reporter Created Current Report Populated Current Report Cleared Add'l Table Code Source
Cbus When Cbus message with new ReporterID received With IDTag UserName or IDTag; Sensor (if associated) set Active #Cleared when object appears in another Reporter IDTag Table CbusReporter extends AbstractRailComReporter
DCC4PC # With RailCom packet information When empty RailCom packet received RailCom Table Dcc4PcReporter extends AbstractRailComReporter
Digitrax Transponding* On receiving Block Entry with new ReporterID From Block Entry message On Block Exit message # LnReporter extends AbstractIdTagReporter
ECOS # # # # EcosReporter extends AbstractReporter
Internal Manually or via script Manually or via script Manually or via script IDTag Table must be updated manually or via script TrackReporter extends AbstractReporter
JMRI Client # # # # JMRIClientReporter extends AbstractReporter
Lissy Detectors # # # # LnReporter extends AbstractIdTagReporter
MQTT Manually or via script On receipt of IDTag, with IDTag and additional message contents Cleared by a blank message or when object appears in another Reporter IDTag Table entried created and updated MqttReporter extends AbstractIDTagReporter
OpenLCB/LCC* Manually or via script On Event Report in the range specified by the Reporter SystemName # RailCom Table entries created and updated OlcbReporter extends AbstractIdTagReporter
RFID Connection* When IDTag message with new Reporter ID received [Also create Sensor] With IDTag UserName or IDTag; Sensor set Active Current Report (and Sensor) automaticly cleared after 2 seconds IDTag Table, Sensor Table entried created and updated RfidReporter extends AbstractIdTagReporter
RPS # # # # RpsReporter extends AbstractReporter
Z21 (Roco) # # # # Z21Reporter, Z21CanReporter extend AbstractRailComReporter

Additional information:

  • Digitrax Transponding: If you are using LocoNet (Digitrax) transponding, the Reporter will automatically be populated with information from Digitrax BDL168 cards with RX4 transponding sensors. When the BDL168 reports that a decoder has been seen in a transponding block or is no longer visible in the block, the corresponding Reporter will display messages like "1234 enter" and "1234 exits".
  • OpenLCB/LCC: Any Event Report message falling into the range specified by the System Name will update the reporter. This will specify a DCC address and an orientation, or that the locomotive left. When the OpenLCB reporter is updated, JMRI will automatically create a Tag with the given DCC address in the RailCom table if there isn't one. The Tag will show its last seen location as the given Reporter. Caveat: it is not possible to differentiate long and short DCC addresses in the Tag entries, so 3L and 3S will be showing the same Tag.
  • RFID Connection: If you are using RFID readers and have set up an RFID Connection, JMRI will automatically create and update Reporters corresponding to the name of the reader and the UID of the RFID tag seen by the named reader. The Reporter will automatically clear the "Current Report" field after 2 seconds.
  • [Advanced} AbstractRailComReporter extends AbstractIdTagReporter which extends AbstractReporter

Displaying Reporter Values on Panels

Reporter contents can be displayed on panels using several different mechanisms:

Display on a Panel using Panel Editor

reporter values

A Reporter's value can be displayed on a Control Panel via an icon. To do this:

  • On the Panel Editor window for your Panel, find the "Add Reporter" button.
  • In the text box next to that button, type the user name or System Name of the desired Reporter.
  • Click the "Add to Panel" button. The Reporter icon will be placed on your Panel. If it's not visible, that might be because the value is currently blank; use the Reporter Table to change the value to something that will be visible.
  • You can drag the icon to where you want it in the usual way.
  • The pop-up menu on the icon will let you change the formatting.

Display on a Layout Panel as a Block Value

Reporters can be associated with layout blocks. When the current report of the Reporter changes, that value will be put into (or removed from) the block value. Block values can be displayed using the Layout Panel Editor.

Display Memory Variables containing Reporter contents

Using LogixNG's Reporter action , Reporter contents from fields Current Report, Last Report, and State can be copied to a memory variable or a LogixNG local variable. Memory variables can then be display on any type of Panels using the appropriate panel editor.

Saving Reporters in Layout Configuration

Reporters are kept in your layout configuration, along with Turnouts, Sensors, Signal Heads, control panel setup etc. "Report" and "Last Report" field contents are not stored. See Loading and Storing Your Work.