OPC UA Guide

Overview

ControlBird's OPC UA (OPC Unified Architecture) integration provides bidirectional connectivity to industrial OPC UA servers and can expose ControlBird entities as OPC UA nodes for other clients to consume. The integration has two halves: a client that connects to external servers to browse, read, write, and subscribe to nodes, and a server that publishes ControlBird data into its own address space.

Everything is configured through the Device Manager app in the Platform UI using controller, endpoint, and mapper entities. No manual configuration files are required. Where security is enabled, endpoints reference a Certificate entity from the Certificate Manager.

Architecture

OPC UA follows ControlBird's standard protocol controller/mapper pattern. The client and server sides each have their own controller, endpoint, and mapper entity types:

Node IDs and addressing

OPC UA nodes are addressed by a NodeId string. ControlBird accepts the standard numeric and string forms, and falls back to namespace 0 for a bare identifier:

Client configuration

The client connects to a remote OPC UA server, discovers its address space, and keeps a set of mapped nodes in sync with ControlBird entities.

1. Create the controller

In Device Manager, create an OpcUaClientController with a Name, optional Description, and an EndpointConnectionMode (default LeaderOnly). Use BrowseMaxResults (default 1000) to cap how many nodes a single browse call returns.

2. Configure the endpoint

Add an OpcUaEndpoint child describing the remote server connection:

Authentication is either Anonymous or username/password identity tokens. When SecurityPolicy is anything other than None, reference a Certificate entity and the OPC UA service handles the certificate material for you.

3. Add mappers

Create OpcUaMapper entities as children of the controller. Each mapper binds one remote node to a target entity field:

Read mapper:
  Direction          = Read
  SourcePath         = ns=2;i=100
  TargetEntity       = [DeviceEntity]
  TargetField        = Temperature
  ReadMode           = Subscribe
  SamplingIntervalMs = 500

Write mapper:
  Direction    = Write
  SourcePath   = ns=2;i=101
  TargetEntity = [DeviceEntity]
  TargetField  = Setpoint

4. Browse the address space

Use the Device Manager browse UI to discover nodes on a connected endpoint. Discovery uses the controller's first candidate OpcUaEndpoint for connection parameters and returns up to BrowseMaxResults nodes per call.

Server configuration

The server side exposes ControlBird entities as OPC UA variable nodes so external SCADA and HMI clients can read them.

1. Create the controller and endpoint

Create an OpcUaServerController, then add an OpcUaServerEndpoint child:

2. Add server mappers

Create OpcUaServerMapper entities as children of the server controller. Set Direction to Get, a SourcePath identifier, the TargetEntity and TargetField to expose, and a BrowsePath that places the node in the address space. The NodeId is generated from the SourcePath.

Server mapper:
  Direction    = Get
  BrowsePath   = Devices/Motor1/Speed
  TargetEntity = [MotorEntity]
  TargetField  = Speed

The server starts automatically when the controller is enabled. It creates a ControlBird folder inside the standard Objects folder (ns=0;i=85) and dynamically adds variable nodes for each registered mapper. Browse paths auto-create the folder hierarchy, so Sensors/Temperature/Celcius produces nested Sensors and Temperature folders with a Celcius variable node.

Security and certificates

For any policy other than None, link a Certificate entity to the endpoint's Certificate field. The certificate and key are managed for you from the linked Certificate Manager entity, including across reconnects.

A common production configuration pairs MessageSecurityMode = SignAndEncrypt with SecurityPolicy = Basic256Sha256.

Data types

OPC UA Variant values are converted to ControlBird Value types and back. Supported scalar conversions are Bool, Int, Float, String, Blob (byte string), and Timestamp. OPC UA DateTime uses 100-nanosecond ticks since 1601-01-01.

Operational notes

• The default OPC UA port is 4840 for both client and server.
• Endpoint connections retry up to 3 times with configurable backoff bounds.
• Subscription delivery is decoupled from the protocol session, so a slow consumer does not stall data coming from the server.
• The communication logger records logical operations (node reads, writes, and subscription events) rather than raw network traffic.

For a step-by-step introduction to connecting devices, see the configuration walkthrough.