Hardware Support: Modbus

Hardware
Limitations
Connecting
Tools
Documentation

Modbus is an industrial control system that's usually used with pretty tough, highly-engineering equipment. The Modbus nodes are often "programmable logic controllers" (PLCs) which can do their own calculations of how to control devices.

Supported Hardware

Modules

Modbus Nodes

JMRI provides support for general JMRI Sensors and Turnouts via Modbus (Node) connections.

Limitations

Modbus support is rapidly evolving; the actual code might be ahead or behind the documentation on any given day. Note that Modbus support is not in any JMRI test or production releases yet.

JMRI as Master Node is not supported yet. JMRI will eventually support operation as either the Master Node, or as one of the Slave Nodes.

Connecting

Software settings

A Modbus installation has one Master node, and one or more Slave nodes. Generally, the Master writes to "Coil" objects in the Slave nodes, and reads from "Discrete input" objects in the Slave nodes. The "Coil" terminology comes from relay coil, solenoid coil, etc.; a way to change the node's output signals. The "Discrete input" is a single bit from some external input. By reading and writing these in a Node, a Modbus Master can sense the condition of the layout (through Discrete inputs) and control it (through Coils).

JMRI as Master Node

(There is no code support for this yet)

When JMRI is the Master Node driving a selection of remote Modbus Nodes, the net effect is very similar to the familiar C/MRI system. There's a Master (JMRI) that communicates with input (Sensors) and output (Turnouts, Lights) lines in remote Nodes. Each Modbus Discrete input in a remote Node gets configured as a JMRI Sensor; each Modbus Coil becomes a Turnout or Light.

JMRI can handle multiple remote Nodes once they've been configured in the JMRI Preferences.

There are multiple ways to configure this connection: TCP/IP vs RS485, ASCII vs RTU protocol, etc. Each of these requires separate code.

JMRI as Slave Node

It's also possible for JMRI to be a Slave Node. In that case a PLC or other unit is the Master Node, and reads/writes JMRI when it needs to. At first, this will probably seem odd; JMRI is usually used as the central control for the layout. But note that Modbus is an industrial-strength system, and JMRI is not. If you want really robust railroad controls, you can built it using PLCs communicating with each other for operation, and only communicating with JMRI to display status on a Panel, get operator input, etc.
In that case, it's quite natural for JMRI to appear as a slave node on the Modbus.

When configured as a Slave, JMRI appears as Coils and Discrete inputs to the Modbus Master. Modbus:

allows the Master to read and write Coils in the Slave, but can only read Discrete inputs; it can't write to Discrete inputs in a Slave.
some popular PLC environments can only write to Coils and read from Discrete inputs.

The Master Node can read from either the Coil or Discrete input for either Turnout or Sensor (see Naming below). It can write to the Coil number to change the status of the Turnout or Sensor within JMRI. A "1" is THROWN or ACTIVE, respectively; a "0" is CLOSED or INACTIVE.

Until each Coil is first written or set within JMRI, the state of the associated Turnout or Sensor will be "UNKNOWN" and it will be read back as "zero" on Modbus.

With this convention, you can put Turnouts and Sensors on your JMRI Panel, and then connect them to PLC code that will tell them what to display. If desired, local changes, e.g. clicking on the screen, can be read back and used to control the railroad.

Configuring as a Slave Node

In the Preferences pane for Connections, select "Modbus" as the System manufacturer and "RS485 ASCII Slave" as the System Connection. Under Settings, select the communications (serial) port your interface is connected on, the baud rate, and enter the node number your Modbus Master Node will use to refer to JMRI. Click "Save", quit and restart.

Next, use the Turnout Table and Sensor Table to define Turnouts and Sensors, which will in the process define the Coils and Discrete inputs that Modbus will read and write. Save this configuration to a Panel file so that it can be reloaded when you start JMRI again later.

Naming

The default system letter for Modbus connections is "M". It can be configured to another letter if desired.

Normally, JMRI provides an interface to the real layout via internal objects such as Turnouts and Sensors that are closely mapped to corresponding physical devices. This mapping is done via "System Names", which both identify the how to access a particular device, and are the key to looking up the corresponding object in JMRI. Here, we have to pick a naming convention that allows those inside-JMRI work with the properties of Modbus.

We therefore provide the following mapping:

JMRI Turnout MTnnn, e.g. MT123: This will appear as Modbus coil nnn and discrete input nnn, e.g. coil 123 and discrete input 123
JMRI Sensor MSnnn, e.g. MS123: This will appear as Modbus coil nnn+1000 and discrete input nnn+1000, e.g. coil 1123 and discrete input 1123