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 NamingJMRI 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|
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
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
"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.
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; 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",
JMRI MERG CBUS Tools
The MERG menu contains 5 tools:
- Naming of CBUS inputs and outputs
- Technical details of CBUS Support
- Main CAN Support Help page including links to more tools.