JMRI: CBUS SupportThe support on this page is rapidly evolving; the actual code might be ahead or behind the documentation on any given day.
NamingThe system letter for CBUS connections is "M". Details of CBUS event and object names are described below, with technical details on a separate page.
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.
JMRI associates CBUS events with individual
JMRI objects (Sensors, Turnouts, etc) via the
JMRI system names. A system name like
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.
SensorsCBUS 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.
NamingA 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,
preceeded 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 CreationJMRI 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.