JMRI: CBUS Support

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

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

See also the main help page for JMRI CAN support, including links to various general tools, and the page on the technical details of JMRI's CBUS support.

Naming

The system letter for 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, 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.

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.

Naming

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, preceeded by the node number:
MS200018
or by using the letters "n" and "e" to specify the separate parts:
MSn2e18

Finally, it's possible to connect a Sensor to arbitrary can frames by specifying their data content as a hex string:
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 associate 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.

Turnouts

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

---