LogoLogo
Contact Uscybus.io
Connectware 1.11.0
Connectware 1.11.0
  • Getting Started
    • Introduction
    • System Requirements
    • Connectware Admin UI
    • Basic Components of Connectware
    • Connecting your First Machine
      • Your First Service Commissioning File
  • Documentation
    • Installation and Upgrades
      • Installing Connectware
        • Installing Connectware (Kubernetes)
        • Installing Connectware (Docker)
      • Upgrading Connectware
        • Upgrading Connectware (Kubernetes)
          • Version-Specific Upgrades (Kubernetes)
        • Upgrading Connectware (Docker)
          • Version-Specific Upgrades (Docker)
      • Uninstalling Connectware
        • Uninstalling Connectware (Kubernetes)
        • Uninstalling Connectware (Docker)
      • Licensing
      • Restarting Connectware
    • User Management
      • Users and Roles View
      • Users
      • Roles
      • Permissions
      • Password Policy Rules
      • Default Admin User
      • MQTT Users
      • Adding a MQTT Publish Prefix for Users
      • Multi-Factor Authentication
      • Single Sign-On (SS0)
        • Single Sign-On with Microsoft Entra ID
        • Single Sign-On with LDAP
      • JSON Web Tokens
      • Access Permissions for Admin-UI
        • UI Access
        • Minimum Access Role Pages
    • Services
      • Service Overview
      • Service Resources View
        • Service Links View
        • Servers View
        • Containers View
        • Volumes View
        • Connections View
        • Endpoints View
        • Mappings View
      • Service Details View
      • Service Commissioning Files
        • Version
        • Description
        • Metadata
        • Parameters
        • Definitions
        • Resources
          • Cybus::Connection
          • Cybus::Container
            • Docker Problem with Network Changes
          • Cybus::Endpoint
          • Cybus::File
          • Cybus::IngressRoute
          • Cybus::Link
          • Cybus:Mapping
          • Cybus::Node
          • Cybus::Role
          • Cybus::Server
          • Cybus::User
          • Cybus::Volume
      • Setting Up and Configuring Services
        • Installing Services
        • Enabling Services
        • Updating Services
        • Disabling Services
        • Deleting Services
      • FlowSync
        • Example 1 - Node with Transaction Mode (HTTP)
        • Example 2 - Node Responds (HTTP)
        • Example 3 - Node with Error (HTTP)
        • Example 4 - Node with Timeout Error Code and Error Message (HTTP)
        • Example 5 - Full Transactional Data Flow (HTTP)
        • Example 6 - Full Transactional Data Flow (OPC UA)
      • ServiceID
      • Inter-Service Referencing
      • Deviations
      • Service Logs
        • Logs of Individual Services
        • Logs of All Services
      • Rule Engine
        • Data Processing Rules
        • Rule Sandbox
      • Shared Subscriptions
        • Setting Up Shared Subscriptions
    • Agents
      • Agents View
      • Installing Agents
        • Installing Agents via Docker
        • Installing Agents via Docker Compose
        • Installing Agents via Kubernetes
        • Using Mutual TLS for Agents
      • Registering Agents in Connectware
      • Using Agents
      • Monitoring Agents
      • Agents in Kubernetes
        • Adding Agents Inside your Connectware Installation
        • Remote Agents with the connectware-agent Helm Chart
        • Kubernetes Cluster Requirements for the connectware-agent Helm Chart
        • Installing Connectware Agents using the connectware-agent Helm Chart
        • Installing Connectware Agents without a License Key Using the connectware-agent Helm Chart
        • Upgrading the connectware-agent Helm Chart
        • Uninstalling Connectware agents with the connectware-agent Helm chart
        • Configuration Principles for the connectware-agent Helm Chart
        • Configuring Agents with the connectware-agent Helm Chart
          • Configuring Target Connectware for the connectware-agent Helm Chart
          • Configuring Agent Persistence for the connectware-agent Helm Chart
          • Configuring Compute Resources for the connectware-agent Helm Chart
          • Using a Custom Image Registry for the connectware-agent Helm Chart
          • Configuring Image Pull Policy for the connectware-agent Helm Chart
          • Using Mutual Transport Layer Security (mTLS) for agents with the connectware-agent Helm chart
          • Configuring image name and version for the connectware-agent Helm chart
          • Configuring Environment Variables for the connectware-agent Helm Chart
          • Configuring Labels and Annotations for the connectware-agent Helm Chart
          • Configuring podAntiAffinity for the connectware-agent Helm Chart
          • Assigning Agents to Kubernetes Nodes for the connectware-agent Helm Chart
          • Configuring Security Context for the connectware-agent Helm Chart
          • Controlling the Name of Kubernetes Objects for the connectware-agent Helm Chart
      • Troubleshooting Agents
    • Client Registry
      • Implicit Flow
      • Explicit Flow
      • Granting Access
    • Certificates
      • Certificates View
      • Adding Certificates
      • Removing Certificates
    • Monitoring
      • Data Explorer
      • Live Data
    • Node-RED Workbench
    • System Status
      • Info
      • Metrics
      • Status
      • Retrieving More System Information
      • System Health
    • Backup and Restore
      • Volumes
      • User Database
    • CybusMQ
      • Configuring CybusMQ
    • Connectware on Kubernetes
      • Connectware Helm Chart
      • Resizing Broker Volumes in Kubernetes
      • Configuring Core Services
      • LDAP Authentication
        • Configuring LDAP Authentication
        • Enabling TLS for LDAP Authentication
        • Manual Kubernetes Secret for LDAP Authentication Bind User
        • Customizing the Search Filter for LDAP Authentication
        • Customizing the User RDN for LDAP Authentication
      • Troubleshooting Connectware on Kubernetes
    • Environment Variables
    • Industry Protocol Details
      • ADS
        • ADS Connection Properties
        • ADS Endpoint Properties
      • BACnet
        • BACnet Connection Properties
        • BACnet Endpoint Properties
      • Custom Connectors
        • Developing Custom Connectors
        • Deploying Custom Connectors
        • Using Custom Connectors
      • EtherNet/IP
        • EtherNet/Ip Connection Properties
        • EtherNet/Ip Endpoint Properties
      • FOCAS
        • FOCAS Connection Properties
        • FOCAS Endpoint Properties
      • Hottinger Baldwin Messtechnik (HBM)
        • HBM Connection Properties
        • HBM Endpoint Properties
      • Heidenhain DNC
        • Heidenhain DNC Connection Properties
        • Heidenhain DNC Endpoint Properties
      • HTTP/REST
        • HTTP/REST Connection Properties
        • HTTP/REST Endpoint Properties
      • HTTP Server/Node
        • HTTP Server Properties
        • HTTP Node Properties
      • InfluxDB
        • InfluxDB Connection Properties
        • InfluxDB Endpoint Properties
      • Kafka
        • Kafka Connection Properties
        • Kafka Endpoint Properties
      • Modbus/TCP
        • Modbus/TCP Connection Properties
        • Modbus/TCP Endpoint Properties
      • MQTT
        • MQTT Connection Properties
        • MQTT Endpoint Properties
      • MSSQL
        • Mssql Connection Properties
        • Mssql Endpoint Properties
      • OPC DA
        • OPC DA Connection Properties
        • OPC DA Endpoint Properties
      • OPC UA
        • OPC UA Client
          • OPC UA Client Connection Properties
          • OPC UA Client Endpoint Properties
        • OPC UA Server
          • OPC UA Server Properties
          • OPC UA Node Properties
        • OPC UA Object Types
        • OPC UA Server References
          • OPC UA Reference Node
          • OPC UA Object Node
      • Siemens SIMATIC S7
        • Siemens S7 Connection Properties
        • Siemens S7 Endpoint Properties
      • Shdr
        • Shdr Connection Properties
        • Shdr Endpoint Properties
      • SINUMERIK
        • SINUMERIK Connection Properties
        • SINUMERIK Endpoint Properties
      • SOPAS
        • SOPAS Connection Properties
        • SOPAS Endpoint Properties
      • SQL
        • SQL Connection Properties
        • SQL Endpoint Properties
      • Werma WIN Ethernet
        • Werma WIN Ethernet Connection Properties
        • Werma WIN Ethernet Endpoint Properties
      • Systemstate
        • Systemstate Endpoint Properties
    • API Reference
      • User Management (API)
      • Client Registry (API)
      • Services (API)
      • Resources (API)
      • System Status (API)
      • Resource Status Tracking (HTTP API)
      • Industry Protocol Details (API)
    • Changelog
Powered by GitBook
LogoLogo

Cybus

  • Terms and Condition
  • Imprint
  • Data Privacy

© Copyright 2025, Cybus GmbH

On this page
  • OPC UA Subscriptions
  • Connectware Subscriptions
  • Subscription Limitations
  • Example
  • Service Commissioning File Example
  • Basic example
  • Advanced Example
  • Example with Method Endpoint
  • Output Format On Reading
  • Output Format On Writing
  • Variables
  • Method Calls
  • Input Format
  • Variables
  • Method Calls
  • Reconnection Behaviour
  • Events for OPC UA
  • Accessing Status Codes for Values

Was this helpful?

  1. Documentation
  2. Industry Protocol Details
  3. OPC UA

OPC UA Client

PreviousOPC UANextOPC UA Client Connection Properties

Last updated 2 months ago

Was this helpful?

This page describes how Connectware can act as an OPC UA client. Connectware can also act as an .

For more information on UPC UA, see the .

OPC UA Subscriptions

OPC UA distinguishes between session, subscriptions and monitored items.

  • Each Connectware connection creates exactly one session in the OPC UA terminology, where Connectware acts as a client towards the server.

  • Within one session, the set of data endpoints are grouped in subscriptions. A subscription carries parameters like publishInterval and maxNotificationsPerPublish so that it controls the data flow between server and client.

  • Within each subscription, the actual data endpoints (also called nodes) are subscribed as monitored items. The monitored items are configured by parameters like nodeId, attributeId, samplingInterval, so monitored items control the collection of the data by the server. Each network request for creating these can create one or multiple monitored items per request.

Connectware Subscriptions

Connectware tries to abstract this complexity away, combining as many endpoints as possible into the same subscription, and also monitored items creation into the same request. This is done according to the following criteria:

  • Each OPC UA Cybus::Connection resource creates exactly one session

  • Within this session, all OPC UA Cybus::Endpoint resources with the same publishInterval property are combined into one subscription. This holds even across different service commissioning files using inter-service referencing, see . Hence, enabling/disabling additional services with additional endpoints will add or remove those endpoints from the currently available subscription.

  • Every OPC UA Cybus::Endpoint resource corresponds to one monitored item

  • Within one subscription and within the same service commissioning file, all endpoints (= monitored items) with the same samplingInterval property are combined into one common creation request. This “create monitored items request” is working very efficiently also for thousands of monitored items.

Subscription Limitations

Some OPC UA servers are known for imposing certain limits on the number of monitored items, either in total, or per subscription, or per request.

  • For example, the maximum number of monitored items within one “create monitored items request” might limited to e.g. 1000 nodes. This limit can even be looked up in the OPC UA node with nodeId ns=0;i=11714. On Connectware side this limit must be taken into account by setting the property maxMonitoredItemsPerCall in the Cybus::Connection resource to the respective value. This will ensure to split larger requests so that all requests stay within this limit.

  • Also, some maximum number of monitored items in total might be configured in the TIAPortal project. Unfortunately it is not known how to look up this value except directly in TIAPortal. If such a value is set, it is not possible for Connectware to create any larger number of endpoints than this value.

Regarding the created subscriptions: As of today, subscriptions are combined only by the publishInterval parameter. The remaining properties related to subscriptions are currently taken only from the first endpoint to be subscribed, while differing settings at subsequent endpoints are currently ignored. This concerns the following endpoint properties: requestedLifetimeCount, requestedMaxKeepAliveCount, maxNotificationsPerPublish, priority.

Example

This is an example configuration snippet with three endpoints (without the connection configuration):

resources:
    spindleSpeed:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            subscribe:
                nodeId: 'ns=1;s=spindleSpeed'
                publishInterval: 1000
                samplingInterval: 100
                maxNotificationsPerPublish: 100
    powerConsumption:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            subscribe:
                nodeId: 'ns=1;s=powerConsumption'
                publishInterval: 1000
                maxNotificationsPerPublish: 50
                samplingInterval: 1000
    temperature:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            subscribe:
                nodeId: 'ns=1;s=temperature'
                publishInterval: 15000
                samplingInterval: 15000

In the above example, two subscriptions will be created. One with publishInterval set to 1000ms and maxNotificationsPerPublish set to 100, the other one with publishInterval set to 15.000ms. The sampling of the individual source values will be set as expected by the specified samplingInterval property, but remember that OPC UA does not offer a fixed data sampling but rather applies a change-of-value filter to each particular data point automatically.

Service Commissioning File Example

Basic example

This is a simple OPC UA connectivity example that only subscribes to the “Server Status” node of an OPC UA server. The proposed node (endpoint) can also be used if the server would otherwise close the connection, which has been observed for some specific versions of OPC UA servers on a S7 PLC.

The example will need some OPC UA server available in your network:

---
description: >

    Simple OPC UA connectivity example

metadata:
    name: Simple OPC UA connectivity
    version: 1.0.0
    icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg
    provider: cybus
    homepage: https://www.cybus.io

parameters:
    opcuaHost:
        type: string
        description: OPC-UA Host
        default: 172.17.0.1

    opcuaPort:
        type: integer
        default: 4840

    opcuaUser:
        type: string
        default: ''

    opcuaPass:
        type: string
        default: ''

resources:
    opcuaConnection:
        type: Cybus::Connection
        properties:
            protocol: Opcua
            connection:
                host: !ref opcuaHost
                port: !ref opcuaPort
                username: !ref opcuaUser
                password: !ref opcuaPass

    serverStatusEndpoint:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            subscribe:
                nodeId: ns=0;i=2259
                samplingInterval: 2000

Advanced Example

More complex example including an OPC UA server container from public docker hub:

---
description: >

    Simulated OPC UA server

metadata:
    name: Simulated OPC UA
    version: 1.0.1
    icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg
    provider: cybus
    homepage: https://www.cybus.io

parameters:
    opcuaHost:
        type: string
        description: OPC-UA Host
        default: 172.17.0.1

    opcuaPort:
        type: integer
        default: 50000

    opcuaUser:
        type: string
        default: user

    opcuaPass:
        type: string
        default: user

definitions:
    CYBUS_MQTT_ROOT: cybus-factory/opcua

resources:
    machineSimulatorContainer:
        type: Cybus::Container
        properties:
            image: mcr.microsoft.com/iotedge/opc-plc
            ports:
                - !sub '${opcuaPort}:50000/tcp'
            command:
                - --unsecuretransport
                - --autoaccept
                - --defaultuser=user
                - --defaultpassword=user

    opcuaConnection:
        type: Cybus::Connection
        properties:
            protocol: Opcua
            connection:
                host: !ref opcuaHost
                port: !ref opcuaPort
                username: !ref opcuaUser
                password: !ref opcuaPass

    currentTime:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: server/status/currenttime
            subscribe:
                nodeId: i=2258

    dipData:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: dip-data
            subscribe:
                nodeId: ns=2;s=DipData

    alternatingBool:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: alternating-bool
            subscribe:
                nodeId: ns=2;s=AlternatingBoolean

    negativeTrendData:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: negative-trend-data
            subscribe:
                nodeId: ns=2;s=NegativeTrendData

    positiveTrendData:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: positive-trend-data
            subscribe:
                nodeId: ns=2;s=PositiveTrendData

    randomSignedInt:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: random-signed-int32
            subscribe:
                nodeId: ns=2;s=RandomSignedInt32

    randomUnsignedInt:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: random-unsigned-int32
            subscribe:
                nodeId: ns=2;s=RandomUnsignedInt32

    spikeData:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: spike-data
            subscribe:
                nodeId: ns=2;s=SpikeData

    stepUp:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            topic: step-up
            subscribe:
                nodeId: ns=2;s=StepUp

Example with Method Endpoint


description: OPC UA method endpoint

metadata:
  name: opcua-method-endpoint
  version: 1.0.0

resources:

opcuaConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      connection: # opc.tcp://opcuaserver.com:48010
        host: opcuaserver.com
        port: 48010

  multiplyEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref opcuaConnection
      publishError: true # will let the endpoint always publish error an error object that contains 'message' and error 'code' when an error occurs
      write:
        nodeId: ns=2;s=Demo.Method.Multiply
        nodeType: Method # mark that endpoint as method

Output Format On Reading

If data is read from OPC UA the output will be provided as JSON object with value and timestamp.

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

Note: If 64-bit integers are being used (which are unsupported in JSON, but are supported in Javascript by the BigInt class), the value is returned as a string that contains the decimal number.

Output Format On Writing

Variables

When data is written to an OPC-UA endpoint, you will get the result of the operation over the /res topic like this:

{ "id": "29194", "timestamp": 1629351968526, "result": { "value": 0 } }

Method Calls

Method calls follow the same pattern as variable operations:

  1. Write the method call data to the /set topic.

  2. Receive the result on the /res topic.

Example

{
    "id": "1234",
    "timestamp": 1738323576339,
    "value": {
        "outputArguments": [
            {
                "value": 42,
                "dataType": "Double",
                "arrayType": "Scalar"
            }
        ]
    }
}

Input Format

Variables

When writing to an OPC UA variable, format the data as a JSON object.

{ "value": "<value>" }

Method Calls

Calling OPC UA methods follows the same pattern as writing to OPC UA variables.

The value has to include the input arguments like this. You can optionally include an id parameter.

{
    "id": "12345",
    "value": {
        "inputArguments": [
            {
                "value": 24
            },
            {
                "value": 2
            }
        ]
    }
}

Reconnection Behaviour

Example with initially 500ms waiting time, increasing up to 10 seconds:

resources:
    myConnection:
        type: Cybus::Connection
        properties:
            protocol: Opcua
            connection:
                host: !ref opcuaHost
                port: !ref opcuaPort
                options:
                    connectionStrategy:
                        initialDelay: 500
                        maxDelay: 10000

Events for OPC UA

Event subscriptions can be created in the connectware by adding the properties fields and eventTypes to the Cybus::Endpoint resource as shown in the example below.

The names for the fields should be Qualified Names. Often, this will require the field name to also contain a namespace identifier, for example 4:MyQualifiedName.3:SubitemQualifiedName. Also, the field names often additionally need a sub-type, which can be specified using a dot notation after the name.

---
description: >

    Simple OPC UA connectivity example

metadata:
    name: example for opcua connectivity
    version: 1.0.0
    icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg
    provider: cybus
    homepage: https://www.cybus.io

parameters:
    opcuaHost:
        type: string
        description: OPC-UA Host
        default: 172.17.0.1

    opcuaPort:
        type: integer
        default: 4840

    opcuaUser:
        type: string
        default: ''

    opcuaPass:
        type: string
        default: ''

resources:
    opcuaConnection:
        type: Cybus::Connection
        properties:
            protocol: Opcua
            connection:
                host: !ref opcuaHost
                port: !ref opcuaPort
                username: !ref opcuaUser
                password: !ref opcuaPass

    # Listen to all events from the server node
    # A list of eventTypes can be selected
    serverEventsEndpoint:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            subscribe:
                nodeId: i=2253
                eventTypes:
                    - 'i=85'
                fields:
                    - 'EventType'
                    - 'ReceiveTime'
                    - 'Message'
                    - 'SourceName'
                    - 'Severity'

Accessing Status Codes for Values

The quality of a data value in OPC UA is represented by predefined status codes. The `statusCode` is transferred to the `$context` object and can be retrieved within the Rule Engine of a Cybus::Endpoint via `$context.raw.statusCode` as shown in the example below.

description: OPC UA Status Code Example
metadata:
    name: OPC UA Status Code Example
    version: 1.0.0
parameters:
    ipAddress:
        type: string
    port:
        type: integer
        default: 4334
    samplingIntervalMs:
        type: number
        default: 1000
    publishIntervalMs:
        type: number
        default: 1000
resources:
    opcuaConnection:
        type: Cybus::Connection
        properties:
            protocol: Opcua
            connection:
                host: !ref ipAddress
                port: !ref port

    A_000:
        type: Cybus::Endpoint
        properties:
            protocol: Opcua
            connection: !ref opcuaConnection
            subscribe:
                nodeId: ns=1;s=0
                samplingInterval: !ref samplingIntervalMs
                publishInterval: !ref publishIntervalMs
            rules:
                - transform:
                      expression: |
                          { 
                            "statusCode": {
                              "name": $context.raw.statusCode.name,
                              "value": $context.raw.statusCode.value,
                              "description": $context.raw.statusCode.description
                            },
                            "value": $.value,
                            "timestamp": $.timestamp
                          }
            topic: A/000

In particular, an embedded OPC UA server on a Siemens S7-1500 or S7-1200 PLC is known for certain restrictions, see .

The given timestamp is the OPC UA “Source Timestamp” which was set on the data source side, see

In OPC UA connections – just with any network connections – it can happen that the connection is lost. In that case the Connectware’s OpcuaConnection will automatically switch into reconnecting state and repeatedly try to re-establish the connection. The exact behaviour on how often this is tried can be controlled by the optional connectionStrategy properties, see . The important property is maxDelay which sets the maximum waiting time (delay) between consecutive re-tries, in milliseconds. The waiting time will start with the value initialDelay, then be increased step by step, until the maxDelay value.

For further details see also the documentation of the internally used package backoff,

System limits of OPC UA Server
Connection Properties
Endpoint Properties
https://reference.opcfoundation.org/v104/Core/docs/Part4/7.7.3/
Connection Properties
https://www.npmjs.com/package/backoff
OPC UA server
OPC Foundation Reference
1KB
opcua-simple-example.yml
3KB
opcua-example.yml
3KB
opcua-client-method-example.yml
1KB
opcua-events-example.yml
1KB
opcua-statusCodes-example.yml
here