Modbus Master for SoftPLC® Runtime

This document describes the installation, usage and functionality of a TLM (TOPDOC Loadable Module) for SoftPLC versions 4.6 and later. This TLM implements the master side of the Modbus Master/Slave Protocol using a serial line. See here and here for definitions of this protocol.

The TLM described by this document is called MODBMAST. This software capability is implemented as a TOPDOC Loadable Module (TLM), written in C++ and implements a fairly comprehensive driver which can manage up to 247 slaves on each of up to 32 serial ports.

This TLM may be used to monitor and control serial RS485, RS422, or RS232 attached slaves. Modbus protocol has been used as the basis of SCADA systems, but was originally designed for communicating with Modicon PLC’s. This TLM has features in it that allow it to also do a reasonable job controlling I/O. That is, it can be configured to take special steps to drive outputs in a way consistent with programmable controller outputs, such as turning outputs off when transitioning to a program/stopped from a run mode. Both Modbus RTU and Modbus ASCII are supported, however Modbus ASCII support requires SoftPLC version 4.6.160608 and TOPDOC NexGen version 1.6.160608 or later.

SoftPLC offers other TLMs in support of Modbus TCP/UDP, as well as Modbus RTU/ASCII Slave. This TLM only implements the serial line form of the protocol and only the master side of it.

TLMs may be developed by any competent C/C++ programmer who has access to the SoftPLC C/C++ Programmer’s Toolkit, a product readily available from SoftPLC Corporation. There are a number of Systems Integrators who are SoftPLC Partners who possess the requisite expertise. End users may also have this capability.

The SoftPLC runtime engine software supports TLMs, which are shared library extensions to SoftPLC. A TLM may be loaded either as a DRIVER or as a MODULE. The difference between a DRIVER and a MODULE is that a DRIVER is called once per SoftPLC scan, and optionally an additional number of times per scan. A MODULE is only called when the control program decides to call it and not as an inherent part of the scan. TLMs are made known to SoftPLC in the MODULES.LST file which may be edited by TOPDOC NexGen by traversing to: PLC | Modules.

The SoftPLC runtime engine is always in one of the following states, called Operating Modes.

Each configured Modbus slave is always in one of the following states. Each slave’s state is independent of the state of any other slave, so not all slaves are always in the same state.

The two states shown are tracked by the MODBMAST.TLM for each slave. The Present and Responding state is used for all 4 Operating Modes. As long as a slave is responding, the TLM can tell it what to do and thereby honor its obligations with respect to Operating Modes. The slaves have no actual knowledge of the SoftPLC Operating Modes per se. A slave can however be told to turn its "outputs" off by sending zeroes to those Modbus memory registors in the slave. The slave does not know the data is "idle" data, only the TLM does.

The SoftPLC runtime engine notifies all TLMs of the need to change from one Operating Mode to another. A TLM that is acting as an I/O driver must honor the behavior outlined in the Operating Modes table above. To accomplish this, there are responsibilities that must be met at the edge of these mode transitions.

Some slaves may need to be configured, and maybe the configuration can be done using one or more Modbus requests on a single shot basis. This soft configuration is supported by the TLM when entering Run mode.

At any moment in time, there is a scan list within the TLM for each port. The scan list is a list of requests that need to be sent now or sometime in the future. The front or top of the list holds the request currently being processed on that port. When completed or timed out, that request is moved towards the rear of the list for another attempt later. Because serial communications can be slow, depending on baudrate, number of slaves, and the turn around time at each slave, this TLM was designed to allow the scanning of the entire scan list to complete over several program scans. And since each port has its own scan list, and the size of these can be different, the total time to scan the entire scan list (scan time) will be different for each port.

When you set the "attempts" attribute to greater than its default of one, then that request will immediately be tried again at that point in the scan list should there be a reply timeout. The "attempts" setting only pertains if there is a timeout. If "attempts" is left at the default of one, then the failed request will be put at the end of the scan list and will be attempted later once it works its way again to the front of the scan list. There is currently no way to take a slave out of the scan list except through a configuration file change. But leaving "attempts" set to one means that a temporarily unavailable slave will only be sent a request once, but once for each request configured for that slave and there may be several.

The master begins timing a transaction only after the entire request has been transmitted. This makes the requestTimeout independent of request length. If the first byte of the reply is not seen within requestTimeout msecs from this point, then the transaction is deemed timed out. After the first byte of the reply is received, then a different type of timeout comes into play, and that is the inter-character timeout limit which comes from the Modbus specification. So the requestTimeout is also independent of reply length. Essentially this means that the requestTimeout can be thought of as mostly corresponding to the turn around time of the slave, and has only minimal dependency on the baudrate of the reply. Therefore, it is possible to have fairly agressive and tight requestTimeouts. This makes it possible to minimize the impact on overall scan time of a missing slave.

Modbus protocol transactions were originally designed for communicating with Modicon PLC slaves. They assume the existence of and reference four different types of Modicon device memory regions. Any non-Modicon slave must emulate these four memory regions as if it were an actual Modicon PLC. Words and bits within these memory addresses are addressed using Reference Numbers, according to the following table.

The first character of a reference number identifies which of the four memory regions is being addressed within a (ficticious) Modicon PLC. The first character is special, and might as well be conceptually removed from the reference number before interpreting the remaining portion of the reference number itself. So when you see a reference number like 40001, think of this as section 4, and element 0001. Section 4 is for Output (aka Holding) Registers. After the leading character you are then left with ordinal 0001 or 1. The elements within each of the 4 Modicon memory regions are numbered starting from 1.

This TLM is configured using a special configuration editor which is built into TOPDOC NexGen. The configuration file is XML text, is hierarchical with the following XML elements. Elements are listed below with one of the following characters appended. The appendage is used to indicate how many times the element may occur in any given context.

The appended character and its meaning is as follows:

The following is a sample screen from the configuration editor showing a few of the elements from the above table. Notice how they are arranged hierarchically and that each element can "contain" other elements. (The rules of containment are given in the table Elements and their Allowed Sub-Elements.)

In the above panel, the element name is at the far left of each tree row. To the right of the element name, still within the tree row, is a list of attributes. That element’s attributes are elaborated on within the table at the far right of the panel. That table is dynamic (depends on the selected element), and has one row for each attribute. The following table lists the allowed attributes for each element type:

In the rules table which follows you will see three attributes occur in more than one XML Element (tree node). The three attributes are:

These three are special and are the inherited attributes . If missing at a given node, then the value is used from the next nearest ancestor above which encloses the node missing the attribute. For example, if a request node does not have a requestTimeout setting (because it is optional and in this example is not present) then the enclosing Slave element is searched for a requestTimeout. If it is still missing there, then the enclosing Port element is searched. If it is still missing there, then the Port’s default is used.

The table below gives the allowed attributes which may be attached to each XML element in the configuration file. Only these attributes may be attached to the corresponding element.

The TLM is named modbmast.tlm.so and is found as part of the standard SoftPLC 4.x installation in the /SoftPLC/tlm directory. To use it you merely have to enable it in NexGen’s PLC | MODULES editor. Then you must edit the xml file MODBUS.XML which is the TLM’s configuration file. There is an application specific editor for this MODBUS.XML file within NexGen. It is easy to edit the configuration file from the PLC | MODULES editor. Simply click on the Configure button after selecting and enabling Use in the same row as the MBIPMAST TLM.

Add button will insert a new element within the selected element. First select the element you wish to insert into.

Delete button will deleted the selected element. It is only enabled when you are allowed to delete the selected element.

Move Up button will move the selected element up in the current containment list.

Fetch, Send, Load, and Save all have the same meaning as they do in the NexGen Module editor. You can see the helpfile for that editor by going to that editor and clicking on Help.

Use Send to transfer the configuration down to the SoftPLC. The next step is to cycle power on the SoftPLC for the changes to take place.

This TLM implements three ladder instructions which are useful for diagnostics and fault situations.

During startup or when troubleshooting a problem node it is usually best to isolate the problem node. This means look at it in isolation, by making it the only active slave on the network. You can keep the other slaves connected, but use a temporary configuration file to announce to the TLM only the node that you are troubleshooting. All other nodes/slaves will simply not be scanned.

The SoftPLC runtime engine constantly monitors its processes, and 'logs' these observations as process output. By default, these logs are minimal. However, for troubleshooting purposes, the logs can provide greater detail.

In the configuration file there is the top most element ModbusSerial and its attribute debug.

Viewing these logs shall be completed at the command prompt of the SoftPLC system. To access the command prompt, log into the SoftPLC by either:

Once logged in, the logs can be viewed by executing one of the following:
(the '#' represents the prompt, and is not typed)

The previous sections have shown how to view the logs from the command prompt. However, recording the logs to text file format is, in the least, efficient for receiving support. Accomplishing this, much like viewing the logs, is firmware dependent (see following sections). Once the text file is created, it can be transferred via (S)FTP to the TOPDOC machine. A detailed explanation of (S)FTP transfers can be found in the TOPDOC User’s Guide.