OPC UA Data Source

Since Mango 5.7

The OPC UA (Unified Architecture) data source connects Mango to OPC UA servers using the Eclipse Milo client library. OPC UA is the modern, platform-independent successor to OPC DA (Classic OPC), designed for secure, reliable industrial communication. It is widely used in manufacturing, process automation, energy systems, and building automation as a standard way to access real-time and historical process data.

Unlike the older OPC DA protocol, OPC UA does not depend on Microsoft DCOM, making it suitable for cross-platform deployments including Linux-based Mango installations.

Overview

Property	Value
Module	mangoAutomation-OpcUa
Protocol	OPC UA (over opc.tcp://)
Direction	Read + write
Typical Use	Industrial automation server integration

Prerequisites

• Network access to the OPC UA server. The default OPC UA port is 4840 over TCP.
• The server endpoint URL in the format opc.tcp://hostname:4840/path.
• Identity — anonymous, username/password, or X.509 client certificate, depending on what the server accepts.
• For secure connections — Mango auto-generates a client certificate on first connect; the OPC UA server administrator may need to move it from the server's rejected/ directory to its trusted/certs/ directory before the connection succeeds.

Connection settings

Setting	Description
Name	A descriptive name for the data source.
Server URL (endpointURL)	The OPC UA server endpoint URL, e.g., opc.tcp://192.168.1.100:4840/milo.
Timeout (clientTimeout)	Milliseconds to wait for both the connect handshake and the acknowledge phase. Default: 5000.

After entering the Server URL, click Fetch Endpoints to query the server's endpoint list. Each returned endpoint advertises a security policy, a security mode, and the identity providers it accepts. Pick the endpoint that matches your security requirements — its security policy and mode are filled into the form automatically.

Security policies

OPC UA supports six security policies. Mango selects one per data source:

Policy	Notes
None	No encryption or signing. Use for testing or fully-trusted networks.
Basic128Rsa15	Legacy, weak. Avoid except for compatibility with old servers.
Basic256	Legacy, weak.
Basic256Sha256	Widely supported, acceptable for production.
Aes128_Sha256_RsaOaep	Modern, OPC UA 1.04+.
Aes256_Sha256_RsaPss	Default. Strongest of the six.

Security modes

Mode	What it does
None	No protection. Only valid when policy is None.
Sign	Messages are signed but not encrypted. Confidentiality is NOT protected.
Sign and Encrypt	Default. Messages are both signed and encrypted.

Identity providers

Provider	When to use
ANONYMOUS	Default. Server allows unauthenticated reads (typical for testing or read-only public servers).
USERNAME	Server requires username + password. Mango sends them along with the secure channel — ensure the security policy is not None so the password is encrypted in transit.
X509	Server requires X.509 client-certificate authentication. Mango uses its auto-generated client.crt / client.key; the server must trust this certificate.

Certificate settings

The first time the data source connects with security enabled, Mango auto-generates a self-signed client.crt, client.key, and client.pub and stores them in the OPCUA_CERTIFICATE_STORE filestore. These files are reused for all OPC UA data sources on this Mango instance.

Setting	Description
Trust all server certificates (trustServerCertificates)	When true, Mango skips server certificate validation. Convenient for development; not recommended for production. When false (default), unknown server certificates are placed in the certificate store's rejected/ directory and connections fail until you promote the certificate to trusted/certs/.

The Certificate Manager tab on the data source editor exposes the trusted/rejected lists and the TRUST/REJECT/DELETE operations (see Certificate Manager below).

Data points

Each data point identifies a specific OPC UA node (variable) on the server.

Setting	Description
Node ID (nodeIdentifier)	The OPC UA node identifier in the parseable string form (e.g., ns=2;s=MyVariable).
Data type	Mango data type. Server values are converted on read; outgoing writes use this type.
Settable	When enabled, the point can be written back to the OPC UA server.
Subscription override (usePubSub)	When true (default), this point uses an OPC UA subscription on the server. When false, the point is polled at the data source's update period. Switch off for points whose value changes faster than you want subscription notifications.

Node ID formats

OPC UA node IDs combine a namespace index (ns) with an identifier. Mango supports three identifier types:

Type	Syntax	Example
String	ns=<namespace>;s=<string>	ns=2;s=MyVariable
Numeric	ns=<namespace>;i=<number>	ns=2;i=12345
GUID	ns=<namespace>;g=<guid>	ns=2;g=09087e75-8e5e-499b-954f-f2a9603db28a

Namespace 0 is reserved for OPC UA standard types; device-specific variables typically live in namespace 2 or higher.

Node Browser

The OPC UA data source editor includes a Node Browser tab that displays the server's address space as a Miller-column tree. Clicking a parent node fetches its direct children only (lazy expansion via POST /rest/latest/opc-ua-data-source/read-children), so browsing very large servers does not download the entire address space up front.

To create points from the browser:

1. Select one or more variable nodes (leaf nodes with a value).
2. Click Create Points (N) at the bottom of the panel.
3. Mango creates a data point per selected node, populating the node ID and a sensible default data type. Adjust names, logging settings, and permissions in the data points list afterward.

Performance note: creating thousands of points at once via the browser sends a large batch through the REST API. For very large imports (5000+ points), import in smaller batches or generate the configuration via JSON import instead.

Certificate Manager

The Certificate Manager tab manages the OPC UA-specific certificate filestore. Operations available:

Operation	What it does
TRUST	Move a certificate from rejected/ to trusted/certs/.
REJECT	Move a certificate from trusted/certs/ to rejected/.
DELETE_TRUSTED	Remove a certificate from the trusted store.
DELETE_REJECTED	Remove a certificate from the rejected store.

The certificate store is shared across all OPC UA data sources on this Mango instance — promoting a server certificate to trusted lets every data source connect to that server.

Access is gated by two system permissions:

• opcua.filestore.permission.read — list the trusted/rejected stores.
• opcua.filestore.permission.write — perform TRUST/REJECT/DELETE operations.

The REST endpoint is POST /rest/latest/opc-ua-data-source/manage-certificates.

REST API

The data source exposes module-specific REST endpoints under /rest/latest/opc-ua-data-source/:

Endpoint	Purpose
POST /rest/latest/opc-ua-data-source/fetch-endpoints	Query an OPC UA server's endpoint list (powers the Fetch Endpoints button).
POST /rest/latest/opc-ua-data-source/read-children	Lazy node fetch for the Node Browser.
POST /rest/latest/opc-ua-data-source/read-values	Read current values for a list of node IDs without creating data points first.
POST /rest/latest/opc-ua-data-source/manage-certificates	List + TRUST / REJECT / DELETE for the OPC UA certificate filestore.

Standard /rest/latest/data-sources and /rest/latest/data-points endpoints accept the new OPCUA model type for managing OPC UA data sources and points programmatically.

Common patterns

Connecting to a simulation server

For testing, a public OPC UA simulation server (such as the Eclipse Milo demo server, or opc.tcp://opcuademo.sterfive.com:26543) is convenient:

1. Create an OPC UA data source with the demo server URL.
2. Set security policy to None and identity to ANONYMOUS.
3. Click Fetch Endpoints and pick the None / None endpoint.
4. Use the Node Browser to find variable nodes and create data points.

Production PLCs and gateways

Modern PLCs (Siemens S7-1500, Beckhoff TwinCAT, Allen-Bradley CompactLogix) and OPC UA gateways (Kepware KEPServerEX, Matrikon, Ignition) all expose OPC UA endpoints. For production:

1. Pick a security policy of Basic256Sha256 or Aes256_Sha256_RsaPss with Sign and Encrypt mode.
2. Configure a username on the server and use USERNAME identity (or X.509 if the server enforces it).
3. On first connect, Mango's client certificate lands in the server's rejected/ directory. Move it to trusted/certs/ on the server side.
4. Re-enable the data source. The connection should succeed.

Troubleshooting

Connection refused or timeout

1. Verify the server URL — try the same URL from a standalone OPC UA client (UaExpert, Prosys Browser).
2. Firewall — OPC UA uses TCP on the configured port (default 4840).
3. DNS — when using a hostname, verify it resolves from the Mango server.
4. Increase clientTimeout — slow networks or busy servers may need more than the 5000 ms default.

Certificate rejected

1. On the server side, check the rejected certificates directory and move Mango's cert to the trusted directory.
2. On the Mango side, the Certificate Manager tab can promote a server certificate from rejected to trusted.
3. Match the security policy — both client and server must support the same policy. Run Fetch Endpoints to see what the server advertises.
4. Try None first — verify basic connectivity, then layer on security.

No data or stale values

1. Check the node ID parse — an incorrect namespace or identifier returns BadNodeIdUnknown. Use the Node Browser to confirm the exact ID.
2. Verify subscription status — runtime status shows the count of monitored items. The server may impose a per-session subscription limit.
3. Settable but writes fail — the OPC UA user account may lack write access on that node, or the node may be read-only at the server level.

Authentication failures

1. Username/password — verify against the server's user list.
2. Encryption requirement — many servers require a non-None security policy when accepting username/password (otherwise the password would travel in the clear).
3. X.509 — confirm the auto-generated client certificate is in the server's trusted store and the X.509 user mapping is configured.

Related Pages

• Data Sources Overview — General data source and data point concepts
• BACnet Data Source — Another protocol for industrial / building automation
• Mango Properties Reference — Permission and filestore configuration referenced by this page
• Users and Permissions — opcua.filestore.permission.read / opcua.filestore.permission.write system permissions