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.
JMRI provides support for general JMRI Sensors and Turnouts via Modbus (Node) connections.
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.
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).
(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.
When configured as a Slave, JMRI appears as Coils and Discrete inputs to the Modbus Master. Modbus:
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.
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.
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: