Configure the OPC-UA Client Connector
Connect SIA Connect to an OPC UA server, configure security, discover servers and nodes, read or write values, and troubleshoot common errors.
The OPC-UA Client Connector connects SIA Connect to an OPC UA server. Use it to read current or historical node values, write supported values, and discover servers and items automatically.
This guide explains how to create an OPC-UA Client instance, configure security, discover servers and items, add items manually, and resolve common connection and data errors.
Before you begin
Make sure that:
- The OPC UA server is running and reachable from SIA Connect.
- You know the server endpoint URL or can discover the server on a local IPv4 network.
- You know which security mode and policy the server supports.
- You have a username and password if the server does not allow anonymous access.
- You can add the SIA Connect client certificate to the server trust list when the server requires a trusted client certificate.
- The required firewall rules allow OPC UA TCP traffic between SIA Connect and the server.
Use a signed or encrypted endpoint when you configure a username and password. Treat credentials, certificates, and private keys as sensitive information.
Create an OPC-UA Client instance manually
- In the Edge Portal, open Workspace > Instances.
- Select Add instance.
- Select the OPC-UA Client Connector.
- Enter a descriptive instance name.
- Enter the OPC UA server endpoint in Address.
- Configure the authentication and security parameters described below.
- Save the instance.
Use an endpoint in this format:
opc.tcp://<host>:<port>/<path>
Example:
opc.tcp://192.168.10.25:4840
If you omit opc.tcp://, the Connector adds it before connecting. The address can include an endpoint path when the server requires one.
Instance parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| Address | Yes | None | OPC UA server endpoint. Include the hostname or IP address, TCP port, and endpoint path when required. |
| Username | No | Empty | Username used for server authentication. Leave empty when the server allows anonymous access. |
| Password | No | Empty | Password used with the configured username. |
| Security mode | Yes | None | Select None, Sign, or Sign & Encrypt. The selection must match an endpoint offered by the server. |
| Security policy | Yes | None | Select None, Basic128Rsa15, Basic256, or Basic256Sha256. The selection must match the selected security mode and an endpoint offered by the server. |
| Certificate | No | None | Client certificate used for secure communication. When secure communication is required and no file is selected, the Connector uses its generated OPC-UA SIA Connect certificate. |
| Key | No | None | Private key matching the selected client certificate. When secure communication is required and no file is selected, the Connector uses its generated OPC-UA SIA Connect key. |
The certificate and key secure the OPC UA channel. The Connector supports anonymous access and username/password authentication. It does not use the selected certificate as an X.509 user identity.
Configure certificates and keys
The Connector generates a self-signed client certificate and matching key when its certificate files do not already exist. The generated files appear in the Connector file list as:
- OPC-UA SIA certificate
- OPC-UA SIA key
When the server requires trusted client certificates:
- Open the files for the OPC-UA Client Connector.
- Download the generated client certificate.
- Add the certificate to the OPC UA server trust list.
- Restart or reload the server trust configuration when required by the server.
- Enable the instance and check that it connects.
You can upload and select another certificate and matching key when required. Make sure that the files use the format expected by the Connector and belong to the same key pair.
Discover OPC UA servers
The Connector can scan a local IPv4 subnet for OPC UA TCP servers.
- Open Configuration > Connectors.
- Find the installed and enabled OPC-UA Client Connector.
- Select Discover instances.
- Configure the discovery parameters.
- Select Search instances.
- Wait for the search to finish.
- Select the required server candidates.
- Import the selected instances.
- Edit an imported instance when you need to add credentials, change its security settings, or select certificate files.
The Connector requests the endpoints offered by each detected server. When it can read the endpoint list, it imports a supported security mode and policy and indicates whether anonymous access or username authentication is offered. If the server advertises another hostname, the imported endpoint keeps the scanned IP address so SIA Connect can reach it.
Server discovery parameters
| Parameter | Default | Accepted values | Description |
|---|---|---|---|
| Scan duration (ms) | 60000 |
1000 to 300000
|
Maximum overall discovery time in milliseconds. |
| Network interface | eth0 |
An available IPv4 interface or All IPv4 interfaces | Interface whose local subnet is scanned. |
| TCP ports | 4840-4850,53530 |
Comma-separated ports and port ranges | TCP ports checked for OPC UA servers. For example, 4840,4845-4850. The Connector scans up to 64 ports. |
Discovery scans up to 256 hosts per selected interface. It skips loopback and IPv4 link-local addresses. Add a routed server manually when it is outside the local subnet or cannot be reached through subnet scanning.
Discover items
Item discovery connects with the instance address, credentials, security settings, certificate, and key. It browses the server address space and returns supported local variables.
- Open the OPC-UA Client instance.
- Select Discover items.
- Set Scan duration (ms) when you need more time for a large server address space.
- Start the search.
- Review the discovered item name, node identifier, data type, and read/write capability.
- Select the required items.
- Import the selected items.
- Enable the items and verify their values.
Discovered items use the following defaults:
-
Floating point precision:
4 - Access level: Current Read/Write
-
History from:
-2000 -
History to:
0 - History no value handling: Keep latest non-empty value
The Connector skips variables that use unsupported data types, cannot be read for type information, or are neither readable nor writable. A browse can return partial results with warnings if the server stops responding before the complete address space has been processed.
Add an item manually
- Open the OPC-UA Client instance.
- Open the Items section.
- Select Add item.
- Enter a descriptive item name.
- Enter the OPC UA NodeId in Identifier.
- Configure the remaining item parameters.
- Save and enable the item.
Node identifier formats
Use the complete OPC UA NodeId whenever possible.
| Identifier type | Example |
|---|---|
| Numeric | ns=2;i=456 |
| String | ns=2;s=Machine.Speed |
| GUID | ns=2;g=1d545837-3edb-43f5-a4b8-073c0775fcbe |
| Opaque or ByteString | ns=2;b=UG9zaXRpb24= |
A bare identifier without a namespace is interpreted as namespace 0. A numeric value is treated as a numeric identifier, a valid UUID is treated as a GUID, and other values are treated as string identifiers.
To address one element in an array, add the array index at the end of the identifier. For example:
ns=2;s=Machine.Values[3]
Array indexes begin at 0.
Item parameters
| Parameter | Default | Description |
|---|---|---|
| Identifier | Empty | Complete NodeId or supported bare identifier for the OPC UA variable. |
| Floating point precision | 4 |
Number of digits used to represent floating-point values. |
| Access level | Current Read/Write | Select Current Read/Write for current values and supported writes, or History Read to request historical values. |
| History from | -2000 |
Start of the historical interval. Use an epoch timestamp in milliseconds, or a negative number for milliseconds before the current time. |
| History to | 0 |
End of the historical interval. Use an epoch timestamp in milliseconds, a negative number for milliseconds before the current time, or 0 for now. |
| History no value handling | Keep latest non-empty value | Select whether the item retains its latest non-empty value or uses an empty value when the requested interval contains no historical values. |
Historical results are returned as a JSON array. Each entry contains a timestamp and a value.
Supported OPC UA data types
The Connector can discover and read the following built-in types and vendor-defined types that inherit from them:
- Boolean
- SByte and Byte
- Int16, UInt16, Int32, UInt32, Int64, and UInt64
- Float and Double
- String
- DateTime
- ByteString
- LocalizedText
- Guid
Writing is supported for the listed primitive types except LocalizedText and Guid. The server must also mark the variable as writable. Array values are supported, and you can use an array index when you only need one element.
Automatic identity items
The Connector adds standard identity items to each OPC-UA Client instance. Values appear when the server exposes the corresponding standard OPC UA nodes.
| Item | OPC UA value |
|---|---|
| Vendor | ManufacturerName |
| Model | ProductName |
| Product code | ProductUri |
| Firmware | SoftwareVersion combined with BuildNumber when available |
| Build number | BuildNumber |
Verify the connection
- Enable the OPC-UA Client instance.
- Confirm that the instance does not report a connection error.
- Enable at least one readable item.
- Confirm that the item receives a value and timestamp.
- If the item is writable, perform a controlled test write and confirm the result on the OPC UA server.
- Restore the original value after testing when required.
Only test writes when changing the target value is safe for the connected process and equipment.
Troubleshoot the OPC-UA Client Connector
| Message or symptom | Likely cause | Action |
|---|---|---|
| BadHostUnreachable, BadConnectionClosed, or another TCP connection error | The endpoint is unavailable, the address is incorrect, or network traffic is blocked. | Check the endpoint address and port. Confirm that the server is running, test network connectivity, and review routing and firewall rules. |
| BadTimeout | The server did not respond within the request timeout. | Check network quality and server load. Increase Scan duration (ms) for discovery or browsing a large address space. |
| BadIdentityTokenRejected, BadUserAccessDenied, or BadUserNameInvalid | The credentials are incorrect or the selected endpoint does not accept username authentication. | Check the username and password. Confirm that the server offers username authentication on the selected security endpoint. |
| BadSecurityModeRejected, BadSecurityPolicyRejected, or No suitable endpoint found | The configured security mode and policy do not match an endpoint offered by the server. | Review the server endpoints and select a matching mode and policy. Discover the instance again to retrieve current endpoint information. |
| A certificate or security-check error | The server does not trust the client certificate, or the selected certificate and key are missing or invalid. | Add the SIA Connect client certificate to the server trust list. Confirm that the selected certificate and key files exist and form a matching pair. |
| Wrong identifier format | The item identifier is not a supported OPC UA NodeId. | Use a valid numeric, string, GUID, or ByteString NodeId. Include the namespace and identifier prefix, such as ns=2;s=Machine.Speed. |
| Unknown node identifier | The server does not contain the configured node, or the namespace or identifier is incorrect. | Browse the server again and import the item, or compare the identifier with an OPC UA browsing tool. |
| Invalid/Unsupported scalar type or Unsupported node data type | The variable uses a data type that the Connector cannot convert. | Use a variable with a supported primitive type. If the server uses a vendor-defined type, confirm that it inherits from a supported built-in type. |
| Writing <type> values is not supported | The variable type is readable but not writable through the Connector. | Use the item for reading only, or expose the value through a writable supported primitive type on the server. |
| Failed to determine data type | The server did not return usable data-type information for the variable. | Check the node permissions and server address space. Confirm that the node exposes a valid OPC UA data type. |
| Failed to convert value to <type> | The value supplied for a write does not match the OPC UA variable type. | Use a value that matches the server data type and expected range. |
| Invalid date time format. Expected format: yyyy-MM-dd hh:mm:ss.zzz | A DateTime write uses another format. | Enter the value in the required format, for example 2026-09-03 14:30:00.000. |
| Discovery finds no servers | The wrong interface or ports are selected, the server is outside the scanned subnet, or a firewall blocks the probe. | Select the interface connected to the server network, include the correct OPC UA port, and check firewall rules. Add the instance manually if the server is routed or outside the local subnet. |
| Item discovery returns partial results | The server stopped responding while the Connector browsed a large address space. | Increase Scan duration (ms), reduce server load, and run discovery again. Review the returned browse warnings. |
| An expected item is missing from discovery | The variable is not readable or writable, is a non-local reference, or uses an unsupported data type. | Review the discovery warnings and the variable configuration on the server. Add it manually only when its NodeId and data type are supported. |
| A historical item returns no value | The server has no historical values in the requested interval or does not support history access for the node. | Check History from and History to. Confirm that history is enabled for the node on the server. |
Review the instance error, item error, discovery warnings, and system logs together. OPC UA status names returned by the server often identify the rejected security, authentication, node, or access setting.