PLCcom OPC UA SDK class library documentation
First steps PLCcom OPC UA SDK for Java
The PLCcom OPC UA SDK for Java is a high-level Java SDK for building OPC UA client and server applications. It provides the OPC UA stack, the application APIs, certificate handling and the convenience classes that are needed to read, write, browse, monitor, expose and manage OPC UA data from Java applications.
The SDK is designed for application developers who want to work with OPC UA without having to implement the protocol details themselves. You configure the connection or server endpoint, create the SDK object, register the events that matter to your application and then use strongly typed Java methods for the common OPC UA workflows.
Where to get the SDK
The PLCcom OPC UA SDK is distributed as a commercial SDK package. Trial and commercial information are available on the PLCcom OPC UA SDK product pages. The public example repository contains complete Java workshops for the client and server APIs.
| 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 | Runnable examples for the PLCcom OPC UA SDK for Java. |
Prerequisites
Before you create an application with the SDK, make sure that the Java build environment and the SDK artifacts are available. The SDK is compiled for Java 1.8 compatibility and can be used from modern JDK installations that support Java 1.8 compatible bytecode.
- 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
- PLCcom OPC UA SDK artifacts in the local or company Maven repository
- Valid PLCcom OPC UA SDK license information
- Network access to the OPC UA server, or a configured endpoint for your own server
- A PKI directory and trusted certificates for secure production communication
If the SDK artifact is not available from a configured Maven repository, install or deploy it according to your delivery package or build process.
Using the SDK with Maven
Reference the SDK like any other Maven library. Replace 10.x.x
with the version delivered with your PLCcom SDK package.
<dependencies>
<dependency>
<groupId>com.indi-an.plccom</groupId>
<artifactId>plccom-opc-ua-sdk</artifactId>
<version>10.x.x</version>
</dependency>
</dependencies>
The SDK and its add-ons are released with matching version numbers. When an add-on such as PubSub is used, keep the SDK and add-on versions aligned.
Important note
With the PLCcom OPC UA SDK you or the user can monitor and control systems, machines or similar assets at your own discretion. For this purpose the user must 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, certificates, server, configuration, etc.). If malfunctions occur or are detected, the PLCcom OPC UA SDK must not be operated at the plant, machine or similar.
What is OPC UA?
OPC UA is the platform independent communication standard from the OPC Foundation. It is used to exchange industrial data between machines, control systems, applications, gateways and enterprise systems. OPC UA provides a structured address space, typed values, secure sessions, subscriptions, alarms, historical access and method calls.
In the classic OPC UA client/server model, a client connects to a server, opens a session and then reads, writes, browses or monitors nodes in the server's address space. The PLCcom OPC UA SDK provides both sides: a high-level client API for connecting to existing servers, and a high-level server API for exposing your own data as an OPC UA server.
What PLCcom OPC UA SDK has to offer
Client features
- Endpoint discovery and endpoint sorting by security level
- OPC UA TCP and HTTPS client connections
- Automatic connect, reconnect and disconnect support
- Read and write by NodeId or by readable browse path
- Browsing, attribute access and browse path translation
- Subscriptions and monitored items for DataChange and event notifications
- Method calls with simple and structured arguments
- Alarm and condition access
- Historical data and historical event access
- Complex type handling for structured OPC UA data
Server features
- OPC UA server endpoint configuration for opc.tcp and opc.https
- Configurable security policies and user token policies
- High-level address space creation with folders, objects and variables
- Scalar values, arrays and custom structured data
- Read/write validation and written-value events
- Session events for client connect and disconnect handling
- Methods, alarms, events and historical access support
- NodeSet import for model based server creation
- Reverse Connect support for selected scenarios
Security and operations
- PKI directory based certificate stores
- Application certificates and HTTPS certificates
- Certificate validation callbacks for user-controlled decisions
- Trusted, rejected, own and private certificate handling
- Recommended OPC UA security modes for production-oriented configurations
- Operation limits, session limits and keep-alive monitoring
Basic terms
| Term | Meaning in application code |
|---|---|
| UaClient | High-level client object that manages a session to an OPC UA server. |
| ClientConfiguration | Connection, endpoint, user identity, certificate and timing settings for a client session. |
| UaServer | High-level server object that exposes an OPC UA endpoint and address space. |
| UaServerConfiguration | Application identity, endpoints, security policies and operation limits for a server. |
| NodeId | The unique address of a node in an OPC UA address space. |
| Browse path | A readable path through the address space, for example Objects.Plant.Line1.Machine1.Temperature. |
| Subscription | A server-side object that sends notifications to the client when monitored items change. |
Create and connect a client
For a client application, start by discovering the server endpoints. Select the
endpoint that matches your security requirements, create a
ClientConfiguration and pass your PLCcom license information when
constructing the UaClient.
String userName = "[Enter your UserName here]";
String serialNumber = "[Enter your Serial here]";
String serverUrl = "opc.tcp://localhost:48410";
EndpointDescription[] endpoints =
UaClient.discoverEndpoints(new URI(serverUrl), certificateValidator);
endpoints = UaClient.sortBySecurityLevel(endpoints, SortDirection.Asc);
ClientConfiguration configuration =
new ClientConfiguration(endpoints[0]);
configuration.setCertificateValidator(certificateValidator);
try (UaClient client =
new UaClient(userName, serialNumber, configuration)) {
System.out.println(client.getLicenceMessage());
client.addSessionKeepAliveListener((serverStatus, serverState) -> {
System.out.println("Server state: " + serverState);
});
client.connect();
NodeId temperature =
client.getNodeIdByPath("Objects.Plant.Line1.Machine1.Temperature");
ReadResponse response = client.readValue(temperature);
DataValue value = response.getResults()[0];
System.out.println("Temperature: " + value.getValue().getValue());
}
For secure endpoints, the server certificate is validated by the configured certificate validator and PKI store. If the certificate is not trusted yet and the application does not explicitly accept it, it is placed in the rejected store so that the user can inspect it before trusting it.
Read, write and browse
The client API supports direct NodeId access as well as path based access. Path based access is convenient for application code because the SDK resolves the NodeId in the background and can cache the result.
NodeId rpmNode =
client.getNodeIdByPath("Objects.Plant.Line1.Machine1.RPM");
ReadResponse readResponse = client.readValue(rpmNode);
System.out.println(readResponse.getResults()[0].getValue().getValue());
StatusCode writeStatus =
client.writeValue(rpmNode, 1500);
System.out.println("Write status: " + writeStatus);
Browsing is used to discover what a server exposes. Start from a known node,
for example Identifiers.ObjectsFolder, and browse forward through
the address space.
BrowseDescription browse = new BrowseDescription();
browse.setNodeId(Identifiers.ObjectsFolder);
browse.setBrowseDirection(BrowseDirection.Forward);
browse.setIncludeSubtypes(true);
browse.setNodeClassMask(NodeClass.Object, NodeClass.Variable);
browse.setResultMask(BrowseResultMask.All);
BrowseResponse browseResponse = client.browse(browse);
Monitor values with subscriptions
Subscriptions are the efficient way to receive value changes. Instead of polling values in a loop, create monitored items and let the server send notifications when values change.
UaSubscription subscription =
client.getSubscriptionManager().createSubscription();
MonitoringParameters parameters = new MonitoringParameters();
parameters.setSamplingInterval(1000.0);
NodeId temperature =
client.getNodeIdByPath("Objects.Plant.Line1.Machine1.Temperature");
ReadValueId valueToMonitor =
new ReadValueId(temperature, UaAttributes.Value.getValue());
MonitoredItemCreateRequest request =
new MonitoredItemCreateRequest(valueToMonitor,
MonitoringMode.Reporting,
parameters);
subscription.createMonitoredItems(
java.util.Arrays.asList(request),
new MonitoredItemNotificationListener() {
public void onValueNotification(
MonitoredItem monitoredItem,
DataValue dataValue) {
System.out.println("Changed: "
+ dataValue.getValue().getValue());
}
public void onEventNotification(
MonitoredItem monitoredItem,
EventFieldList eventFieldList) {
// Event notifications can be handled here when the monitored
// item is configured for event monitoring.
}
});
Create and start a server
A server application starts with a UaServerConfiguration. The
configuration defines the application identity, endpoints, security policies,
user token policies and operation limits. After the server has been started,
you can create folders, objects and variables in the address space.
String userName = "[Enter your UserName here]";
String serialNumber = "[Enter your Serial here]";
UaServerConfiguration configuration = new UaServerConfiguration();
configuration.setApplicationName("My OPC UA Server");
configuration.setApplicationUri("urn:localhost:my-company:my-server");
configuration.setProductUri("https://www.example.com/my-server");
configuration.setNamespaceUri("http://www.example.com/opcua/my-server");
configuration.setBaseAddresses(
java.util.Arrays.asList("opc.tcp://localhost:48410"));
// Use recommended security modes for production configurations.
// For a first local experiment you may intentionally use SecurityMode.NONE.
configuration.setSecurityModes(UaServer.getRecommendedSecurityModes());
try (UaServer server = new UaServer(userName, serialNumber)) {
System.out.println(server.getLicenceMessage());
server.addSessionListener(new UaServer.UaSessionListener() {
public void onSessionCreated(UaServer.UaSessionInfo session) {
System.out.println("Client connected: "
+ session.getSessionName());
}
public void onSessionClosed(UaServer.UaSessionInfo session) {
System.out.println("Client disconnected: "
+ session.getSessionName());
}
});
server.start(configuration);
UaFolder plant =
server.createFolder("Plant",
UaRolePermissions.WITHOUT_RESTRICTIONS);
UaVariable<Double> temperature =
server.createVariable(plant,
"Temperature",
UaRolePermissions.WITHOUT_RESTRICTIONS,
Double.class,
21.5,
false);
temperature.setValue(22.0);
}
The workshops show a complete server configuration including application identity, opc.tcp and opc.https endpoints, recommended security modes, user authentication, certificate store creation, write validation and live value updates.
Certificate handling
Secure OPC UA communication depends on certificates. The PLCcom SDK follows a PKI directory structure that is familiar from OPC UA applications: own certificates and private keys are stored separately from trusted and rejected certificates. If validation is not overridden by the application and a remote certificate is not trusted yet, the certificate is placed in the rejected store for manual inspection.
| Store area | Purpose |
|---|---|
| own | Own application certificate files. |
| private | Private keys belonging to the own certificates. |
| trusted | Certificates that are accepted for communication. |
| rejected | Certificates that were seen but not trusted automatically. |
The client and server certificate helper classes can load existing certificates, create missing certificates and build certificate stores for the configuration. Application code can still provide validation callbacks when a project needs explicit user decisions or custom trust rules.
Licensing
The PLCcom OPC UA SDK is activated by passing the license information when a client or server instance is created. The license information is provided with your trial or commercial license.
UaClient client =
new UaClient("[Enter your UserName here]",
"[Enter your Serial here]",
clientConfiguration);
System.out.println(client.getLicenceMessage());
UaServer server =
new UaServer("[Enter your UserName here]",
"[Enter your Serial here]");
System.out.println(server.getLicenceMessage());
Examples and further steps
The public Java example repository contains complete, runnable example projects. The examples are intentionally written as workshops: they explain the scenario, show the configuration, print useful console output and demonstrate the expected certificate handling.
Public repository:
https://github.com/Indi-An/PLCcom-OpcUaSdk-examples-java
Recommended learning path:
- Start the simple server workshop.
- Connect with the endpoint discovery client workshop.
- Read, write and browse the address space.
- Add subscriptions and monitored items.
- Move to alarms, history, methods, complex types and server-side workflows.
For message based OPC UA PubSub communication, use the PLCcom OPC UA PubSub SDK add-on in the same version as the main PLCcom OPC UA SDK.