OPC UA

Connection String Options

Name

Type

Default Value

Required

Description

Name

Opcua

Code

opcua

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-opcua</artifactId>
  <version>0.12.0</version>
</dependency>

Default Transport

tcp

Supported Transports

  • tcp

Config options:

protocol-code

STRING

transport-code

STRING

transport-config

STRING

discovery

BOOLEAN

true

Controls the feature of the discovery endpoint of an OPC UA server which every server
will propagate over an '<address>/discovery' endpoint. The most common issue here is that most servers are not correctly
configured and propagate the wrong external IP or URL address. If that is the case you can disable the discovery by
configuring it with a false value.

The discovery phase is always conducted using NONE security policy.

username

STRING

A username to authenticate to the OPCUA server with.

password

STRING

A password to authenticate to the OPCUA server with.

security-policy

STRING

NONE

The security policy applied to communication channel between driver and OPC UA server.
Default value assumes. Possible options are NONE, Basic128Rsa15, Basic256, Basic256Sha256, Aes128_Sha256_RsaOaep, Aes256_Sha256_RsaPss.

message-security

STRING

SIGN_ENCRYPT

The security policy applied to messages exchanged after handshake phase.
Possible options are NONE, SIGN, SIGN_ENCRYPT.
This option is effective only when securityPolicy turns encryption (anything beyond NONE).

key-store-file

STRING

The Keystore file used to lookup client certificate and its private key.

key-store-type

STRING

pkcs12

Keystore type used to access keystore and private key, defaults to PKCS (for Java 11+).
Possible values are between others jks, pkcs11, dks, jceks.

key-store-password

STRING

Java keystore password used to access keystore and private key.

server-certificate-file

STRING

Filesystem location where server certificate is located, supported formats are DER and PEM.

trust-store-file

STRING

The trust store file used to verify server certificates and its chain.

trust-store-type

STRING

pkcs12

Keystore type used to access keystore and private key, defaults to PKCS (for Java 11+).
Possible values are between others jks, pkcs11, dks, jceks.

trust-store-password

STRING

Password used to open trust store.

channel-lifetime

LONG

3600000

Time for which negotiated secure channel, its keys and session remains open. Value in milliseconds, by default 60 minutes.

session-timeout

LONG

120000

Expiry time for opened secure session, value in milliseconds. Defaults to 2 minutes.

negotiation-timeout

LONG

60000

Timeout for all negotiation steps prior acceptance of application level operations - this timeout applies to open secure channel, create session and close calls. Defaults to 60 seconds.

request-timeout

LONG

30000

Timeout for read/write/subscribe calls. Value in milliseconds.

encoding.receive-buffer-size

INT

65535

Maximum size of received TCP transport message chunk value in bytes.

encoding.send-buffer-size

INT

65535

Maximum size of sent transport message chunk.

encoding.max-message-size

INT

2097152

Maximum size of complete message.

encoding.max-chunk-count

INT

64

Maximum number of chunks for both sent and received messages.

endpoint-host

STRING

Endpoint host used to establish secure channel.

endpoint-port

INT

Endpoint port used to establish secure channel

Transport config options:

tcp

tcp.keep-alive

BOOLEAN

false

Should keep-alive packets be sent?

tcp.no-delay

BOOLEAN

true

Should packets be sent instantly or should we give the OS some time to aggregate data.

tcp.default-timeout

INT

1000

Timeout after which a connection will be treated as disconnected.

Name

Value

Description

Supported Operations

read

The read interface allows for reading the full range of supported PLC4X data types in single and bulk requests

write

The write interface allows for writing the full range of supported PLC4X data types in single and bulk requests

subscribe

Subscriptions are possible with events on event- and cyclic-basis

Connection String

The OPC UA drivers uses the connection string

opcua:{transport}://{ip-address}:{port}?{options}

An example of this connection string would be:-

opcua:tcp://127.0.0.1:12686?discovery=true&username=admin&password=password

Note the transport, port and options fields are optional.

Secure communication

The secure channel implementation within Apache PLC4X project have been tested against existing open source server implementations. This includes Eclipse Milo (all modes) as well as OPC Foundation .NET server (except Basic128Rsa15). Manual tests proven that driver is able to communicate with OPC UA server launched on PLCs as well as commercial simulators.

Depending on actual configuration of remote end there might be necessity to prepare client certificate. Preparation of certificate is beyond driver, however in case when no client certificate is provided, it will be auto-generated to establish a session.

The security modes differ between themselves by strength of applied signature and encryption algorithms. Driver is able to communicate with single security mode at the time. Additionally, to security policy it is possible to specify messageSecurity option which indicates expected security settings after initial handshake. By default, this option is set to SIGN_ENCRYPT which imposes high security settings and full encryption of exchanged message payloads. In case when additional diagnostics is needed payloads has to be traced through TRACE level log entries. The SIGN mode gives possibility o browse packets in tools such wireshark.

Certificate verification

The OPC UA specification defines its own procedures for certificate validation. In order to simplify implementation by default server certificate validation is relaxed. Unless explicitly disabled through configuration of trustStoreFile all server certificates will be accepted without validation.

In case when secure communication is enabled the trustStoreFile option might be used to point certificates which client should accept. The acceptance rely on regular TLS checks (expiry date, certificate path etc.), does not validate OPC UA specific parts such as application URI.

Negotiation procedure

Depending on settings driver might or might not attempt to discover endpoints from remote server. In case when discovery option is set to true driver will look up server certificate through connection attempt. The discovery option also enables checks of server endpoints for matching security settings.

Once initial discovery is completed and driver finds endpoint matching its security settings it will launch second connection attempt which will switch to configured security mode.

Each connection attempt made by driver attempt to use limits described in table above. Role of these options is declaration of values accepted and expected by client. Once server returns its limits (Acknowledge for supplied Hello call) driver picks values from these. The only one note is that driver takes minimum of local receive and remote send buffer size. It does same with local send and remote receive buffer.

Usual values of sendBufferSize and receiveBufferSize PLC devices remain at 8196 bytes.

Due to lack of complete implementation of negotiation and chunking logic the OPC UA driver prior Apache PLC4X 0.11 release could supply calls exceeding server limits.

Address Format

To read, write and subscribe to data, the OPC UA driver uses the variable declaration string of the OPC UA server it is connecting to. It includes the namespace(ns) of the hierarchy tree followed by the type of identifier string(s), numeric(i), binary(b) or guid(g) and its address. The Data Type is an optional field, if it is not included a default data type is selected based on the datatype of the returned value. For Unsigned data types it needs to be included otherwise.

ns={namespace-index};[s|i|g|b]={Identifier};{Data Type}

Data Types

The following data types are supported

  • BOOL (boolean)

  • SINT (int 8)

  • USINT (uint 8)

  • BYTE (uint 8)

  • INT (int 16)

  • UINT (uint 16)

  • WORD (uint 16)

  • DINT (int 32)

  • UDINT (uint 32)

  • DWORD (uint 32)

  • LINT (int 64)

  • ULINT (uint 64)

  • LWORD (uint 64)

  • REAL (float)

  • LREAL (double)

  • CHAR (char)

  • WCHAR (2 byte char)

  • STRING (utf-8)

  • WSTRING (utf-16)

Example of a valid OPC UA address:

The following are examples of valid addresses

String address:

ns=2;s=HelloWorld/ScalarTypes/Boolean
ns=2;s=HelloWorld/ScalarTypes/Boolean;BOOL

Numeric address

ns=1;i=1337
ns=1;i=1337;DINT

GUID address:

ns=2;g=09087e75-8e5e-499b-954f-f2a8624db28a
ns=2;g=09087e75-8e5e-499b-954f-f2a8624db28a;REAL

Note the Identifiers s,i,b and g specify the format of the address not the data type of the returned value.

Some useful tips

The namespace (e.g. ns=2) within the address is specific to the server you are connecting to.

More details on OPC UA

OPC UA The OPC Unified Architecture (UA), released in 2008, is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework.

This multi-layered approach accomplishes the original design specification goals of:

  • Functional equivalence: all COM OPC Classic specifications are mapped to UA

  • Platform independence: from an embedded micro-controller to cloud-based infrastructure

  • Secure: encryption, authentication, and auditing

  • Extensible: ability to add new features without affecting existing applications

  • Comprehensive information modeling: for defining complex information