ModbusIP Master for SoftPLC® Runtime

This document describes the installation, usage, and functionality of a TOPDOC Loadable Module (TLM) for SoftPLC version 4.x and later. The TLM implements the master (or client) side of the Modbus TCP protocol. As an extension of the standard, it also implements the same protocol on UDP/IP.

This TLM may be used to monitor and control ethernet based I/O and MMI graphical user interface stations, or it may be used to communicate with other controllers on an ethernet. Modbus protocol was designed for communicating with Modicon PLC’s and was not designed for communicating with I/O. However, this TLM is an I/O driver first and foremost, and a peer to peer messaging service secondarily. Therefore it takes special steps to overcome most shortcomings in the Modbus protocol with respect to I/O control, resulting in a good I/O solution to most control applications.

This driver can be used without any application program logic required for configuring I/O modules or firing messages. Messages are ear-marked for either "configuration" or "RUN mode continuous" purposes. Configuration messages take place automatically just as SoftPLC enters RUN mode. RUN mode continuous messages are issued cyclically any time SoftPLC is in RUN mode. Lastly, the RUN mode continuous messages automatically use alternate "write" data on the last scan before SoftPLC enters PROGRAM mode, and thus the process outputs will be turned off as you would expect.

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.

In order to use the modbus IP master TLM you need a working ethernet connection. This TLM takes a configuration file named MBIPMAST.XML and acts as a "scanner" or as "master" or a "client", three terms which mean the same thing in the context of Modbus IP. On the other end of any Modbus conversation is a "slave" or a "server". Because the master implemented by this TLM supports both TCP and UDP carriers for the Modbus protocol, this allows you to talk to slaves which implement MODBUS/UDP in addition to slaves which implement only MODBUS/TCP. Up to 128 servers are supported by this master. Each slave may be addressed using TCP or UDP, or both.

When TCP is used by the master, there is a TCP connection established. When UDP is used by the master, the request response sequence takes place in a "connection-less" fashion. Because UDP is not a guaranteed delivery service, any Modbus master using UDP instead of TCP to carry the modbus requests and responses should implement timeout and retry logic. This master TLM allows you to configure the response timeout and attempts for each UDP server uniquely.

SoftPLC also provides a Modbus IP Slave TLM, which is documented here. A single SoftPLC machine can be both a master and a slave. This capability gives the systems designer the power and flexibility to develop very powerful, fast and flexible distributed control systems. Obviously a SoftPLC Modbus master can talk to a SoftPLC Modbus slave as well as third party slaves.

The following is a list of the Modbus Commands, and whether they are supported or not:

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

Each configured Modbus IP 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 TLM for each slave. The Present and Responding state is used for all 4 Operating Modes. As long as an I/O module 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. An output module is told to go "idle" merely by sending the corresponding process data to the module. The module 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 significant responsibilities that must be met at the edge of these mode transitions.

Additionally most Modbus IP I/O modules these days are intelligent and can be software configured to operate with alternative behaviors. The soft configuration normally takes place by sending regular Modbus requests, but with special memory addresses used in the requests that are reserved for configuration.

This soft configuration may be required when entering Run mode, or it may be required just after an I/O module is replaced, possibly due to an I/O module failure. The I/O module replacement might take place while the SoftPLC runtime engine is in Run mode the entire time. The I/O driver must therefore detect that the I/O module is newly present, and send the configuration commands on the edge of this transition from not present to present.

The TLM has its own thread (scanner thread) with its own scanning operation. This scanner thread is separate from the main control program thread (main thread) which is part of the SoftPLC runtime engine. The scanner thread runs in parallel with the main thread. Naturally the two threads can have different work loads and will rarely complete their respective scan cycles in the same amount of time. The following rules are put into effect:

In other words, the scanner thread is not allowed to wastefully use CPU cycles obtaining fresh I/O status only to have it not used. On the other hand, if this Modbus master scanner thread is running slower than the main thread, then only the I/O on the ethernet is updated slower. Any other I/O drivers (TLMs) and the main thread are not slowed down due to a slow ethernet module.

The modbus scanner thread issues many of the requests all at once and then services the responses as they come back asynchronously. This gives the best modbus I/O scan times because all the slaves are handling their respective requests in parallel. However, it can lead to choppy network traffic with higher instantaneous bursts of traffic at the start of each I/O scan. For this reason and for reasons of reliability and overall consistency of performance, it is recommended, but not mandatory, that a dedicated ethernet be used for the I/O modules and this master, particularly if you have more than a handful of slave nodes.

Modbus commands were originally designed for a Modicon PLC. Therefore they assume 4 different types of memory regions. Words within these memory addresses are addressed using Reference Numbers, according to the following table. Basically, the first character of a reference number gives its region:

Modbus TCP protocol includes the original slave id field which was part of the modbus on serial line protocol. In the case of communications on ethernet, either via TCP or UDP, this field is no longer used to qualify the actual network node that will respond to a request. The reason for this is because the IP Address in the ethernet frame serves this purpose. Therefore the "slave id" field becomes available for another use. This TLM can be configured to use a slave id field of your choosing for any request.

This TLM is configured using a special configuration editor which is built into TOPDOC NexGen. The configuration file is organized hierarchically with the following building blocks (elements). Sub Elements are listed with one of the following characters trailing (suffix), indicating that zero or more elements must or may be present according to the following interpretation:

Here 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:

The element name is at the far left of each row. To the right of the element name is a list of attributes. The following table lists the allowed attributes for each element type:

The TLM is named mbipmast.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 MBIPMAST.XML which is the TLM’s configuration file. There is an application specific editor for this MBIPMAST.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. As an alternative to cycling power, you may enter "Remote Program" mode using NexGen, then select "Remote Program" a second time. This psuedo transition from Remote Program to Remote Program is a signal to the TLM that it should reload its configuration file. This way you can reconfigure without cycling power, although it does require you enter "Remote Program" mode (twice!).

With a (or multiple) TealwareDrop present, using Save or Send, the configuration editor will run a verification check on the address references used in all modules. If any overlaps are found, the error will be shown; otherwise the editor will then automatically generate Slave elements with Modbus requests as appropriate for all the modules. These elements cannot be edited, and any changes that may be needed should be made by editing the actual module element or its address component. For more information on TealwareDrop elements and their components, see the Configuration page.

The Module Selection dialog is used to assign Tealware modules to specific slots in a Rack.

The Select Module Type box allows you to choose which types of modules you want to view when choosing what to add.

The Select Module box shows a list of all modules of the selected type with descriptions.

Configure Values displays the input and/or output areas for the module, as well as a table to configure the CDM data for the module (if present). Default values are supplied by the configuration tool and are automatically incremented as modules are added, but these values can be changed manually at any point. Values for digital addresses are word references, while analog addresses are input as an offset from word 0 in the file given by the ModbusTLM element.

Ok will add the selected module to the Rack, while Cancel will take no action and close the dialog.

The configuration editor also provides a network discovery utility that can detect what Racks and modules are present in a Tealware Drop. Selecting the desired TealwareDrop element and right-clicking on it will show the menu options for the network utilities: Configure this TealwareDrop and BOOTP Protocol. The first option looks on the network at the IP Address specified for the selected Drop and (if successful) discovers what is present. The components for the TealwareDrop are then added and configured using the auto-increment functionality to assign addresses for the modules. Any CDM data must be manually entered.

The second menu option will open a new dialog window that will use the BOOTP Protocol to configure the selected TealwareDrop with an IP Address.

Right-clicking with the ModbusTLM root element selected will bring up an option to Discover/Configure all Tealware Drops. This performs the same function as for an individual element, but will find and add any TealwareDrop elements as well as their componenets.

This TLM implements a few 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 (MBIPMAST.XML), there is the top most element ModbusTLM 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.

The XML grammar supported by the MBIPMAST.XML configuration file is given in the following modbusIP.dtd file. The latest version of this file is kept within the topdoc.jar file, and is named modbusIP.dtd: