OPC-UA Integration with Cumulocity IoT, OPC UA Server configuration
OPC UA Server
In this article, I will focus on the options to configure the OPC UA Server at the OPC UA Gateway. Most standard OPC UA Server connection configurations can be done via UI see OPC UA Server connection. However, there are a few expert configurations that are not available at UI and can be done via REST API.
Advanced Configuration via REST API
OPC UA Server can also be created and updated via REST API. This option allows more configuration possibilities and can also be used to automate onboarding of OPC UA servers.
POST {{url}}/service/opcua-mgmt-service/gateways/{{gatewayId}}/servers
PUT {{url}}/service
Request Body
{ "name": "OPC UA Example Server", "config": { "securityMode": "NONE", "keystorePass": null, "certificatePass": null, "serverUrl": "opc.tcp://localhost:4840", "userIdentityMode": "Anonymous", "userName": null, "passwordEncrypted": null, "keystoreBinaryId": null, "rescanCron": null, "timeout": 30, "autoReconnect": true, "statusCheckInterval": 30, "targetConnectionState": "enabled", "targetUpdateState": false, "autoScanAddressSpace": true, "subscribeModelChangeEvent": false, "maxResponseMessageSize": 50000000, "cyclicReadBulkSize": 1000, "alarmSeverityMappings": null, "alarmStatusMappings": null } }
The following attributes can be set by UI and need to be set to connect the OPC UA client to the OPC UA server with a specific security mode and policy. These attributes will not be discussed in this article.
“securityMode”
“keystorePass”
“certificatePass”
“serverUrl”
“userIdentityMode”
“userName”
“passwordEncrypted”
“keystoreBinaryId”
“timeout”
“statusCheckInterval”
The following attributes will be handled in this article.
“rescanCron”
“autoReconnect”
“autoScanAddressSpace”
“subscribeModelChangeEvent”
“maxResponseMessageSize”
“cyclicReadBulkSize”
“alarmSeverityMappings”
“alarmStatusMappings”
rescanCron
Type: Cron expression
Description: Example: 0 0 */1 * * ?. This would mean, address space scan operation is going to be executed each full hour. If no Cron expression is set, no frequent address space scan will be performed.
Default value: null (not set)
Hint: Needed if the address space of the Server changes regularly and those changes must also be reflected in the Cumulocity platform. Be aware that the process of address space scan can take a while. The frequency configured should fit the duration of the scan. However, it is not recommended to have a high frequent address space scan! If OPC UA server supports model change events it is recommended to use subscribModelChangeEvent: true instead, see below.
autoReconnect
Type: Boolean
Description: Whether the gateway should try to reconnect to the OPC UA server once the connection drop is detected.
Default value: true
autoScanAddressSpace
Type: Boolean
Description: true value means that If the OPC UA Server is the first time connected an address space operation will be automatically created. Otherwise, false, no address space scan operation will be created. In case of not defined null OPC UA Gateway configuration will be taken, gateway.operation.autoScanAddressSpace. The default value of that property is “true”.
Default value: true
Hint: It is recommended to set this to true. However, if the address space of the Server is too huge and the address space scan takes too long, this can be set to “false”. It is important to know that most convenience functions in UI are based on the address space stored in Cumulocity and will not work if the operation isn’t executed successfully.
subscribeModelChangeEvent
Type: Boolean
Description: The subscription to model change events can be enabled/disabled using this property. Default value is false (disabled), which means any change in the address space nodes of the OPC UA server in runtime will not automatically be updated in the address space of Cumulocity IoT. This property must be explicitly set to true to detect and persist the address space changes on runtime.
Default value: false
Hint: If the OPC UA Server creates such model change events it is recommended to use this event-driven approach instead of rescanCron. However, many OPC UA Server doesn’t implement this event, so it will not work with all OPC UA Servers!
maxResponseMessageSize
Type: Integer
Description: Define the maximum size, in bytes, for the body of any response message from the server.
Default value: 50.000.000 (50 MB)
Hint: To make this unlimited, set it to 0. This configuration is interesting if large data like log files or software images are read from nodes.
cyclicReadBulkSize
Type: Integer
Description: For cyclic reads, this defines how many nodes can be read at once from the OPC UA server. This is applicable only for nodes resulting from the application with the same device type, matching root node, and sharing the same reading parameters (rate and max age).
Default value: 1000 defined in the application YAML file.
alarmSeverityMappings
Type: Map
Description: “Alarm severity mappings from the OPC UA event severity (1 - 1000) to the Cumulocity IoT alarm severity (CRITICAL, MAJOR, MINOR, WARNING).
This is applicable only for UAAlarmCreation. The key of this map is the lower bound value of the OPC UA event severity in the range. The value of this map is the expected severity of the alarm being created. For example, to map the OPC UA severity of the range 200-400 to a MINOR Cumulocity IoT alarm put this entry to the map: "200": "MINOR" .
If this is given, it will override the alarm severity mappings that are specified in the configuration YAML file.
Note that, if the severity field for alarm mapping is provided, this alarmSeverityMappings will have no effect.” see online Documentation
Default value:
801: CRITICAL 601: MAJOR 401: MINOR 1: WARNING
Hint:: Example, the following mapping is needed:
| Cumulocity Alarm severity | OPC UA Server severity |
|---------------------------|------------------------|
| CRITICAL | 801 – 1000 |
| MAJOR | 601 – 800 |
| MINOR | 301 – 600 |
| WARNING | 1 – 300 |
To implement this mapping, the server configuration must look like that:
"alarmSeverityMappings": {
"801": "CRITICAL",
"601": "MAJOR",
"301": "MINOR",
"1": "WARNING" }
Additionally, the Severity attribute should be added in the subscribed attributes (uaEventMappings → attributes) in the device type in order to get the severity value of the OPC UA event.
alarmStatusMappings
Type: Map
Description: “The status of an alarm in Cumulocity IoT is defined by multiple conditions on OPC UA servers. For example, if the value of AcknowledgedState node is “Acked” and ConfirmedState is “Confirmed”, then the status of the alarm in Cumulocity IoT is expected as ACKNOWLEDGED. They might vary with different servers as well. This field enables the user to configure the desired conditions (based on the information retrieved from the event type nodes of the OPC UA server) while creating alarms via UA event mappings (this is not applicable for OPC UA data value alarm creation). The example below shows that the keys of the map are the user-defined expressions and the value represents their corresponding desired status of the alarm. The variables that can be used in the expressions are the selected attributes provided in the subscription definition of the device type. It can be written down either by using the relevant node names (for example EnabledState.text == 'Enabled' ), or the qualified browse name with namespace index (for example ['0:EnabledState'].text == 'Enabled' ). If the variables are not provided in the subscribed attributes (uaEventMappings → attributes), they are considered null. If the alarm status is explicitly provided in the alarm mapping (uaEventMappings → alarmCreation) of the device type, these alarm status mappings have no effect. The Spring Expression Language(SpEL) has been used to parse these conditions, but only Boolean expressions are allowed.” see online Documentation
Hint: Examples
Example 1
The OPC UA server uses ActiveState and AckedState text to define the status of the alarm.
"alarmStatusMappings": { "['0:ActiveState'].text == 'Active' and ['0:AckedState'].text != 'Acknowledged'": "ACTIVE", "['0:ActiveState'].text == 'Active' and ['0:AckedState'].text == 'Acknowledged'": "ACKNOWLEDGED", "['0:ActiveState'].text == 'Inactive'": "CLEARED" }
Example 2
The OPC UA server uses ActiveState and AckedState id to define the status of the alarm.
"alarmStatusMappings": { "['ActiveState/Id'] == true and ['AckedState/Id'] == false": "ACTIVE", "['ActiveState/Id'] == true and ['AckedState/Id'] == true": "ACKNOWLEDGED", "['ActiveState/Id'] == false": "CLEARED" }