MODBUS

MODBUS OPC UA server implements MODBUS TCP protocol and exposes COIL, DI, HREG and IREG registers via OPC UA interface.

Download

v3.0.0 / Nov 14, 2024

Installation

Installation process is very simple and straight forward. Installer copies the following files to “%PROGRAMFILES%\X-tensive\DPA.UA\modbus\“ directory:

dpa.ua.modbus.exe
dpa.ua.modbus.ctrl.exe

Firewall exception is added for dpa.ua.modbus.exe executable.

If there is no certificate or private key for OPC UA server default instance, a self-signed certificate as well as private key are generated and placed to “instances\default\“ subfolder.

Installer is a simple console application that requires no user interaction or parameters. All output is sent to stdout and stderr. It is fine to run installer under SSH session. Here is a typical output:

dpa installer 2.1.0.0, 64-bit
Destination: C:\Program Files\X-tensive\DPA.UA\modbus\
Discovering services for "dpa.ua.modbus.ctrl.exe"...
Discovering services for "dpa.ua.modbus.exe"...
Checking processes for "dpa.ua.modbus.ctrl.exe"...
Checking processes for "dpa.ua.modbus.exe"...
Copying "dpa.ua.modbus.ctrl.exe"... ok
Copying "dpa.ua.modbus.exe"... ok
Generating default certificate...
  default certificate exists already. Will skip.
Will configure firewall...
  exception for "dpa.ua.modbus.exe"... ok
installation SUCCEEDED!

Update of running services

In case when a previous version was already installed and the OPC UA server instances are up and running as Windows services, the installer will perform the update correctly. First, all running services of the OPC UA server are shutdown gracefully. Old binaries are replaced with a new version. Finally, all previously running instances are started again.

Update of interactively running processes

In case when the OPC UA server runs as an interactive console process, installer terminates this process before installation to release any locks on old binaries, otherwise installation and updating of the binaries would fail. The installer does not attempt to restart interactive processes after the binaries update.

Command line arguments

/dev:<host[:port]>

MODBUS device ip and port (optionally), like “192.168.0.1” or “192.168.0.1:502”.

/slave:<num>

Optional. MODBUS slave id.

/reconnectInterval:<num>

Optional. Reconnection interval between two consecutive connection attempts, ms. Default is 5000 ms.

/requestInterval:<num>

Optional. Minimal interval between requests, ms. Default is 100 ms.

/responseTimeout:<num>

Optional. Timeout interval used to wait for a response, ms. Default is 1000 ms.

/byteTimeout:<num>

Optional. Timeout interval between two consecutive bytes of a message, ms. If there is no character in the buffer, the allowed timeout interval between two consecutive bytes is defined by byte timeout. Default is 1000 ms.

/readAttempts:<num>

Optional. Maximal read attempts before failure. Default is 3.

/instance:<str>

Optional. Specifies instance name for non-default instance. Instances are explained here.

/nocert

Do not use certificates. Indicates that OPC UA server should not expose secured endpoints. Can optionally be applied only to OPC UA servers running interactively. Can not be applied to OPC UA servers running as Windows Services.

/port:<num>

Optional. Specifies TCP port for OPC UA server. Default is 4840.

Running in Console mode

The OPC UA server can run interactively in console mode. For instance:

dpa.ua.modbus /dev:192.168.0.2 /slave:16 /responseTimeout:3000

Ctrl+C gracefully shuts down the server.

Running as Windows Service

It’s very easy to run OPC UA server as Windows service. dpa.ua.modbus.ctrl is used to list, register and unregister Windows Services for MODBUS OPC UA servers. For example, to register OPC UA server as a service:

dpa.ua.modbus.ctrl /install /dev:192.168.0.2 /slave:16 /responseTimeout:3000

If you need to connect several MODBUS devices, named instances must be used. Instances are explained here. The instance name is specified via the command line argument “instance”. Take into account, each instance must have unique tcp port to expose OPC UA endpoints:

dpa.ua.modbus.ctrl /install /dev:192.168.0.3 /slave:16 /responseTimeout:3000 /instance:dev2 /port:4841

To list all installed instances:

dpa.ua.modbus.ctrl.exe /list

Typical output:

DPAOPCUA.MODBUS
  instance: (default)
  port: 4840
  dev: 192.168.0.2:502
  slave: 16
  reconnectionInterval: 5000
  requestInterval: 100
  responseTimeout: 3000
  byteTimeout: 1000
  readAttempts: 3
  start type: auto
  status: stopped
DPAOPCUA.MODBUS.dev2
  instance: dev2
  port: 4841
  dev: 192.168.0.3:502
  slave: 16
  reconnectionInterval: 5000
  requestInterval: 100
  responseTimeout: 3000
  byteTimeout: 1000
  readAttempts: 3
  start type: auto
  status: stopped

Finally, to start the (default) instance:

net start DPAOPCUA.MODBUS

Or to start named instance “dev2”:

net start DPAOPCUA.MODBUS.dev2

To unregister the Windows Service:

dpa.ua.modbus.ctrl /uninstall /instance:dev2

Take into account, the service is not stopped automatically when unregistering. It must be stopped with “net stop” command before.

Address space

MODBUS OPC UA server provides https://dpaxt.io/UA/modbus/ namespace which defines 4 variables to access COIL, DI, HREG and IREG registers respectively:

Objects/MODBUS/AS/COIL
Objects/MODBUS/AS/DI
Objects/MODBUS/AS/HREG
Objects/MODBUS/AS/IREG

Use OPC UA indexes to access particular register. For instance, to access HREG register number 32:

Objects/MODBUS/AS/HREG[32]

Ranges are supported as well. To read HREG values of registers 32-38:

Objects/MODBUS/AS/HREG[32:38]

To explicitly specify the slave number, use indexes with two components. For instance, to read HREG values of registers 32-38 from slave 13:

Objects/MODBUS/AS/HREG[13,32:38]

Aliases are human-readable shortcuts, allowing easy access to indexed registers using clear notations such as “temperature”, “speed”, etc. Conversion and data transformation are also supported. For example, to convert two 16-bit registers into one value of type “float”.

Troubleshooting

Windows Service fails to start

In case OPC UA server fails to start as Windows Service, run it in Console mode with exactly the same command line arguments to check console output. Normally, all diagnostic messages are sent to stdout and stderr. For instance, when OPC UA server fails to read the certificate or the private key:

[2023-10-18 11:07:13.019 (UTC+0300)] fatal/server       Could not load certificate storage.

In that case ensure that .cert and .key files exist and are located according to Instances directory structure.

An invalid or corrupted alias.json file may cause service to fail to start:

[2023-10-18 11:08:54.418 (UTC+0300)] fatal/server       Could not load alias json.

In that case ensure that alias.json is valid and its content respects the demands described here. Take into account that empty alias.json file is considered as invalid. If aliases are not used, just remove alias.json.

License

If the license is not installed or if the license is not valid, for example, an expired TRIAL license, then the OPC UA server will function for 1 hour after starting the process. After the hour has elapsed, the OPC UA server will return a BADLICENSENOTAVAILABLE or BADLICENSEEXPIRED error on requests to read and write data, except for system objects and system variables of OPC UA server.

The variable “Objects/Server/Instance/LicenseKey” allows to read the loaded license and its status. Next, the license status can be checked with the command line utility dpa.opcua.rs:

dpa.opcua.rs.exe target <OpcServerIp>

MODBUS communication

To troubleshoot any MODBUS communication issues, please, refer to “Objects/MODBUS/link” variable. It provides detailed information about the status of MODBUS TCP connection as well as any errors detected, including the rich set of counters for various types of errors.