7.0.1685-testing

In this page

Introduction
OpcuaClient
OpcuaSecurityMode
OpcuaSecurityPolicy
OpcuaCertificate
OpcuaCredentials
Log levels
Examples
Third party licenses

OPC UA

Introduction

OPC UA, or Open Platform Communications Unified Architecture, is a standardized communication protocol for industrial automation applications. It provides a platform-independent, service-oriented architecture that enables secure and reliable data exchange between various industrial devices and systems. OPC UA is used to facilitate interoperability and communication in industrial environments, allowing different types of machines, sensors, and control systems to seamlessly exchange data regardless of the underlying hardware or software platforms. It ensures compatibility, scalability, and security in distributed systems, making it a preferred choice for implementing Industrial Internet of Things (IIoT) and Industry 4.0 solutions. In that regard, we provide for users of GreyCat, an OPC UA Client allowing the seamless connection to OPC UA devices to retrieve their values, without the need to leave GCL code and use external tools!

Plugin availability

Platform	Availability
arm64-apple	Yes
arm64-freebsd	No
arm64-linux	Yes
arm64-windows	No
x64-apple	Yes
x64-freebsd	No
x64-linux	Yes
x64-windows	Planned

OpcuaClient

The OpcuaClient type is responsible for establishing a connection to an OPC UA device.

Properties

When instantiating this type, the following properties are available:

host: String: Specifies the hostname or IP address of the OPC UA device.
port: int: Indicates the OPC UA port number (usually 4840).
path: String?: (Optional) Represents the optional path to the required endpoint. If not provided, it defaults to \.
timeout: duration?: (Optional) Response timeout (by default: 20s)
security_mode: OpcuaSecurityMode: Specifies the OPC UA security mode to be applied to the connection.
security_policy: OpcuaSecurityPolicy?: (Optional) Specifies the OPC UA security policy to be applied to the connection, if required.
credentials: OpcuaCredentials?: (Optional) Provides credentials for authentication, if necessary.
certificate: OpcuaCertificate?: (Optional) Optionally includes a client certificate for authentication purposes.

Reading Node Values in OPC UA

To read the current value of a specified NodeID, it must be provided in its string representation, following the OPC UA encoding format: ns=<namespaceindex>;<type>=<value>. For example, ns=0;i=2258 or ns=1;s=string.id.

String Representation Format:

ns: Indicates the namespace index of the NodeID.
<type>: Represents the type of the NodeID. It can be i for numeric NodeIDs, s for string NodeIDs, g for Guid or b for Opaque/ByteString identifier.
<value>: Specifies the value of the NodeID.

Supported OPC UA Types and their mapping in GreyCat

The following table illustrates the OPC UA types supported by GreyCat and their corresponding mappings:

OPC UA Type	GreyCat mapping
Boolean	bool
SByte	int
Byte	int
Int16	int
UInt16	int
Int32	int
UInt32	int
Int64	int
UInt64	int
Float	float
Double	float
String	String
DateTime	time
ByteString	String
XmlElement	String
Guid	String
StatusCode	String
NodeId	String
ExpandedNodeId	String
QualifiedName	String
LocalizedText	String
ExtensionObject	NOT SUPPORTED
DataValue	NOT SUPPORTED
Variant	NOT SUPPORTED
DiagnosticInfo	NOT SUPPORTED

OPC UA arrays are converted into GreyCat arrays, while OPC UA matrices are transformed into GreyCat arrays of arrays.

Read a single node

opcua.read(nodeId: String):any?

opcua.read("ns=1;s=float"); //return 12.3456
opcua.read("non valid or unknwown node"); //return null

Read a batch of nodes

opcua.read_all(nodeIds: Array<String>): Array<any?>

opcua.read_all(["ns=1;s=float", "ns1;s=int", "ns1;s=hello"]); //return [12.3456, 42, "hello world"];
opcua.read_all(["ns=1;s=float", "ns1;s=int", "non valid", "ns1;s=hello"]); //return [12.3456, 42, null, "hello world"];

Read a node and retrieve its server/source timestamp

opcua.read_with_time(nodeId: String):OpcuaValueDetails?

opcua.read_with_time("ns=1;s=boolean"); // return OpcuaValueDetails{value:true,source_time:'2024-05-15T14:55:57Z',server_time:'2024-05-15T14:55:57Z'}

Read a batch of node and retrieve their server/source timestamp

opcua.read_all_with_time(nodeId: Array<String>):Array<OpcuaValueDetails?>

opcua.read_all_with_time(["ns=1;s=boolean","ns=1;s=float"]); // return [OpcuaValueDetails{value:true,source_time:'2024-05-15T14:57:55Z',server_time:'2024-05-15T14:57:55Z'},OpcuaValueDetails{value:123.4560012817,source_time:'2024-05-15T14:57:55Z',server_time:'2024-05-15T14:57:55Z'}]

Read the history of a node

The server needs to be capable of supporting data historization for the specified node.

opcua.read_history(nodeId: String, from: time?, to:time?):Array<OpcuaValueDetails>?

opcua.read_history("ns=1;s=history.uint32", time::parse("2023-07-11T12:00:00Z", null), time::parse("2024-08-11T12:00:00Z", null));
// Return [OpcuaValueDetails{value:100,source_time:'2024-05-15T15:01:08Z',server_time:'2024-05-15T15:01:08Z'},OpcuaValueDetails{value:150,source_time:'2024-05-15T15:01:09Z',server_time:'2024-05-15T15:01:09Z'},OpcuaValueDetails{value:200,source_time:'2024-05-15T15:01:10Z',server_time:'2024-05-15T15:01:10Z'}]

Writing Node Values in OPC UA

In the context of Industry 4.0, the capability to write data back to a machine after data analytics or machine learning algorithms have been applied serves multiple essential purposes. Firstly, it enables proactive maintenance strategies by allowing machines to be stopped or alarms raised immediately upon detection of anomalies or potential malfunctions. Secondly, providing aggregated data or results from machine learning algorithms directly to the machine enables informed decision-making at the operational level, empowering machines to adjust their behavior autonomously based on insights derived from the data. Moreover, fine-tuning machine parameters based on the analyzed data ensures optimal performance and efficiency, as adjustments can be made in real-time to adapt to changing production conditions or quality requirements.

OpcuaClient provides a write method to write data on a OPC UA device. The prerequisites are that the node must be writable, the OPC Ua user must have write permissions on the device and the provided value must match the node type.

write(nodeId: String, value:any)

The following types can be written on devices:

OPC UA Type	GreyCat mapping
Boolean	bool
SByte	int
Byte	int
Int16	int
UInt16	int
Int32	int
UInt32	int
Int64	int
UInt64	int
Float	float
Double	float
String	String
DateTime	time
ByteString	NOT SUPPORTED
XmlElement	NOT SUPPORTED
Guid	NOT SUPPORTED
StatusCode	NOT SUPPORTED
NodeId	NOT SUPPORTED
ExpandedNodeId	NOT SUPPORTED
QualifiedName	NOT SUPPORTED
LocalizedText	NOT SUPPORTED
ExtensionObject	NOT SUPPORTED
DataValue	NOT SUPPORTED
Variant	NOT SUPPORTED
DiagnosticInfo	NOT SUPPORTED

Calling OPC-UA methods

The call method is used to invoke methods on OPC UA nodes. This method requires two parameters: the OPC UA node identifier and an array of parameters to pass to the method.

opcua.call(nodeId: String, parameters:Array<any>):any?

Error management

Read

You may want to protect the read calls with try{} catch {}. The plugin will raise runtime exceptions on:

Unable to read client key and/or certificate
Unable to connect to the OPC UA server
OPC UA responses with a StatusCode != Good
Unable to convert an ExpandedNodeId to a String
Unsupported OPCUA type
Unable to parse the node id

Write

You may want to protect the read calls with try{} catch {}. The plugin will raise runtime exceptions on:

Unable to read client key and/or certificate
Unable to connect to the OPC UA server
OPC UA responses with a StatusCode != Good
Unsupported OPC UA type for writing
Unable to find the OPC UA node type
Unable to serialize the GreyCat value
Unsupported GreyCat type for a given OPC UA type
Overflow on OPC UA type
Unable to parse the node id

OpcuaSecurityMode

In OPC UA, security is an essential aspect to ensure the integrity, confidentiality, and authenticity of data exchange between clients and servers. OPC UA offers several security modes that dictate how communication is secured between parties. Here’s an explanation of the differences between the “None,” “Sign,” and “SignAndEncrypt” security modes:

`OpcuaSecurityMode::None`

In this mode, no encryption or digital signatures are applied to the communication.
Data is transmitted in plaintext, making it vulnerable to interception and tampering.
This mode is suitable for environments where security is not a concern, such as local testing or isolated networks. However, it should not be used in production environments where data confidentiality and integrity are paramount.

`OpcuaSecurityMode::Sign`

In this mode, digital signatures are applied to the communication but encryption is not used.
Data remains in plaintext, but each message is signed with a cryptographic signature to ensure its integrity and authenticity.
While this mode provides some level of security by preventing tampering with data, it does not protect data confidentiality. It is suitable for scenarios where data confidentiality is not a requirement, but data integrity and authenticity are important.

`OpcuaSecurityMode::SignAndEncrypt`

This mode offers the highest level of security by both signing and encrypting communication.
Data is encrypted before transmission, ensuring confidentiality, and each message is signed to ensure its integrity and authenticity.
SignAndEncrypt mode provides comprehensive protection against eavesdropping, tampering, and unauthorized access, making it suitable for environments where data security is critical, such as industrial control systems and IIoT applications.

OpcuaSecurityPolicy

`OpcuaSecurityPolicy::Aes128_Sha256_RsaOaep`

This security policy utilizes AES (Advanced Encryption Standard) with a key length of 128 bits for encryption, SHA-256 (Secure Hash Algorithm 256) for hashing, and RSA-OAEP (RSA Optimal Asymmetric Encryption Padding) for asymmetric encryption.
SHA-256 is a cryptographic hash function that produces a 256-bit (32-byte) hash value, ensuring data integrity.
RSA-OAEP is an asymmetric encryption scheme based on RSA, providing secure encryption and decryption of data.

`OpcuaSecurityPolicy::Aes256_Sha256_RsaPss`

This security policy is similar to Aes128_Sha256_RsaOaep but uses AES with a key length of 256 bits for encryption.
AES-256 offers stronger encryption compared to AES-128, suitable for environments requiring higher security levels.

`OpcuaSecurityPolicy::Basic128Rsa15`

This security policy utilizes Basic128 encryption and RSA with PKCS#1 v1.5 padding for asymmetric encryption.
Basic128 refers to AES with a key length of 128 bits for encryption, providing basic security measures.
RSA15 refers to RSA encryption with PKCS#1 v1.5 padding, an older encryption scheme that is less secure than RSA-OAEP.

`OpcuaSecurityPolicy::Basic256`

This security policy uses AES with a key length of 256 bits for encryption without specifying the hash and asymmetric encryption algorithms.
While it provides stronger encryption compared to Basic128, it lacks specificity regarding hashing and asymmetric encryption algorithms.

`OpcuaSecurityPolicy::Basic256Sha256`

Similar to Basic256, this security policy uses AES with a key length of 256 bits for encryption.
Additionally, it specifies SHA-256 for hashing, enhancing data integrity compared to Basic256.

`OpcuaSecurityPolicy::None`

This security policy indicates that no security measures are applied to communication.
It should only be used in environments where security is not a concern, such as local testing or isolated networks.

OpcuaCertificate

The OpcuaCertificate type represents a certificate used for OPC UA connections.

path: String: Specifies the file path to the certificate.
private_key_path: String: Specifies the file path to the private key associated with the certificate.
application_uri: String?: (Optional) Represents the application URI associated with the certificate.
allow_self_signed: bool?: (Optional) Indicates whether self-signed certificates are allowed. If true, self-signed certificates are permitted; if false or not specified, they are not allowed.

OpcuaCredentials

The OpcuaCredentials type represents credentials used for authentication in OPC UA connections.

login: String: Specifies the login or username associated with the credentials.
password: String: Specifies the password associated with the credentials.

Log levels

GreyCat Log Level	Open62541 Log Level
`error`	`error`
`warn`	`warn`
`trace`	`debug`
all others	`off`

Examples

Reading a single node

@library("opcua", "0.0.0");
fn main() {
    var opcua = OpcuaClient {
        host: "localhost",
        port: 4842,
        security_mode: OpcuaSecurityMode::SignAndEncrypt,
        security_policy: OpcuaSecurityPolicy::Aes128_Sha256_RsaOaep,
        certificate: OpcuaCertificate {
            allow_self_signed: true,
            path: "./test/key/client_cert.der",
            private_key_path: "./test/key/client_key.der",
        },
        credentials: OpcuaCredentials { login: "root", password: "opcua" }
    };
    var result = opcua.read("ns=0;i=2258");
    println(result);
    println(result is time);
}

This code perform a OPC UA connection to a local server running on port 4842. The connection is password protected and uses signature/encryption with the Aes128_Sha256_RsaOaep policy. We want to read the node i=2258 on namespace 0 (this node is present on all OPC UA servers and store the server timestamp). We also assess the result is a core::time.

Result:

'2025-03-26T10:15:12.288884Z'
true

Read a single node with times

In a similar way, we want to retrieve the content of node ns=0;i=2258, alongside with the server and source times:

@library("opcua", "0.0.0");
fn main() {
    var opcua = OpcuaClient {
        host: "localhost",
        port: 4842,
        security_mode: OpcuaSecurityMode::SignAndEncrypt,
        security_policy: OpcuaSecurityPolicy::Aes128_Sha256_RsaOaep,
        certificate: OpcuaCertificate {
            allow_self_signed: true,
            path: "./test/key/client_cert.der",
            private_key_path: "./test/key/client_key.der",
        },
        credentials: OpcuaCredentials { login: "root", password: "opcua" }
    };
    var result = opcua.read_with_time("ns=0;i=2258");
    pprint(result);
}

Result:

OpcuaValueDetails {
  value: '2025-03-26T10:17:47.286130Z',
  source_time: '2025-03-26T10:17:47Z',
  server_time: '2025-03-26T10:17:47Z'
}

Writing a value

Node ns=1;s=boolean hosts a boolean value. We want to write a new value on this node:

@library("opcua", "0.0.0");
fn main() {
    var opcua = OpcuaClient {
        host: "localhost",
        port: 4842,
        security_mode: OpcuaSecurityMode::None,
        security_policy: OpcuaSecurityPolicy::None,
    };
    println(opcua.read("ns=1;s=boolean"));
    opcua.write("ns=1;s=boolean", true);
    println(opcua.read("ns=1;s=boolean"));
    opcua.write("ns=1;s=boolean", 42);
}

Result:

false
true
ERROR 2025-03-26T10:20:08.348155Z 1/3.0 project::main
    Unsupported GreyCat type (3) for OPCUA type: Boolean
    at main (project.gcl:15:38)

Initially, the value on the node was false. We replace it with true and a subsequent call shows the value has been correctly written back to the server. Writing an incompatible value (42 instead of a boolean value) raises a runtime_error.

Writing an array

Node ns=1;s=bool.array hosts a boolean array (size = 3). We want to write new values on this node:

@library("opcua", "0.0.0");
fn main() {
    var opcua = OpcuaClient {
        host: "localhost",
        port: 4842,
        security_mode: OpcuaSecurityMode::None,
        security_policy: OpcuaSecurityPolicy::None,
    };
    println(opcua.read("ns=1;s=bool.array"));
    opcua.write("ns=1;s=bool.array", [false, false, true]);
    println(opcua.read("ns=1;s=bool.array"));
}

Result:

[true,false,true] //Original value
[false,false,true] //After writing

Calling a method

Our OPC UA server exposes two RPC methods:

ns=1;i=62541: Take one string argument and return Hello <argument>
ns=1;s=IncInt32ArrayValues: Take two arguments, a int array, and an increment. This method returns an array with elements increased by the increment value

@library("opcua", "0.0.0");

fn main() {
    var opcua = OpcuaClient {
        host: "localhost",
        port: 4842,
        security_mode: OpcuaSecurityMode::SignAndEncrypt,
        security_policy: OpcuaSecurityPolicy::Aes128_Sha256_RsaOaep,
        certificate: OpcuaCertificate {
            allow_self_signed: true,
            path: "./test/key/client_cert.der",
            private_key_path: "./test/key/client_key.der",
        },
        credentials: OpcuaCredentials { login: "root", password: "opcua" }
    };

    println(opcua.call("ns=1;i=62541", ["DataThings"]));
    println(opcua.call("ns=1;s=IncInt32ArrayValues", [[1, 2, 3, 4, 5], 5]));
}

Result:

Hello DataThings
Array{6,7,8,9,10}