Introduction
Events are a powerful feature of OPC UA with several advantages compared to data-change monitoring:
- No need for a sampling interval
- Rich, structured payloads instead of single values
- Strong semantics via EventTypes
- Propagation and aggregation (bubbling up) within the information model hierarchy
- Built-in server-side filtering to reduce network traffic
Despite these benefits, events are often underutilized due to their perceived complexity. With version 1.5 of the open62541 SDK, we focused on significantly improving the usability and ergonomics of the event API. This article walks through the key enhancements on both the client and server side.
Human-Readable Event Field Syntax
The event payload, made up of the event fields, is defined by EventTypes, which are specialized ObjectTypes within the OPC UA information model. Many companion specifications define custom EventTypes for their application domain. For example, the AutoID companion specification defines EventTypes for barcode and RFID detection.
The following image gives an overview of the standard event fields from the BaseEventType. These are always available and form the foundation for all events.
On the client side, relevant event fields are selected via the select-clause of an EventFilter. This clause consists of SimpleAttributeOperand entries, which are BrowsePaths augmented with attribute and index-range metadata.
In v1.5, we introduced a concise and human-readable syntax for defining these operands. Instead of verbose structures, event fields can now be expressed as simple path strings.
For example:
- /1:Robot/2:Axis1/2:Angle
- /2:Line/2:VisualInspection/3:Camera/3:CapturedImage#Value[0:100,0:100]
The nodes from the EventType are addressed with their browse-name (with an optional colon-separated prefix for th namespace index) and slashes delimit hierarchy levels. For full details, see the open62541 Documentation and our ETFA 2024 paper on event filters.
This representation is now used consistently across both client and server APIs, ensuring a unified model for defining, transmitting, and consuming event data.
Client-Side: Register for Event Monitoring
On the client side, registering for event monitoring has been streamlined considerably. Previously, constructing the select-clause required multiple lines of boilerplate code. With v1.5, the entire clause can be parsed directly from a single human-readable string.
Once monitoring is active, the server sends event notifications to the client. These are delivered to a user-defined callback. As seen in the above code snippet, the event fields arrive in the callback as a key-value map. The keys are the human-readable syntax for each event field. At the same time, the order of the event fields is preserved from the original select-clause. So a resource-efficient indexed access remains possible. This dual-access pattern (by key or index) provides both readability and performance.
Server-Side Event Generation in open62541
On the server side, event creation has been consolidated into UA_Server_createEvent as a single, expressive API. This function also leverages the human-readable event field syntax.
When generating an event, field values can originate from four possible sources:
- Inline (mandatory): The most important event fields are inlined in the call to UA_Server_createEvent.
- Field Map (optional): The key-value map in the eventFields argument maps from human-readable definitions of the event fields to the (variant) value.
- Event Instance (optional): If an event field could not be resolved by the previous, the eventInstance argument refers to an ObjectNode in the information model. Typically this object instantiates the EventType of the event. The server then uses the members of this object to resolve the content of the event fields.
- Default Values (internal): If mandatory fields from the BaseEventType remain undefined from the prior sources, default values are created internally. For example, the /Time field is set to the current time and a random ByteString is used for the unique /EventId field.
This layered resolution model provides flexibility while maintaining clarity.
Summary
OPC UA events are a highly expressive and efficient mechanism for conveying structured information. With version 1.5, the open62541 API significantly lowers the barrier to entry by:
- Introducing a human-readable field syntax
- Simplifying client-side filter construction
- Providing structured and intuitive callback data
- Unifying and streamlining server-side event creation
These improvements make event-based architectures more accessible and practical for real-world deployments.