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.


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.


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:
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):

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,
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:
or by using the letters "N" and "E" to specify the separate parts:

You can mask off part of the CBUS packet, so any values in the masked part will still match, using the "M" format letter.
"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":
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.


(To be written, but 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)


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


MERG menu

The MERG menu contains 5 tools: