Before proceeding with this applications note, ensure you have reviewed the following:
For more information on Modbus, consult this list of resources
Binding the Protocol to the Hardware
The first step in connecting as a Modbus slave device is to create a link
node in the Resources area
, go to the Resources area
and right click on the “links” section and add a new link
node. This node will bind the Modbus slave protocol to a physical communications channel, so set up this new link
node with properties like this:
Each channel in a platform may only be bound once to a single protocol. For example, UART0 can only be bound to a single protocol (e.g. MODBUS_SLAVE_RTU
Creating One or More Virtual Slave Devices
Within a given link
, there may be one or more linkset
nodes. Each linkset
encompasses all the traffic between two endpoints in a link
. On the slave side of master/slave protocols (for example the MODBUS_SLAVE_RTU
), the GUI may be responding as one or more Modbus slaves. Even though the protocol is running on a single physical communications channel (e.g. UART0), each linkset
within the link
can act as one of a number of independent virtual slaves.
Adding two linksets
to our prior example might look like this:
In this example GUI, our SIM is acting as a Modbus slave attached to UART0, potentially one of many other Modbus slave devices on the physical network. This physical network (aka channel) could be, for instance, a multi-drop RS485 network with many slaves of which our SIM
is only one. Our GUI, because it has the two linksets
at ID #1 and #13 created, will respond as if it were two of those slaves on the network.
Adding Shared Link Variables
The SHIP GUI communicates with a remote network device using the concept of link variables
. These are variables who’s values are shared, nearly automatically, across the communications link. One party must own the actual true value of the variable, other parties on the network merely need to get copies of the latest value in order to display, react, control, or otherwise act on that value.
For example, if a device on a network has a motor RPM sensor, that device “owns” that value – perhaps represented as a 16-bit signed (for motor direction) RPM value. Other devices on the network that need to know that motor’s RPM need to somehow get access to that devices “RPM variable” periodically. A SHIP GUI, for example, may need to update a value on the screen showing the motor RPM every second or even more frequently.
These shared network variables are represented in your SHIP GUI each as linkvar
nodes describing these shared network variables within a given linkset
. The linkvar
properties available depend on the protocol selected.
The following are normal properties of a linkvar
||A unique variable name within the linkset
||The data type of this link variable; may be limited depending on the protocols
||Most protocols require each variable to have a unique address/location/id number assigned
||Most protocols need to understand if this is an input or output variable
||Defaults to true, but can be set false in SHIPTide. Only enabled variables participate in polling (if applicable).
The direction can be a bit confusing: it is always with respect to SHIPEngine
and the GUI. So an output
direction means the data is supplied by SHIPEngine
to the device across the network on the remote end of the linkset
, regardless of whether the linkset
is a master or slave in a master/slave environment. Similarly, an input
direction means that the data is coming into the variable from the remote end of the linkset
. Remember that “in” and “out” are with respect to your GUI in SHIPEngine
The datatypes are protocol
dependent, and, in the Modbus case, may be limited to the basic Modbus data types of Boolean
Expanding the example above with four linkvars
looks like this:
Our example here is, perhaps, a hypothetical GUI controlling a pump. Our GUI (in a Sail script
) could turn on the pump by setting the pumpOnRequest output Boolean linkvar
to “true”. Since Modbus masters poll their slaves, the next time the master polls slave #1 address 0x4000 (“pumpOnRequest”, a Boolean
), it will read a “true” at that shared variable location, indicating to the master (the pump) to turn on. It may also poll slave #1 address 0x2000 (“pumpRPMRequest”, a Short
) to determine the requested RPM before turning the pump on. It may continue to poll these two locations to watch for a request to stop the pump or change the RPM. Also, as the pump turns on and off, and its actual RPM changes, it may send those values to slave#1 address 0x4001 (“pumpOn”, a Boolean
) and 0x2002 (“pumpRPM”, a Short
Note that just because the GUI “requests” that a remote device performs some action does not mean the remote device actually does it. The GUI (in a Sail script
) might request the pump turn on, but it may not happen for whatever reason (the pump is overheated, for example). Timeouts and other mechanisms can be done in the GUI to watch for these conditions.
A good practice is to have visual indicators on the GUI reflect the actual remote state, rather than the requested state. For example, an RPM reading in the GUI should reflect the value of “pumpRPM”, not “pumpRPMRequest”.