PLCcom OPC UA PubSub SDK class library documentation
First steps PLCcom OPC UA PubSub SDK for Java
The PLCcom OPC UA PubSub SDK for Java is an add-on for the PLCcom OPC UA SDK for Java. It adds OPC UA publisher/subscriber communication to applications that already use, or want to use, the PLCcom OPC UA SDK. The add-on is released in the same version as the main SDK and is intended to be used together with the matching PLCcom OPC UA SDK version.
The main SDK provides the classic OPC UA client and server world. The PubSub add-on extends this with message based communication: a publisher sends process values through UDP or MQTT, and one or more subscribers receive and process these values. This is useful for telemetry, machine-to-machine communication, broadcast or multicast scenarios and broker based MQTT integration.
Where to get the add-on
The PubSub SDK is distributed as an add-on to the PLCcom OPC UA SDK. It requires a valid PLCcom OPC UA SDK installation and license information that includes PubSub usage rights. Trial and commercial information are available on the PLCcom OPC UA SDK product pages.
| Resource | Purpose |
|---|---|
| PLCcom OPC UA SDK overview | Product information for the PLCcom OPC UA SDK family. |
| Trial download | Download entry point for evaluation and trial use. |
| Purchase information | Commercial license and ordering information. |
| Public Java examples on GitHub | Complete Java examples for the PLCcom OPC UA SDK and the PubSub add-on. |
Prerequisites
Before you add PubSub to an application, make sure that the basic SDK environment is available. The PubSub SDK is not a standalone replacement for the main PLCcom OPC UA SDK. It is an add-on and uses the main SDK types, license handling and certificate handling.
- PLCcom OPC UA SDK for Java in the same version as the PubSub add-on
- License information that includes the PubSub add-on usage rights
- Java runtime 1.8 or higher for applications
- A Java development environment that can compile Java 1.8 compatible code
- Maven, when the SDK is referenced through Maven coordinates
- An MQTT broker, when MQTT or secure MQTT transport is used
- A PKI and trusted certificates, when TLS protected MQTT communication is used
The PLCcom SDK artifacts must be available to Maven, for example in the local Maven repository or in a company Maven repository. If the artifacts are not available from a configured repository, install or deploy the SDK and PubSub artifacts according to your delivery package or build process.
Using the add-on with Maven
The PubSub add-on is referenced like any other Maven library. The version should always match the version of the main PLCcom OPC UA SDK used by the application.
<dependencies>
<dependency>
<groupId>com.indi-an.plccom</groupId>
<artifactId>plccom-opc-ua-pubsub</artifactId>
<version>10.x.x</version>
</dependency>
</dependencies>
Replace 10.x.x with the version delivered with your PLCcom SDK
package. The PubSub add-on and the main PLCcom OPC UA SDK are released with the
same version. The main SDK dependency is referenced by the PubSub artifact and
is normally resolved transitively by Maven.
Important note
With the PLCcom OPC UA PubSub SDK you or the user will be able to exchange process data between applications, machines or similar systems at your own discretion. For this purpose the user has to have the required knowledge and must understand the effects of the created application.
Before the resulting work can be applied to the plant, machine or similar, the creator of a project must test all functions and check function and interactions with the system, machine or similar. These tests are to be repeated after every software change and after every change to the system, machine or similar or the periphery (network, broker, certificates, server, etc.). If malfunctions occur or are detected, the PLCcom OPC UA PubSub SDK must not be operated at the plant, machine or similar.
What is OPC UA PubSub?
OPC UA PubSub extends the well-known OPC UA client/server communication model. In the classic model, a client connects to a server, opens a session and reads, writes or monitors nodes. In the PubSub model, a publisher sends DataSet messages and one or more subscribers receive them.
The data is described by DataSets and fields. A transport such as UDP or MQTT delivers the messages. Depending on the selected encoding and transport, PubSub can be used for local UDP communication, multicast distribution, broker based MQTT communication or TLS protected MQTT scenarios.
What PLCcom OPC UA PubSub SDK has to offer
The add-on provides a high-level Java API for creating PubSub publishers and subscribers. The configuration stays explicit and readable: choose the transport, define the published fields, enable discovery if needed and then start the publisher or subscriber.
Communication and encoding
- UADP NetworkMessage support
- JSON NetworkMessage support
- UDP unicast communication
- UDP multicast communication
- UDP broadcast communication
- MQTT transport for UADP and JSON messages
- Secure MQTT with TLS broker certificate validation
Application API
- High-level UaPublisher and UaSubscriber classes
- Fluent configuration builders for Publisher and Subscriber
- Named field access for received DataSet messages
- Publisher and Subscriber diagnostic events
- Simple Start(), Stop() and close() lifecycle
- WriteValue and WriteValues methods for updating published field values
PubSub features
- PubSub discovery for DataSetMetaData exchange
- Static DataSetReader field configuration when discovery is not desired
- KeyFrame and DeltaFrame handling for UADP DataSet messages
- PKI based certificate handling in the familiar PLCcom SDK style
- Optional client certificate support for mutual TLS scenarios
- OPC UA PubSub message security support for applications that provide the required key material
Basic PubSub terms
| Term | Meaning in application code |
|---|---|
| Publisher | Sends DataSet messages through the configured transport. |
| Subscriber | Receives DataSet messages and raises data events. |
| PublishedDataSet | A named group of values that belongs together. |
| Field | One logical value inside a DataSet, for example "Temperature". |
| DataSetReader | Describes what a subscriber expects to receive. |
| Discovery | Optional metadata exchange so a subscriber can learn the field layout. |
Create and start a publisher
A publisher configuration describes what is sent and how it is transported. The following example publishes three machine values by using UADP over UDP. Each field has a logical PubSub name and a NodeId that identifies the value in the publisher data store.
UaPublisherConfiguration publisherConfiguration =
UaPublisherConfiguration.Build("MachineTelemetryPublisher",
"opcua:MachineTelemetry")
.WithTransport(PubSubTransportMode.DirectUnicast,
"opc.udp://localhost:4840")
.WithDiscovery("opc.udp://localhost:4841")
.WithPublishingInterval(1000)
.AddDataSet("MachineTelemetry", ds -> ds
.AddField("Temperature", new NodeId(1001, 2))
.AddField("Pressure", new NodeId(1002, 2))
.AddField("Speed", new NodeId(1003, 2))
.WithKeyFrameCount(10)
.WithInterval(1000));
After the configuration has been created, construct the publisher with your PLCcom license information and call Start(). The WriteValue method updates the current value of a field. The next scheduled publish cycle sends the changed values according to the DataSet configuration.
try (UaPublisher publisher =
new UaPublisher(userName, serialNumber, publisherConfiguration)) {
publisher.addErrorListener(event -> {
System.out.println(event.getMessage());
if (event.getException() != null) {
event.getException().printStackTrace();
}
});
publisher.Start();
publisher.WriteValue("MachineTelemetry", "Temperature", 42.5);
publisher.WriteValue("MachineTelemetry", "Pressure", 6.2);
publisher.WriteValue("MachineTelemetry", "Speed", 1450.0);
// Keep the application alive while publishing is required.
// Call publisher.Stop() when publishing should be stopped explicitly.
}
Create and start a subscriber
A subscriber configuration describes what is received and which transport is used. When discovery is configured and no static fields are defined for the DataSetReader, the subscriber can request the DataSetMetaData from the publisher and use the discovered field names.
UaSubscriberConfiguration subscriberConfiguration =
UaSubscriberConfiguration.Build("MachineTelemetrySubscriber")
.WithTransport(PubSubTransportMode.DirectUnicast,
"opc.udp://localhost:4840")
.WithDiscovery("opc.udp://localhost:4841")
.AddDataSetReader("opcua:MachineTelemetry",
"MachineTelemetry");
If discovery is not used, or if the field layout is intentionally fixed in the application, the fields can be listed directly in the DataSetReader configuration.
UaSubscriberConfiguration subscriberConfiguration =
UaSubscriberConfiguration.Build("MachineTelemetrySubscriber")
.WithTransport(PubSubTransportMode.DirectUnicast,
"opc.udp://localhost:4840")
.AddDataSetReader("opcua:MachineTelemetry",
"MachineTelemetry", ds -> ds
.AddField("Temperature")
.AddField("Pressure")
.AddField("Speed"));
The subscriber raises a DataReceived event when a DataSet message arrives. For UADP DeltaFrames the event can contain only the fields that changed. For KeyFrames and JSON messages the complete payload is available.
try (UaSubscriber subscriber =
new UaSubscriber(userName, serialNumber, subscriberConfiguration)) {
subscriber.addErrorListener(event -> {
System.out.println(event.getMessage());
if (event.getException() != null) {
event.getException().printStackTrace();
}
});
subscriber.addDataReceivedListener(event -> {
System.out.println("DataSet: " + event.getDataSetName());
System.out.println("Fields : " + event.getFields());
});
subscriber.Start();
// Keep the application alive while receiving is required.
// Call subscriber.Stop() when receiving should be stopped explicitly.
}
Using MQTT and secure MQTT
For broker based communication, use an MQTT transport mode and an MQTT broker endpoint. The same Publisher and Subscriber pattern is used. Only the transport endpoint changes, for example:
UaPublisherConfiguration publisherConfiguration =
UaPublisherConfiguration.Build("EnergyPublisher", "opcua:Energy")
.WithTransport(PubSubTransportMode.BrokerMqttJson,
"mqtt://localhost:1883")
.AddDataSet("Energy", ds -> ds
.AddField("Voltage", new NodeId(2001, 2))
.AddField("Current", new NodeId(2002, 2))
.AddField("Power", new NodeId(2003, 2)));
For TLS protected broker connections use an mqtts endpoint and configure the TLS settings in the SDK configuration. Broker certificates are validated by the configured certificate handling. If the certificate is not yet trusted and no application override accepts it, it is placed in the rejected certificate store so that the user can inspect it before trusting it.
Licensing
The PLCcom OPC UA PubSub SDK is a separately licensed add-on. The license information is passed when a UaPublisher or UaSubscriber instance is created.
UaPublisher publisher =
new UaPublisher("[Enter your UserName here]",
"[Enter your Serial here]",
publisherConfiguration);
System.out.println(publisher.getLicenceMessage());
Examples and further steps
The public Java example repository contains complete, runnable example projects for the PLCcom OPC UA SDK and the PubSub add-on. These examples show the typical application structure, configuration style, console output and certificate handling used by the SDK.
Public repository:
https://github.com/Indi-An/PLCcom-OpcUaSdk-examples-java
The PubSub add-on and the main PLCcom OPC UA SDK should always be used in the same version.