Donate to JMRI.orgJMRI Hardware Support: CBUS® Main Support Page
Introduction
Originally named CBUS by co-founder Gil Fuchs, CBUS is an 'open' protocol for Model Railway use. The protocol and other useful information is hosted on the MERG public website (see further support links). CBUS is not owned or controlled by MERG but the co-founders Gil Fuchs and Mike Bolton are active members. MERG members are able to purchase a range of CBUS kits.
As support for CBUS continues to evolve, these help pages are not a definitive CBUS network guide and contain considerable simplification of the CBUS scheme. They are aimed at helping new users to JMRI or CBUS, not systems developers who should consult the full protocol specification and Developer's Guide hosted by MERG.
Other JMRI CBUS Help Pages
Connecting
For details of how to setup a connection to a CBUS network, you should refer to the JMRI help pages, or other documentation, for your chosen manufacturer's hardware.
Known CBUS hardware solutions (November 2020)
CBUS Tools
CBUS tools are accessed from the menu for your chosen system connection.The example shows a connection to MERG hardware. The available tools may vary with the system connection
- Console - Tool for viewing and sending CAN frames / events.
- Event Table - Monitors events and presents them in a table full of statistics.
- Node Manager - Node Table and node configuration tools
- Command Station Monitor - Loco session monitoring and Command Station Tools.
- Send Frame - Send CAN frames or CBUS events
- Event Capture Tool - Capture CBUS events
- Event Request Monitor - Request Event status monitoring tool
- Network Item simulation - Simulates Cbus Command stations and responds to event requests
- Firmware update - to update CBUS module firmware
- Voltage / Current meters - Monitor track current/voltage
CBUS Events
- Event Name and Numbering
- System Names
- Summary of CBUS Events
- Event Naming Specification
- Sending hex strings
- Opcodes in JMRI
CBUS Event Overview
CBUS events are transmitted as a one-to-many network. Connected modules receive all network messages and choose whether or not to act on them. This enables multiple modules to act on a single event, eg:
- A physical turnout (UK - point) sensor is wired to a CBUS producer module. The module has been taught to send a particular event when the switch is closed.
- This event is received by a relay driver (consumer), which changes the frog polarity.
- The event is also received by an LED module (consumer) which has not been taught the event, so does nothing.
- The event is also received by an LED module (consumer), lighting a LED on a mimic panel.
- The event is also received by JMRI (consumer)
- A JMRI sensor has been created with the event number,
causing the sensor status to change
- A JMRI turnout (point) has its turnout feedback set by this sensor.
- JMRI panel(s) update to reflect the new point position.
- JMRI Signalling Logic recalculates, and on the JMRI panel, a signal protecting the point changes from Red to Green.
- The JMRI Signal Mast mapping is checked and the relevant CBUS event is sent to change that on the layout (producer)
- This event is received by a module which changes a physical on-layout signal (consumer)
- This event is also received by a module which changes a signal on a mimic panel (consumer)
- A train, controlled by (JMRI DispatcherPro for a JMRI Layout Editor Panel) or ( JMRI Warrants for a JMRI Control Panel Editor panel), sees that the signal ahead has cleared and can increase its speed.
- DCC commands are generated from JMRI and sent over CBUS using special events (producer)
- These CBUS events are received by a consumer, e.g. a DCC command station,
which then sends the actual DCC command.
This train had requested the section ahead of it, JMRI Dispactcher/Warrants had allocated it (after checking occupancy and other rules), then sent the turnout event (producer) to change the points.
The event was received by a Servo or solenoid module (consumer) which had triggered correctly, changing the point sensor right at the top of this example. - You can start small and think big, adding more modules as your time and experience allows.
Many people use CBUS and JMRI purely for displaying turnout positions, adding things like track occupancy, on-layout signals, mimic panels etc. at a later date.
If you anticipate adding track occupancy, especially track circuit electrical block (Train On Track Indicators), ideally plan the electrical scheme for this on your layout at any early stage.
CBUS events generally come in two types: "ON" and "OFF".
Events can be short (SLiM) events, eg +11 for event 11 on.
Events can be long (FLiM) events, eg -N2E7 for node 2 event 7 off.
JMRI, being both a consumer and producer of events, can send and receive on any node number and any event.
Adding events to JMRI
CBUS events are stored as
- JMRI Sensors (Inputs)
- JMRI Turnouts (Outputs)
- JMRI Lights (Outputs).
These are accessed via JMRI Tables, ie PanelPro > Tools > Tables > (
Sensors,
Turnouts or
Lights ) .
When the table loads, click on " Add... " button at bottom left to create an item.
For most short events, you just need to enter the number. Here are a few examples :
| Hardware Address | Meaning | Event Consumed as Sensor |
Event Produced as Turnout |
Event Produced as Light turned |
|---|---|---|---|---|
+18 |
Event 18 On
Event 18 Off |
Sets sensor Active Sets sensor Inactive |
Thrown Closed |
On Off |
+18;+21 |
Event 18 On
Event 21 On |
Sets sensor Active Sets sensor Inactive |
Thrown Closed |
On Off |
+18;-21 |
Event 18 On
Event 21 Off |
Sets sensor Active Sets sensor Inactive |
Thrown Closed |
On Off |
+N2E18 |
Node 2 Event 18 On
Node 2 Event 18 Off |
Sets sensor Active Sets sensor Inactive |
Thrown Closed |
On Off |
You will need to enter the Hardware Address in a JMRI recognised format to create the event.
If the create button is grayed out, check your hardware naming format.
Adding a User Name (using any characters) when creating a table item may make accessing it easier in JMRI.
Remember to save your tables!
For more on events, see JMRI system naming with CBUS.
DCC over CBUS
DCC is not a requirement for CBUS or JMRI. Many DC layouts use CBUS + JMRI for route setting, signalling and track occupancy purposes.
For full details of using CBUS in a DCC system you should refer to the JMRI help pages, or other documentation, for your chosen manufacturer's hardware. Some brief details are included below.
JMRI will send and receive CBUS encoded DCC packets over the CBUS network. These and can be monitored with the CBUS console
Loco sessions are best viewed with the CBUS Command Station Monitor, which displays the sessions in a table format.
Throttles
All of the programs within the JMRI suite (including the JMRI WiThrottle server) internally share the same command station slot for a given loco address, so all of JMRI appears to the command station as a single throttle for any single address.
JMRI (via the CBUS Node Manager) can tell if a command station is available which supports the CBUS steal or share features, when throttles are requested which are already in use by something external to JMRI (i.e. a CBUS connected throttle).
When a JMRI application requests a loco (which is already in a CBUS session), JMRI will check the main Throttles Preferences.
If Silent Steal or Silent Share has been selected, this will be the default action.
If neither have been checked and you are using the main JMRI Throttle, you will be asked if you want to Steal, Share, or cancel.
If you are using an automation script and neither option is checked, the system will attempt to acquire a Share on the session.
The command station may disable or enable steal / share at any point, so even if you have a preferred option, an automation script may attempt to use the non-preferred option to obtain the session.
Throttles Stolen from JMRI
When a Throttle session has been stolen / cancelled from outside of JMRI, any open JMRI throttle window for that loco will cease to accept commands, ie throttle slider and function keys greyed out.
If Silent Share is enabled in the Throttle Preferences, and share is available on the Command Station, after a short delay JMRI will attempt to share the throttle.
For most users, silent sharing enables most layouts to operate with minimum of fuss.
If Silent Steal is enabled in the Throttle Preferences, and steal is available on the Command Station, after a short delay JMRI will attempt to steal the throttle back.
Beware of creating Steal loops if more than 1 throttle is capable of auto-stealback! If you find this is happening, disable the Silent Stealing option to stop the loop.
If neither option is enabled, or the steal / share is not possible, a notification will be displayed:
Ticking the checkbox before closing the popup will suppress loco steal notifications for the rest of the JMRI session, for all loco sessions.
Relevant information can be viewed in the main JMRI Console log.
Note that not all JMRI applications currently have a method for dealing with a stolen throttle.
Dispatch / Release
Dispatch is available according to Command Station features.
Note that as dispatch availability for a single loco address may change, this will be reflected by button availability in the main JMRI Throttle.
Consisting
Support for consisting depends on features of the connected hardware.
Although the CBUS protocol supports Advanced Consisting, this has not been implemented within JMRI at present.
JMRI Consisting : Advanced Decoder Consisting (Decoder Assisted Consist) is currently unsupported, hence this is set to Internal in the CBUS preferences.
Primary Address Consists are supported however.
Programming CV's
Subject to support in the connected hardware, a CBUS connection fully supports programming of decoders using DecoderPro and either or both service mode programming on a programming track and operations mode programming on the layout.
Signalling
There are multiple ways to interface JMRI signalling with CBUS modules.
You are strongly advised to let JMRI control your signal logic, however it's also possible to link JMRI with 3rd party signalling over CBUS.
JMRI includes various signalling definitions, a popular choice for UK based layouts being BR2003, however for some layouts LMS 1932 or GWR 1931 may be more appropriate.
Sending JMRI Controlled Signal Logic to your layout
There are multiple ways of sending cbus events from JMRI out to LED or servo signal control modules, this is just one approach.
- Add all aspects to the signal in question to the Turnout Table.
eg. Signal 1 Red :+N256E412(only uses the ON event)
eg. Signal 1 Flashing Precautionary :+N256E416(only uses the ON event)
Signals which can only display 2 aspects (eg a Servo controlling a semaphore signal) can be setup with 1 CBUS event, using the standard ON and OFF event status. - Add a Signal Mast via the Signal Mast Table
- Specify type : Turnout Controlled
- Specify which Turnout output you wish to show to show for each aspect, eg. Signal 1 Red Thrown.
This ensures that only 1 CBUS message is sent for flashing aspects,
specify this flashing in the module board, not JMRI!
Some Signal Mast types send 1 CBUS message for each flash.
A layout with 20 quad aspect signals could send 40 odd cbus events every 0.5seconds, 4,800 events per minute.
This could make network diagnosis awkward, although very unlikely to swamp a CBUS network.
As stated previously, this is just one approach. There are other methods of interfacing JMRI with CBUS signalling systems.
There is initial support for the experimental CabData OPC available in JMRI CabSignals
Receiving Module supplied or existing Signal Logic into JMRI
This is normally done the other way round, however people may have existing systems in place which they do not want to change.
- Create a virtual Signal Mast, named something like SignalMast7
- Create incoming CBUS event(s) as sensor(s), eg "SignalMast7Red".
- For each signal state (eg. Stop or Proceed),
create a new JMRI Logix
in the JMRI Logix Table to set the signal head or mast as appropriate, similar to
If SignalMast7Red is active, set SignalMast7 to Stop - Repeat for each signal state
Further Support
- MERG introduction to CBUS.
- CBUS Wiki hosted on the Model Electronic Ralway Group MERG public website, with full protocol specification.
- https://www.merg.org.uk/merg_resources/cbus-dcc.php The Model Electronic Railway Group MERG-DCC help page.
- MERG kits for CBUS.
- JMRI Users at Groups.io
- For extra logging while debugging, locate and edit the default.lcf file
in the root of the JMRI install, see the pattern at the end of the file.
General CBUS logging - log4j.category.jmri.jmrix.can.cbus=DEBUG
Connection logging - log4j.category.jmri.jmrix.can.adapters.gridconnect=DEBUG
The extra logging will appear in the JMRI console, also the JMRI error logs. - https://github.com/amaurial/mergCanBus CBUS implementation for Arduino. (+ have a look at Amauria's other CBUS Github projects)
- http://www.oscale.net/?q=en/cbus CBUS on an Arduino using CAN BUS shields - See download links at bottom (in English + German)
- https://www.npmjs.com/search?q=keywords:MERG node.js modules to create a CBUS module + Class to create a CBUS module conneted via ethernet.
CBUS is a registered trade mark of Dr Michael Bolton