OPC UA Server

Configure Connectware as an OPC UA server to expose data to OPC UA clients.

Connectware can act as an OPC UA server, exposing data to OPC UA clients. For OPC UA client functionality, see OPC UA Client.

For configuration reference, see:

• OPC UA Server Properties

• OPC UA Node Properties

Configuration

Define a server resource of type Cybus::Server::Opcua in your service commissioning file. OPC UA clients can connect to this server using:

opc.tcp://<connectwareHost>:4841<resourcePath>

Port configuration

Connectware uses port 4841 instead of the standard OPC UA port 4840 to avoid conflicts with other OPC UA servers. Only one OPC UA server instance can run per Connectware installation.

If Connectware is accessible via DNS hostname, specify this hostname in the hostname property to allow connections from outside the Docker network. Do not use localhost as it only refers to the local container.

The resourcePath property defines the connection string prefix and defaults to /UA/CybusOpcuaServer. This path must be included in the connection URL for clients to connect successfully.

Node Structure

Define data points as Cybus::Node::Opcua resources. Nodes form a tree hierarchy:

• One root node with its parent property referencing the server.

• All other nodes reference the root node or intermediate nodes as parent.

Nodes can be defined in the same service as the server or in separate services using service-id references. This allows adding or removing nodes dynamically by commissioning additional services.

Security Settings

For production environments, only use the SignAndEncrypt security profile. Other profiles allow communication to be intercepted or manipulated. By default, the OPC UA server only permits SignAndEncrypt connections (configured in securityModes).

Authenticate using Connectware username and password credentials via user token.

CA Certificate

When an OPC UA client connects to the server, it verifies that the server certificate was signed by a CA it trusts. The caFile property tells the OPC UA server which CA certificate to use for this.

Connectware ships with its own CA and a matching server certificate. The caFile property defaults to /connectware_certs/cybus_ca.crt, which Connectware places automatically. If you are using the default Connectware certificates, you do not need to configure caFile.

If you are using your own PKI — that is, you have supplied your own certificateFile and privateKeyFile signed by your organization's CA — you must also set caFile to the path of your CA certificate inside the container. Alternatively, you can manually place the CA certificate in /app/.config/node-opcua-default-nodejs.

Service Commissioning File Example

4KB

opcua-server-example.yml

Open

opcua-server-example.yml

---
description: >

  This is a fixture showing server resource functionality

metadata:
  name: OPC UA Server example
  version: 1.0.0
  icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom1.svg
  provider: cybus
  homepage: https://www.cybus.io

parameters:
  influxPort:
    type: integer
    default: 8086
    title: Influx Database Port

  retentionTime:
    type: integer
    default: 356
    title: Retention Time

definitions:
  databaseName: opcuaHistory

resources:
  influxdb:
    type: Cybus::Container
    properties:
      image: influxdb:1.8-alpine
      ports:
        - !sub '${influxPort}:8086/tcp'
      volumes:
        - !sub '${influxdbVolume}:/var/lib/influxdb'
      environment:
        INFLUXDB_DB: !ref databaseName
        INFLUXDB_HTTP_FLUX_ENABLED: true

  influxdbVolume:
    type: Cybus::Volume

  opcuaServer:
    type: Cybus::Server::Opcua
    properties:
      database:
        host: 172.17.0.1
        name: !ref databaseName
        retention: !ref retentionTime
      allowAnonymous: false
      certificateFile: /connectware_certs/cybus_server.crt
      privateKeyFile: /connectware_certs/cybus_server.key

  parentNodeRoot:
    type: Cybus::Node::Opcua
    properties:
      browseName: parentNodeRoot
      nodeId: ns=1;s=parentNodeRoot
      parent: !ref opcuaServer
      nodeType: Object

  parentNode1:
    type: Cybus::Node::Opcua
    properties:
      browseName: parentNode1
      nodeId: ns=1;s=parentNode1
      parent: !ref parentNodeRoot
      nodeType: Object

  parentNode2a:
    type: Cybus::Node::Opcua
    properties:
      browseName: parentNode2a
      nodeId: ns=1;s=parentNode2a
      parent: !ref parentNode1
      nodeType: Object

  parentNode2b:
    type: Cybus::Node::Opcua
    properties:
      browseName: parentNode2b
      nodeId: ns=1;s=parentNode2b
      parent: !ref parentNode1
      nodeType: Object

  dataNodeRoot1:
    type: Cybus::Node::Opcua
    properties:
      browseName: dataNodeRoot1
      nodeId: ns=1;s=dataNodeRoot1
      parent: !ref parentNodeRoot
      nodeType: Variable
      operation: serverProvides
      dataType: Boolean

  dataNodeRoot2:
    type: Cybus::Node::Opcua
    properties:
      browseName: dataNodeRoot2
      nodeId: ns=1;s=dataNodeRoot2
      parent: !ref parentNodeRoot
      nodeType: Variable
      operation: serverReceives
      dataType: DateTime

  dataNodeRoot3:
    type: Cybus::Node::Opcua
    properties:
      browseName: dataNodeRoot3
      nodeId: ns=1;s=dataNodeRoot3
      parent: !ref parentNodeRoot
      nodeType: Variable
      initialValue: 42.0
      operation: serverProvidesAndReceives
      dataType: Float
      historize: true

  dataNode1:
    type: Cybus::Node::Opcua
    properties:
      browseName: dataNode1
      nodeId: ns=1;s=dataNode1
      parent: !ref parentNode1
      nodeType: Variable
      operation: serverReceives
      dataType: Int32

  dataNode2a:
    type: Cybus::Node::Opcua
    properties:
      browseName: dataNode2a
      nodeId: ns=1;s=dataNode2a
      parent: !ref parentNode2a
      nodeType: Variable
      operation: serverProvides
      dataType: Double
      historize: true

  dataNode2b:
    type: Cybus::Node::Opcua
    properties:
      browseName: dataNode2b
      nodeId: ns=1;s=dataNode2b
      parent: !ref parentNode2b
      nodeType: Variable
      operation: serverProvides
      dataType: String

  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - publish:
            topic: my/opcuaData/dataNode1
          subscribe:
            endpoint: !ref dataNode1

        - publish:
            endpoint: !ref dataNode2a
          subscribe:
            topic: my/opcuaData/dataNode2a

Output Format

If the server receives data from an external OPC UA client, the output on the internal MQTT broker is provided as a JSON object:

{ "timestamp": "<unix timestamp in ms>", "value": "<value>" }

Input Format

To provide data to an external OPC UA client, publish the message to the internal MQTT broker in this format:

{ "value": "<value>" }

{hint style="warning"} When using 64-bit integers — which JSON does not support but JavaScript does via BigInt — pass the value as a string containing the decimal number.

OPC UA Method Implementation

OPC UA methods can only be implemented on servers when used in conjunction with FlowSync.

When configured in transaction mode, Cybus::Nodes handle operations differently than standard variable nodes. Any node with the setting operation: transaction follows this workflow:

1. Publishes request data to the /treq topic.

2. Waits to receive a response on the /tres topic before proceeding.

Example

The following example configuration is taken from FlowSync Example 6.

opcuaServer:
  type: Cybus::Server::Opcua
  properties:
    hostname: 127.0.0.1
    allowAnonymous: true
    securityPolicies: ['None']
    securityModes: ['None']

rootNode:
  type: Cybus::Node::Opcua
  properties:
    browseName: Cybus
    nodeId: ns=1;s=Cybus
    parent: !ref opcuaServer
    nodeType: Object

getIpForDomainNode:
  type: Cybus::Node::Opcua
  properties:
    topic: getIpForDomain
    browseName: getIpForDomain
    nodeId: ns=1;s=getIpForDomain
    parent: !ref rootNode
    nodeType: Method # mark node as method
    operation: transaction # activate FlowSync
    inputArguments:
      - name: domain
        dataType: String
        description: the domain to resolve
    outputArguments:
      - name: ip
        dataType: String
        description: the IP address of the domain

Request Data Structure

When a method is called, it publishes request details to the /treq topic in the following format:

• Each request contains a unique id for tracking.

• The response must include this same id to complete the flow.

Example

The data structure matches the format shown in FlowSync Example 6.

{
  "id": "b9cc7c92-1f8c-4f00-8871-945a858ec3f8",
  "timestamp": 1738332862812,
  "value": {
    "browseName": "getIpForDomain",
    "nodeId": "ns=1;s=getIpForDomain",
    "inputArguments": [
      {
        "dataType": "String",
        "arrayType": "Scalar",
        "value": "cybus.io"
      }
    ]
  }
}

Response Data Format

Each method call must receive a corresponding response published to the /res topic.

Example

In the FlowSync Example 6, the response will look like this:

{
  "id": "b9cc7c92-1f8c-4f00-8871-945a858ec3f8",
  "timestamp": 1738332862983,
  "value": {
    "outputArguments": [
      {
        "value": "18.195.30.255"
      }
    ]
  }
}

Error Response Format

To return an error response from a node, you must include an error property containing the appropriate error code. This code will be used in the method call response. Note that any error.message provided will be ignored.

Example

{
  "id": "b9cc7c92-1f8c-4f00-8871-945a858ec3f8",
  "timestamp": 1738332862983,
  "error": {
    "message": "Domain Not Found",
    "code": "BadNotFound"
  }
}