OPC UA Bridge

Introduction

The OPC UA Bridge enables seamless communication with OPC UA servers, serving as a client to connect with and gather data from industrial systems. Designed for interoperability in industrial automation, the OPC UA Bridge connector reads values from OPC UA servers, such as those provided by PLCs, sensors, and other monitoring equipment, and sends them to Coreflux MQTT Broker. This setup allows data to flow in both directions: the client can also receive data from Coreflux Central and write it back to OPC UA servers. By facilitating secure and reliable data exchange, the OPC UA Bridge connector enhances integration and efficiency in complex, distributed systems.

Features and Benefits

Comprehensive Security Options: Supports multiple authentication methods, including user/password, certificates, and anonymous access. Additionally, it offers robust security policies and message security mode, ensuring secure and reliable communication with OPC UA servers.
Flexible Data Handling: Enables both read and write operations, allowing it to gather data from OPC UA servers and push real-time updates or commands back to devices. This bi-directional data flow enhances system responsiveness and control.
Tag-Based Messaging: Uses tags for MQTT topics, simplifying configuration and making data streams easier to understand and manage.
Seamless Coreflux Integration: Fits smoothly within the Coreflux ecosystem, reducing complexity and speeding up IoT solution deployment.
Interoperability and Flexibility: Compatible with a wide range of OPC UA server implementations, enabling seamless integration across varied industrial devices and systems, making it a versatile connector for complex automation environments.
Enhanced Data Exchange: Utilizes MQTT's efficient messaging protocol for real-time data exchange, improving decision-making and system performance.

Use Cases:

Real-Time Monitoring and Control: Enables direct monitoring and control of OPC UA-connected machinery through MQTT-enabled dashboards, providing instant insights and enabling proactive adjustments to reduce downtime and boost productivity.
Cross-Platform Interoperability: Supports integration with diverse OPC UA servers across various industrial platforms, allowing seamless data exchange and device management within mixed-technology environments. This flexibility simplifies system expansions and enhances compatibility across new and legacy equipment.
IoT Integration: Facilitates secure integration of industrial systems into IoT environments for cloud analytics, remote monitoring, and predictive maintenance. By leveraging OPC UA’s security features, it ensures that sensitive data is protected during transmission between devices and Coreflux MQTT Broker.

Prerequisites

Before you install and configure the OPC UA Bridge connector, ensure you have the following prerequisites:

Basic understanding of the MQTT protocol.
Undertstanding of OPC UA protocol.
Coreflux account.
Coreflux 1.3 MQTT broker.
MQTT Client (such as MQTT Explorer).
Access to an OPC UA server (e.g., a PLC or other compatible device).
Required security certificates if using certificate-based authentication for OPC UA.

Connector installation

Using Coreflux HUB

Please refere to general docs for connector installation trough the Coreflux HUB.

Using Coreflux HUBLESS

Connector management and control are conducted using the MQTT protocol. Commands (payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

Connect to the Coreflux MQTT Broker using your preferred client.
Login using your coreflux account:
```
-L myname@mydomain.com password
```
Check your available connectors:
```
-l
```
Install connector:
```
-I coreflux_mqttopcbridge
```

If there were no issues during the installation you should receive a message on the $SYS/Coreflux/Command/Output:

Your coreflux_mqttopcbridge was installed with version <version> with the <connector_guid>. Let the magic begin!

Connector Configuration

Before using the connector, it must be properly configured. This configuration process involves setting various parameters to ensure the connector functions optimally and integrates seamlessly with OPC UA servers and MQTT networks. Configuration requires specifying details like the OPC UA server endpoint, authentication mode, security policies, and MQTT topic settings for data exchange. The configuration is detailed in a JSON file, divided into three main sections: MQTT Parameters, OPC UA Properties and Tags Prameters.
The instructions below will guide you through configuring each section, culminating in a sample configuration you can customize for your setup.

Warning: If a parameter is not included in your connector's configuration and it is not required, a default value will be applied. Incorrect configuration may cause the connector to not work as intended.

Information_source: This configuration is presented using a hubless setup as an example. The key takeaway is the understanding of the parameters and their significance. If you are configuring the connector via Coreflux Hub, the same parameters and configurations apply.

MQTT Parameters

The MQTTParameters in the JSON configuration define how to connect to an MQTT broker, specifying the communication details. The Address and Port indicate the broker's network location (in this case, 127.0.0.1 on port 1883), which is where the data will be sent to or received from. The parameters also detail authentication methods and the use of TLS for secure communication. This setup determines the pathway for data exchange between the device and the MQTT broker, facilitating the monitoring or control of device operations.

Parameter	Description	Required	Example	Default Value
Port	Port number on which the MQTT broker is running.	Yes	`1883`	1883
Address	IP address or hostname of the MQTT broker.	Yes	`"127.0.0.1"`	`"127.0.0.1"`
IsAnonymous	Indicates if the connection is anonymous (no username/password required).	No	`true`	`true`
Username	Username for authentication, if not anonymous.	No	`""` (empty string)	`""` (empty string)
Password	Password for authentication, if not anonymous.	No	`""` (empty string)	`""` (empty string)
WithTLS	Specifies whether TLS encryption is enabled for secure communication.	No	`true`	`false`
ClientId	Specifies the unique client identifier for the MQTT connection.	Yes	`LocalBroker`	`randomName`

Example:

{
  "MQTTParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "WithTLS": false,
    "ClientId": "LocalBroker"
  }
}

OPC UA Parameters

The OPC UA section in the JSON configuration specifies the setup for OPC UA communication between the local system and the target server. These parameters are essential for enabling secure and reliable data exchange using the OPC UA protocol.

Parameter	Description	Required	Example	Default Value
EndpointUrl	The OPC UA server URL for connection	Yes	`opc.tcp://localhost:1234/server`	`"opc.tcp://localhost:62541/path/server"`
PublishingInterval	The interval, in milliseconds, at which the server sends notifications for monitored items to the client. A smaller value increases the frequency of updates but may increase network and processing load. Publishing & Sampling Intervals	Yes	`500`	`200`
AutoAcceptUntrustedCertificates	Automatically trusts certificates without manual validation, useful for development but risky for production.	Yes	true	false
SuppressNonceValidationErrors	Disables validation errors for server nonces, allowing connections even if nonce length or randomness is insufficient.	Yes	true	false
AuthMode	Authentication mode to connect server and client. Options are (0)Anonymous, (1)Certificate, or (2)UserPass.	Yes	`Certificate`	`Anonymous`
UseSecurity	Determines if the endpoint should use secure communication. If value is true, it allows you to set the SecurityPolicy and MessageSecurityMode to enable secure messaging and data encryption.	Yes	true	false
SecurityPolicy	Defines encryption and signing algorithms, for secure communication. Required if UseSecurity is true. Check Security Policy Types	No	`Basic256Sha256`	`None`
MessageSecurity	Specifies the security level, ensuring data is signed or signed and encrypted. Required if UseSecurity is true. Check Message Security Modes	No	`SignAndEncrypt`	`None`
UserCertificatePath	Path to the user identity certificate (.pfx) used for authentication when AuthMode is Certificate.	No	`certificate/opcua`	`path/to/user/identity/certificate`
CertificatePassword	Password for accessing the user certificate, if applicable.	No	`password`	''
User	Username for authentication with the OPC UA server. Required if AuthMode is UserPass.	No	`admin`	``
Password	Password for authentication with the OPC UA server. Required if AuthMode is UserPass.	No	`adminpass`	``
Timeout	Connection timeout duration in milliseconds.	Yes	90000	6000
Browse	Enables or disables browsing of OPC UA nodes.	Yes	true	true
BrowsePath	Path to the node or folder to start browsing from when Browse is enabled. Option are Root, Root/Objects, Root/Types.	No	`Root`	`Root/Objects`
BrowseOnValueChange	Browsing is triggered by value changes. Enabling this option may decrease the connector performance.	No	true	false

ℹ : If AutoAcceptUntrustedCertificates is set to false, the OPC UA Bridge will not automatically trust certificates from untrusted sources. In this case, users will need to manage certificates manually and have some familiarity using certificate stores. This involves adding the server's certificate to the trusted store or managing rejected certificates, which is crucial for establishing a successful and secure connection.

ℹ : If AuthMode is set to Certificate, the user will need to create a client identity certificate that meets the specific requirements of the OPC UA server configuration. This certificate may need to include attributes like “Digital Signature” and “Client Authentication” to be accepted by the server. A strong understanding of managing certificate stores on both the client and server sides is essential, as proper handling of trusted and rejected certificates will be required to establish a secure connection.

⚠ Warning: The OPC UA Bridge connector stores its certificates at the following path: %LocalAppData%/OPC Foundation/pki

Example:

{
  "MqttParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "WithTLS": false,
    "ClientId": "LocalBroker"
  },
    "Properties": {
    "EndpointUrl": "opc.tcp://Coreflux:53530/OPCUA/Server",
    "AutoAcceptUntrustedCertificates": false,
    "SuppressNonceValidationErrors": false,
    "AuthMode": 2,
    "UseSecurity": true,
    "SecurityPolicy": 3,
    "MessageSecurity": 2,
    "User": "admin",
    "Password": "adminpass",
    "Timeout": 90000,
    "Browse": true,
    "BrowsePath": "Root/Objects",
    "BrowseOnValueChange": false
    }
}

Security Policy Types

The SecurityPolicyType Table outlines the different security policies available for OPC UA communication, each identified by a specific policy type. These policies define the level of encryption, signing, and algorithms used to secure data exchange between the client and server.

SecurityPolicyType	Description
None - 0	No security; data is exchanged without encryption or signing. Suitable for low-security environments.
Basic128Rsa15 - 1	Uses RSA encryption with a 128-bit key and SHA-1 for signing. This policy provides basic security.
Basic256 - 2	Uses RSA encryption with a 256-bit key and SHA-1 for signing. Provides moderate security.
Basic256Sha256 - 3	Uses RSA encryption with a 256-bit key and SHA-256 for signing. Provides strong security and is commonly recommended for secure environments.
Aes128_Sha256_RsaOaep - 4	Uses AES-128 encryption with SHA-256 and RSA-OAEP for signing and encryption. Provides enhanced security with modern encryption standards.
Aes256_Sha256_RsaPss - 5	Uses AES-256 encryption with SHA-256 and RSA-PSS for signing and encryption. Offers the highest security, suitable for environments requiring maximum data protection.

Message Security Modes

The MessageSecurityMode Table outlines the different levels of message security that can be applied in OPC UA communication. Each mode defines how messages are protected during transmission, ensuring data integrity and confidentiality as needed.

MessageSecurityType	Description
None - 0	No security applied to messages; data is exchanged without signing or encryption. Suitable for low-security applications.
Sign - 1	Messages are signed to ensure integrity, preventing unauthorized changes to the data. Ideal for environments where data tampering needs to be prevented but encryption is not required.
SignAndEncrypt - 2	Messages are both signed and encrypted, ensuring confidentiality and integrity. Recommended for high-security environments where data needs to be protected from tampering and unauthorized access.

Tag Data Types

This section outlines the various data types used within the system, which are named and structured to mirror the data types found in the corresponding devices. This naming convention ensures a more intuitive and direct mapping of data types from the devices to our system, facilitating easier data handling and integration. Understanding these data types is crucial for effective communication and data manipulation in the system.

Data Type - Integer Value	Description	Memory Space	Lower Bound	Upper Bound
Boolean - 0	Set a specific Bit to: 0 (false) or 1 (true).	1 bits	FALSE (0)	TRUE (1)
SByte - 1	Signed 8-bit integer.	8	-128	127
Byte - 2	Unsigned 8-bit integer.	8	0	255
INT16 - 3	Signed 16-bit integer.	16 bits	-32768	32767
UINT16 - 4	Unsigned 16-bit integer.	16 bits	0	65535
INT32 - 5	Signed 32-bit integer.	32 bits	-2147483648	2147483647
UINT32 - 6	Unsigned 32-bit integer.	32 bits	0	4294967295
INT64 - 7	Signed 64-bit integer.	64 bits	-2^63	2^63-1
UINT64 - 8	Unsigned 64-bit integer.	64 bits	0	2^64-1
Float32 - 9	32-bit floating point number.	32	-3.402823e+38	3.402823e+38
Float64 - 10	64-bit floating point number (double).	64 bits	-1.7976931348623158e+308	1.7976931348623158e+308
String - 11	Sequence of characters, typically encoded in UTF-8.	Variable	N/A	N/A
DateTime - 12	Represents date and time as per OPC UA standards.	64 bits	1/1/0001 00:00:00 UTC	12/31/9999 23:59:59 UTC

Publishing Sampling Intervals

The PublishingInterval and SamplingInterval are key parameters in OPC UA subscriptions that control the flow of data updates between the server and the client.

SamplingInterval: Defines how often the server samples the data source for changes.
If set to 0, the server uses its default sampling interval.
A smaller value increases the sampling frequency but can increase server load.
PublishingInterval: Defines how often the server sends collected updates (notifications) to the client.
The server sends the latest sampled values at this interval.

Key Behavior:
If SamplingInterval is greater than PublishingInterval, updates will only occur at the SamplingInterval.
If SamplingInterval is smaller than PublishingInterval, the server will send the most recent sampled value at each publishing interval.

Understanding the Intervals: Example Table

The table below demonstrates how PublishingInterval and SamplingInterval interact:

Time (ms)	NodeId 1 (`SamplingInterval = 500 ms`)	NodeId 2 (`SamplingInterval = 200 ms`)	Subscription (`PublishingInterval = 350 ms`)
0	Collects initial value	Collects initial value	Sends initial values to the client
200	-	Collects new value	-
350	-	-	Sends updated value of NodeId 2
400	-	Collects new value	-
500	Collects new value	-	-
700	-	Collects new value	Sends updated values of NodeId 1 and NodeId 2
800	-	Collects new value	-
1000	Collects new value	-	Sends updated values of NodeId 1 and NodeId 2

ℹ Practical Considerations :

Use a lower PublishingInterval for near real-time applications, but monitor network and client load.
Use a lower SamplingInterval for fast-changing values, but consider server resource usage.
Allow SamplingInterval = 0 to use the server's optimized default for less critical data.

By tuning these two values correctly, you can balance update frequency, server load, and network performance.

Saving the configuration

Connector management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : Configuration requires the user to be logged in and have an connector installed. If these requirements are not met, please refer to the installation section.

Save configuration:
```
-assetConfigSave <asset_guid or assetName> <configuration>
```
ℹ : The connector asset_guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Example:

-assetConfigSave connectorName {
  "MqttParameters": {
    "Port": 1883,
    "Address": "127.0.0.1",
    "IsAnonymous": true,
    "Username": "",
    "Password": "",
    "WithTLS": false,
    "ClientId": "LocalBroker"
  },
    "Properties": {
    "EndpointUrl": "opc.tcp://Coreflux:53530/OPCUA/Server",
    "AutoAcceptUntrustedCertificates": false,
    "SuppressNonceValidationErrors": false,
    "AuthMode": 2,
    "UseSecurity": true,
    "SecurityPolicy": 3,
    "MessageSecurity": 2,
    "User": "admin",
    "Password": "adminpass",
    "Timeout": 90000,
    "Browse": true,
    "BrowsePath": "Root/Objects",
    "BrowseOnValueChange": false
    },
    "Tags": [
    {
      "Name": "TagInbound",
      "Route": 0,
      "Publish": 2,
      "MqttTopic": "test/receive",
      "QualityOfService": 0,
      "MqttRetain": false,
      "NodeId": "ns=5;s=Int32Array",
      "DataType": 5,
      "IsArray": true,
      "FullArray": true
    }
  ]
}

Check if the configuration was saved (optional) :
```
-assetConfigLoad <asset_guid>
```

ℹ : Find more detailed information about the connector management here.

Configuration Reference

A comprehensive source for detailed information on connector parameters and their interactions.

Using the connector

⚠ Warning: It is important to understand that the flow of data between the broker and the device highly depends on the configuration of both the connector and the device. In case of unexpected results, please verify the configuration and/or check the logs for any possible errors.

With Coreflux HUB

Please refer to the general docs for connector installation through the Coreflux HUB.

With Coreflux HUBLESS

Connector management and control are conducted using the MQTT protocol. Commands (MQTT payload) are sent to the $SYS/Coreflux/Command topic. The results of these commands are published to $SYS/Coreflux/Command/Output. The following steps will focus solely on the payload that needs to be sent.

ℹ : The asset guid can be obtained by consulting the $SYS/Coreflux/Assets topic.

Run connector

Run connector:

-R <asset_guid>

Stop connector

Stop connector:

-S <asset_guid>

⚠ Warning: To update the connector configuration, ensure you stop it first to avoid issues. After making the changes, restart the connector to apply the new configuration.

Logs

Logs are essential for monitoring and debugging your system. They provide insight into the operation of your connectors and can help identify and resolve issues promptly.

With Coreflux HUB

On Coreflux HUB, the logs are displayed in the "Log" section of the connector configuration.

With MQTT Explorer

To display logs in MQTT Explorer, follow these steps:

Publish the following command to the $SYS/Coreflux/Command topic:

-addTraceLog topic=topic/to/show/log level=Error/Information/Warning messageContains=(assetID)

2. The logs will be shown on the $SYS/Coreflux/Log/Traces/topic/to/show/log topic.

Example1:

To display informational logs, use:

-addTraceLog topic=log/inf level=Information

Note : This will display the Logs "Information" of all the connectors

Example2:

To display error logs, from a specific connector, use:

-addTraceLog topic=log/opcua/err level=Error messageContains=assetID

Note : This will display the Logs "Error" of a specific connector

Note: To display all three types of logs (Error, Information, and Warning), you will need to repeat this process three times, one for each log level. three times, one for each log level.

Parameter	Description	Required	Example	Default Value
Name	Unique Tag identifier	Yes	`outputExample`	`"TagName"`
Route	The direction of data flow. Can be 'To subscribers' i.e. MQTT client or 'To other', such as a device.	Yes	`The options are: 0 - ToSubscribers, 1 - ToOther`	`0`
Publish	Chose how data is sent.	Yes	`Acceptable values are: 'Update' (0), 'Cyclic' (1), 'Once' (2)`	`1`
PublishCycle	If 'publish' = 'Cyclic', a value must be set	No	`PublishCycle must be between 1 and 86400 seconds (24 hours)`	`0`
MqttTopic	Indentifies the topic to which the data will be published.	Yes	`machine/motorStart`	`"Random Topic"`
MqttRetain	Defines if the message should be retained	Yes	`true or false`	`false`
QualityOfService	Quality of service for the MQTT topic	Yes	`Options are: 0 - AtMostOnce, 1 - AtLeastOnce and 2 - ExactlyOnce.`	`0`
NodeId	Identifier for the OPC UA node to read or write data.	Yes	`ns=1;s=Identifier`	`ns=1;s=Identifier`
DataType	Defines data type to read/write. Check Tag Data Types	Yes	`2`	`5`
SamplingInterval	The interval, in milliseconds, at which the server samples the data source for monitored items. If set to 0, the server's default sampling interval is used. A smaller value increases the sampling frequency but may increase server load. Check Publishing & Sampling Intervals	Yes	`500`	`0`
IsArray	Indicates if the node value is an array.	Yes	true	false
FullArray	For inbound tags, reads the full array from the OPC UA server. For outbound tags, sends all values from the payload JSON.	No	true	true
ArrayIndex	Specifies the array index to access when FullArray is false and IsArray is true.	No	`5`	`0`