Configuration

As of today, configuration of the ogamma Modbus OPC UA Server is done by editing of the configuration file. Location of the file is data/config.json. Intially file does not exist, and is created automatically at application start up.

Changing configuration settings.

Configuration settings are defined in JSON format, and can be modified in 3 different ways:

1. Editing the file in place.

Configuration file data/config.json can be edited using text editor. The application monitors changes in the configuration file, and changes will be applied without restart. Existing connections will be closed and clients need to reconnect after configuration changes though.

2. Over OPC UA interface.

Two methods are defined in the OPC UA server address space to facilitate editign of the server configuration: Server/Get Configuration to receive the current settings from the server, and Server/ Set Configuration to replace the configuration file.

To get the current configuration form the server, connect to it using OPC UA client and call method Get Configuration:

To apply new configuration, connect to the server using OPC UA client and call method Set Configuration. In case of success, the server should restart and apply changes automatically.

3. Using environment variables

A few environment variables can be used to change some configuration options. Note that these settings have priority over settings defined in the configuration file. They are not applied when the configuration is modified over OPC UA interface.

OMOUAS_PORT - type: integer, defines OPC UA Server port number.
OMOUAS_HOST - type: string, defines host name used in discovery and endpoint URLs returned by the server, as well as in the application instance certificate.
OMOUAS_ACCEPT_ANY_CERTIFICATE - type: boolean, if set to value true, any client certificates will be accepted to open secured connection. In production environment must be set to false.
OMOUAS_ENABLE_NONE_SECURE_ENDPOINT - type: boolean, if set to value true, none-secure endpoint can be used to create session. When set to false (default value), none-secure endpoint can be used only to call discovery services (FindServers and GetEndpoints).

Description of configuration settings.

Default configuration file

When the application starts very first time, it creates default configuration file at location data/config.json (relative to the working directory). The content of the file is quoted in the code block below.

{
    "id": "B1FC1A028461BAB1",
    "idh": "768B669E916A0E6D",
    "td": 132963433740090893,
    "server": {
        "port": 4840,
        "hostName": "",
        "endpointUrlPath": "",
        "acceptAnyCertificate": true,
        "enableNoneSecureEndpoint": true,
        "receiveBufferSize": 1048576,
        "sendBufferSize": 1048576
    },
    "modbus": {
        "devices": [
            {
                "unitId": 1,
                "browseName": "",
                "description": "",
                "hostName": "127.0.0.1",
                "name": "Modbus Device",
                "type": "TCP",
                "port": 502,
                "serialDeviceName": "COM1",
                "serialBaudRate": 9600,
                "serialDataBits": 8,
                "serialParity": "N",
                "serialStopBits": 1,
                "inputCoils": {
                    "name": "Input Coils",
                    "browseName": "inputCoils",
                    "variables": [
                        {
                            "name": "IC1",
                            "dataType": "Boolean",
                            "offset": 0,
                            "index": 0,
                            "arrayLength": -1
                        }
                    ]
                },
                "outputCoils": {
                    "name": "Output Coils",
                    "browseName": "outputCoils",
                    "variables": [
                        {
                            "name": "OC1",
                            "dataType": "Boolean",
                            "offset": 0,
                            "index": 0,
                            "arrayLength": -1
                        }
                    ]
                },
                "inputRegisters": {
                    "name": "Input Registers",
                    "browseName": "inputRegisters",
                    "variables": [
                        {
                            "name": "IR1",
                            "dataType": "UInt16",
                            "offset": 0,
                            "index": 0,
                            "arrayLength": -1,
                            "swapBytes": false
                        }
                    ]
                },
                "holdingRegisters": {
                    "name": "Holding Register",
                    "browseName": "holdingResisters",
                    "variables": [
                        {
                            "name": "HR1",
                            "dataType": "UInt16",
                            "offset": 0,
                            "index": 0,
                            "arrayLength": -1,
                            "swapBytes": false
                        }
                    ]
                }
            }
        ]
    }
}

Desctiption of configuration settings.

id, idh, td - these nodes used internally and must be kept unchanged.
server - settings related to the general OPC UA Server properties.
- port - TCP port on which the server listens to accept connections from OPC UA clients. Default value os 4840.
- hostName- host name of the machine where the application runs. It is used as part of discovery and endpoint URLs, as well as in the application instance certificate. If set to empty value, then the application will determine host name by making systems call.
- endpointUrlPath - the postfix part in the OPC UA endpoint URL (the portion following after port number). Default value is empty.
- acceptAnyCertificate - when set to true, any OPC UA client certificate will be accepted in secured connections. Default value is false.
- enableNoneSecureEndpoint - when set to true, connections in none-secure mode are allowed. Default value is false.
- receiveBufferSize - size of the receiving buffer, default value is 1048576 (in bytes). In most cases no need to change this value.
- sendBufferSize - size of the sending buffer, default value is 1048576 (in bytes). In most cases no need to change this value.
modbus / devices - arry of settings defining what Modbus devices to connect to to, and what registers to expose. For each array element of object type there will be created corresponding node in the OPC UA Server’s address space under Objects / DeviceSet. Each node can have the following below sub-nodes:
- unitId - Modbus device’s unit id. Must be unique for each device node.
- name - display name of the device.
- browseName - used as BrowseName attribute of the Modbus device node
- description - used as Description attribute of the Modbus device node.
- type - defines what protocol to use to connect to the Modbus device. Can be TCP for TCP connections or RTU for serial connections (RS-232 or RS-485).
  
  The rest of options depends on the value of the type option.
  
  When type is set to value TCP, following below options are used:
  - hostName - IP address of the Modbus device. Default value: 127.0.0.1. Note: only IPV4 addresses are supported, no host names can be used in the version 1.0.
  - port - port number used to connect to the Modbus device. Default value is 502.
  When option type is set to RTU, the following below options are used (their name start with serial prefix):
  - serialDeviceName - name of serial device. In Windows machines, it is defined as COM1, COM2, and so on. In Linux systems often defiend as /dev/ttyS0.
  - serailBaudRate, serialDataBits, serailParity, serailStopBits define the rest of serial communicaiton options.
The next object nodes are used to group variables representing Modbus registers. They can be of 4 different type, and have similar structure:
- name - display name of the OPC UA node.
- brosweName - attribute BrowseName of the OPC UA node.
- variables - array of variables representing Modbus registers.
- inputCoils - defines Modbus input coils represented in the OPC UA server address space.
- outputCoils - defines Modbus output coils represented in the OPC UA server address space.
- inputRegisters - defines Modbus input registers represented in the OPC UA server address space.
- holdingRegisters - defines Modbus holding (output) registers represented in the OPC UA server address space.
The variables node is JSON array consisting of elements defined as objects with the following below fields:
- name - used as display name and as well as browse name of the OPC UA Variable node. As part, it can have the placeholder [index], which will be replaced by value of the index virtual variable. the index virtual valiable by defualt is set to 1, and is incremented by 1 for the next variable. This way, it is possible to define the field name as like Room [index] temperature. It will be defined as Room 1 temperature at runtime, the next variable name will be Room 2 temperature, and so on. To limit number of variables generated this way, another option, number is used. Its default value is 1, which means, only one variable OPC UA variable wil be created in the address space. If it is set to value greater than 1, then that number of OPC UA variables will be created in the OPC UA server address space. When option number exists``, it is expected that the field name has placeholder [index] or [offset], so they have unique names.
  
  Note that sometimes you might need to define index values with specific width, for example, to make sure that they are ordered properly, like Register 001, Register 002, and so on. For this, it is possible to define option indexFormat with value like {:03d}. Here 3 means width of the index number, and 0 means padding symbol. For more detials about syntax for this option refer to this web page: https://fmt.dev/latest/syntax.html
- dataType - this field defines data type of the OPC UA variable node. Can have the following values:
  - Boolean - boolean type;
  - Int16 - signed 16-bit integer
  - UInt16 - unsigned 16-bit integer
  - Int32 - signed 32-bit integer
  - UInt32 - unsigned 32-bit integer
  - Int64 - signed 64-bit integer
  - UInt64 - unsigned 64-bit integer
  - Float - 32 bit float point number
  - Double - 64 bit float point number
  - String - String type. In this case additional field length must be defined, defining string length.
  - ByteString - ByteString type. In this case additional field length must be defined, defining string length.
- offset - defines offset of the register, starting from 0. If omitted, for the very first variable value 0 is used. For the next variables, next available Modbus register offset will be used. ?If registers are following without gaps, it is possible to omit it completely.
  
  Value of this field can also be used to substitute placeholder [offset] in the name field.
- index - value of this option is used to substitute placeholder [index] in the name option as described above.
- arrayLength - must be set to -1 in version 1.0. In the future versions will be used as array length for array type variables.
- swapBytes - optional, can be used for input and holding registers to indicate that order if bytes must be swapped.
- swapWords - optional, can be used for input and holding register with data types occupying 2 or more registers to indicate that order if words must be swapped.

Configuring trust to OPC UA Client certificates

By default, the ogamma Modbus OPC UA Server is confured to allow only secured connections, and to not accept client certificates if they are not in the list of trusted certificates (the option acceptAnyCertificate is set to false and option enableNoneSecureEndpoint is set to false).

In such configuration, clients can open OPC UA Sessions only in secured mode. When a client tries to connect in secured mode, initially connection will not be accepted, because client certificate is not trusted. The client’s certificate will be stored in the folder data/pki/rejected/certs. To allow connections in secured mode, this stored certificate can be copied to the folder where trusted certificates are stored: data/pki/trusted/certs. Alternatively, you can obtain the client certificate by other means and store it there. The certificate format must be der.

If the client certificate is signed by a CA certificate, then one certificate from the certificates chain must be saved in the folder data/pki/trusted/certs. The CA certificates which are not in the trusted certificates folder, must be stored in the folder of known issuers, that is data/pki/issuer/certs. And additionally, any CA certificate from the chain must have certificate revocation list file stored in folder data/pki/crls.

Note

In Windows machines, after storing or removing a file in one of the PKI folders data/pki/trusted/certs, data/pki/issuer/certs or data/pki/crls, the application restarts the OPC UA Server object to apply changes, so existing client connections will be closed. In Linux machines no such restart is done, so changes are applied in new connections.

Restarting OPC UA Server object and stopping the application

To stop the application, termination signal can be sent at the operating system level, as well as Ctrl+C keys combination works too.

The application also can be stopped by creating a file data/omouas-exit.txt. Note that the file will be deleted before exiting, to prevent inifinite start/exit loops.

Restarting of the internal OPC UA Server object can be done by creating a file data/omouas-restart.txt. Note that the file will be deleted to prevent infinite restarts.

Another way to restart is by calling method Server/Restart over OPC UA connection.