Modbus Server

Purpose

Purpose of this plugin is to instantiate a Modbus Server on the Ardexa edge device.

Description

This plugin will read a configuration file, read Modbus registers from a local network, and then publish Modbus data locally. Data can be sourced either via RTU (local serial device) or from local IP addresses. The source Modbus registers can then be remapped to other registers. No data will be sent to the Ardexa cloud. This plugin is just to assist some plant owners that require Modbus data to be shared locally, via a Modbus Server.

Configuration File

The configuration file is required to manage various aspects of the data collection and conversion. The file must be defined as shown below. There are a few rules to note:

1. The IP/Serial device address MUST be at the end of ALL the mbpoll commands

2. Mbpoll commands MUST start with _cmd, , followed by the mbpoll command which sources the data

3. All the other lines in the configuration file define registers and how they are to be treated.

4. All lines that start with an # character are treated as comments and will be ignored.

5. Each of the columns listed below MUST not be empty.

6. For Type, only the valid strings can be used: INT16, INT32, FLOAT.

7. If a INT32 or FLOAT type is used, be sure to leave 2 sequential output registers free.

8. Scale can be any floating point number. It can only be used on FLOAT, but NOT INT16 or INT32 - which must be set to 1.0.

9. _cmd is the commands to run. Only modpoll or the mbpoll commands can be used to read Modbus registers. mbpoll is preferred. The registers being collected MUST MATCH the registers listed in the configuration items. If not, you will have empty fields when running a discover. The IP address or serial device MUST appear as the last entry in the command.

10. Each Output Register must be unique. If there are any duplicates, then the script will report an error and not run.

#
_cmd, mbpoll -m tcp -a 1 -r 120 -c 50 -t 3 -1 -0 -p 502 192.168.1.10
_cmd, mbpoll -m rtu -a 2 -r 1 -c 2 -t 3 -1 -0 /dev/ttyACM3
#
# Output Register    Type,      Description,    Units,      Scale,  Source Endpoint        Input Register
1,                   INT16,     Pressure,       hPa,        150,    192.168.1.10,            123
2,                   INT32,     Direction,      degs,       1.1,    192.168.1.10,            130
8,                   INT16,     Flow Rate,      L/min,      3.5,    192.168.1.10,            145
9,                   FLOAT,     Radiation,      W/m^2,      1.0,    192.168.1.10,            155
105,                 INT16,     Temp,           C,          0.1,    /dev/ttyACM3,            2
206,                 INT16,     Humidity,       %,          0.01,   /dev/ttyACM3,            3

Usage

This plugin uses a configuration file. The file must be named as modbus_server.txt in the directory: /opt/ardexa/config/modbus-server, and configured as discussed above. Once a single scenario has been defined, a service will be activated that waits for Modbus requests. The task element of the scenario will not do anything. The scenario must be activated as a service. Due to a technical limitation, in order to save some config data when initially setting up the server, such as a custom port, once the service is created you may have to turn on the Test Mode then SAVE, then turn it off and SAVE again. DO NOT create multiple scenarios for this service, it is not designed for this and will lead to undefined behaviour.

Also, you need to open a firewall port manually once the scenario has been activated. This is a design feature, to warrant that the user is aware of the risks of activating a service (server) on the local device. To open a firewall port on the Ardexa device run the following command: sudo ufw allow 502, where 502 should be the port number required. To close all ports, run the command: sudo ufw default deny incoming. The Modbus Server port is defined when setting up the server.

If a Modbus request is received, the data defined in the configuration file will be queried and served via the service. The plugin will make a maximum of 3 attempts to read the data, and will cache the results for a maximum of 10 seconds. This cache is to prevent the source endpoints from being overloaded with modbus queries. Queries may take a little longer, so a timeout of a few seconds may be required. If using the mbpoll client, this is achieved using the -o argument, such as the query: mbpoll -m tcp -a 1 -r 11 -c 8 -t 4:float -1 -0 -o 8 -p 502 127.0.0.1 - which specifies a timeout of 8 seconds. DO NOT connect to this server with multiple clients, it can only handle one connection at a time. If one client has been connected for more than 30 seconds it will be automatically disconnected, this is to prevent dead connections blocking the server.

Clients querying the Modbus server must use address 1. It will respond to either Input or Holding registers requests. When the service is started, or when running a discover command (see below), a PDF file will be written to /opt/ardexa/config/modbus-server/modbus_server_mapping.pdf, which will show the parameters of the configuration file, IP address, port and cache settings. It can be downloaded from the edit scenario page by selecting in the drop down.

Please note that for this service to be reliable a static IP address must be defined on the Ardexa device. In order to test the plugin is working ok, the service can be checked as follows: systemctl status modbus-server-plugin.service

Test Mode

There is also a test mode, used to serve known values for debugging. this is activated by the switch in the scenario page. These registers and their value can then be checked with a script that is run with the discover button. The script and its configuration files, found in /opt/ardexa/config/modbus-server, can be downloaded and configured locally to test a remote server. There should be a test_client.py script, a test_server.txt configuration and some .dict lookups. There is also a multiple option in the config interface, this will add duplicate test registers in multiples of 100, for example if multiple is 2 then registers 1 and 101 will store the current hour.

Some of the test mode registers values are dynamic and others are fixed, as per the list below:

register, value

1,           hour
2,           minute
3,           second
4,           True
5,           32 bit unix time int
7,           32 bit uptime float
9,10,11      day of week character, eg. Thu
12,          0x1234
13,          0xabcd
14,          cpu usage 32 bit float
16,          ram usage 32 bit float
18,19,20,21  timezone characters, eg. AEST
22,23,24,25  ip addr numbers as 16 bit ints
26,          32 bit uptime int
30001,       0xff00
30002,       1.2345 32 bit float little endian
30004,       1.2345 32 bit float big endian
30006,       123456 32 bit int little endian
30008,       123456 32 bit int big endian
30010,       2 
30011,       4
30012,       8
30013,       16
30014,       0010000000000000
30015,       308
30016,       51