Hardware Support: MERG CBUS

The support for MERG is rapidly evolving; the actual code might be ahead or behind the documentation on any given day.

Connecting

CBUS Naming

JMRI provides support for general JMRI Sensors, Turnouts and Lights in terms of CBUS "events".

The system letter for MERG CBUS connections is "M".

Details of CBUS Event and object names are described below, with technical details on a separate page.

JMRI associates CBUS events with individual JMRI objects (Sensors, Turnouts, Lights, etc.) via the JMRI System Names. A System Name like "MS+123;-345" defines a Sensor that follows the "123 ON" and "345 OFF" CBUS events to change state. Depending on which CBUS event-IDs are used on a particular layout, these system names can get very long, in which case the "user names" become much more useful.

Adding an item to the table

When you add an item to one of the tables, many times you only have to fill in the numbers to have JMRI construct the complete system name.
Here's a summary, split up for outputs (eg. Turnouts) and inputs (eg. Sensors):

In/Out Entry Meaning makes System Name Mask Equivalent Minimum Maximum
in 200018M07 listen to Events 18 .. 1F MS200018M07 + M + hex mask N/A
in X91012;X91019 hex CAN frame msg. Active; Inactive MTX91012;X91019 hex ; hex N/A
both 18 event 18 On; 18 Off MT18 integer +18;-18
both 18;21 event 18 On; 21 On MT18;21 integer ; integer +18;+21
both +18;-21 event 18 On; 21 Off MT+18;-21 idem signed N/A
both 2000018 Node 2 Event 18; On Event = Active; Off Event = Inactive MT200018 node + (5 digits) N2E18 Note: not working
both N2E18 Node 2 Event 18; On Event = Active; Off Event = Inactive MTN2E18 N + number + E + number 2000018 Note: not working

Sensors

CBUS messages coming into JMRI applications can be accessed via JMRI Sensor objects. The Sensor's System Name determines which CBUS message(s) it corresponds to. A Sensor is defined by two events: The one that sets it ACTIVE, and the one that sets it INACTIVE. If these are mapped to ON and OFF frames with the same event ID number, respectively, only the event ID number need be specified:
MS18
The number is decimal.

To increase versatility, it's possible to use different event ID numbers for the ACTIVE transition (by default, an ON frame) and INACTIVE transition (by default, an OFF frame):
MS18;21

The ON and OFF coding of CBUS is not entirely consistent with the event model, and it may be useful to connect the ACTIVE or INACTIVE transition of a JMRI Sensor to an OFF or ON CBUS frame respectively. Leading "+" and "-" characters can do this. For example,
MS-18;+21
defines a sensor that goes ACTIVE when an OFF frame with ID number 18 is received, and goes INACTIVE when an ON frame with ID number 21 is received.

CBUS event numbers (usually) contain a node number in their most-significant bytes. You can specify the node number either by using a full 5 decimal digits for the event number itself, preceded by the node number:
MS200018
or by using the letters "N" and "E" to specify the separate parts:
MSN2E18

You can mask off part of the CBUS packet, so any values in the masked part will still match, using the "M" format letter.
MS200018M07
"M" indicates the start of a hexadecimal mask that will be applied, where 1 bits in the mask will be zero bits in the resulting value. In the example above, "18" through "1F" will match. This is particularly useful for matching e.g. CBUS short events, where parts of the packet include the node number which should (usually) be ignored.

Finally, it's possible to connect a Sensor to arbitrary CAN frames by specifying their data content as a hex string, indicated by "X":
MSX9100000000000012;X9100000000000019
This allows the Sensor to disregard any intrinsic meaning to "ON" and "OFF" events, and allows it to respond to any frame on the layout.

Automatic Creation

JMRI automatically attempts to create Sensor objects from the traffic that it hears on the CBUS. When JMRI hears an ON or OFF event on the CBUS, it creates a Sensor using the corresponding event ID. This automatically-created sensor defaults to the ON event setting the Sensor ACTIVE and the OFF event setting INACTIVE.

Because events are not intrinsically associated with specific hardware objects, and because people can use event IDs in many ways, this doesn't do what's desired. When it doesn't, you can manually create the proper Sensors using the Add... button on the Sensor Table.

Note that there's a CBUS Event Capture Tool that can help you create Turnouts and Sensor names without having to directly work out the System Names.

Turnouts

(To be written; the scheme is similar to Sensors above, except JMRI is emitting the CBUS frames instead of receiving them, and the type letter is "T" instead of "S", e.g. MT-18;+21)

Lights

(To be written; the scheme is similar to Turnouts above, except the type letter is "L" instead of "T", e.g. ML-18;+21)

JMRI MERG CBUS Tools

MERG menu

The MERG menu contains 5 tools:

Documentation

JMRI Help

Third Party/Support