Event Communication

Event Communication#

In modern industrial environments and Digital Twin architectures, real-time awareness of changes and state updates is crucial for maintaining system coherence and enabling reactive behaviors. Event-driven communication allows systems to respond immediately to changes in Asset Administration Shells, Submodels, and their properties, enabling scenarios such as automated workflows, monitoring dashboards, data synchronization, and compliance tracking.

BaSyx implements comprehensive event communication capabilities that automatically generate and publish events whenever changes occur to AAS, Submodels, properties, or registry descriptors. This event-driven architecture enables loose coupling between components while ensuring that all interested parties are notified of relevant changes in real-time.

The BaSyx ecosystem supports multiple event communication protocols. Repositories (AAS Repository, Submodel Repository, ConceptDescription Repository) support both MQTT for lightweight IoT scenarios and Apache Kafka for high-throughput enterprise environments. Registries (AAS Registry, Submodel Registry) currently support Kafka event streaming. Third-party applications can subscribe to these event streams to implement custom business logic, analytics, or integration workflows based on AAS lifecycle events.

Note

Two comprehensive examples demonstrating different event communication scenarios are available in the Examples on GitHub:

Feel free to try them out yourself!

Event Communication Architecture#

The following diagram illustrates how event-driven communication works across the BaSyx ecosystem:

@startuml rectangle "Client Applications" as clients rectangle "Event Consumers" as consumers rectangle "AAS Repository" as aasrepo rectangle "AAS Registry" as aasreg package "Event Infrastructure" { rectangle "MQTT Broker" as mqtt rectangle "Kafka Cluster" as kafka } clients -down-> aasrepo : CRUD Operations clients -down-> aasreg : Registry Operations aasrepo -down-> mqtt : MQTT Events aasrepo -down-> kafka : Kafka Events aasreg -down-> kafka : Kafka Events mqtt -down-> consumers : Event Subscriptions kafka -down-> consumers : Event Subscriptions note right of aasrepo AAS Repository supports: • MQTT Events • Kafka Events end note note right of aasreg AAS Registry supports: • Kafka Events only end note note bottom of consumers Event Types: • AAS Created/Updated/Deleted • Submodel Reference Changes • Registry Descriptor Changes end note note top of clients Similar event patterns apply to: • Submodel Repository • ConceptDescription Repository • Submodel Registry end note @enduml

Event Publishing and Consumption Flow#

The sequence diagram below shows the detailed process of how events are generated, published, and consumed:

@startuml participant "Client Application" as client participant "AAS Repository" as aasrepo participant "MQTT Broker" as mqtt participant "Kafka Cluster" as kafka participant "Event Consumer" as consumer client -> aasrepo : Create/Update AAS activate aasrepo aasrepo -> aasrepo : Process Operation aasrepo -> aasrepo : Generate Event par MQTT Publishing aasrepo -> mqtt : Publish MQTT Event\n(Topic: aas-repository/aas-repo/shells/created) mqtt -> consumer : Event Notification else Kafka Publishing aasrepo -> kafka : Publish Kafka Event\n(Topic: basyx-aas-events) kafka -> consumer : Event Notification end aasrepo -> client : Operation Success Response deactivate aasrepo note over consumer Event Processing: • Parse event payload • Extract AAS data • Trigger business logic • Update external systems end note note over mqtt MQTT Topics Examples: • aas-repository/aas-repo/shells/created • aas-repository/aas-repo/shells/updated • aas-repository/aas-repo/shells/deleted • sm-repository/sm-repo/submodels/updated • sm-repository/sm-repo/submodels/created end note note over kafka Kafka Topics: • basyx-aas-events • basyx-submodel-events • basyx-registry-events • basyx-conceptdescription-events end note @enduml

Event Types and Triggers#

BaSyx generates events for various operations across different components:

AAS Repository Events (MQTT & Kafka)#

  • AAS Created: Triggered when a new Asset Administration Shell is created

  • AAS Updated: Fired when AAS metadata or structure is modified

  • AAS Deleted: Generated when an AAS is removed from the repository

  • Submodel Reference Created: Triggered when Submodel references are added to an AAS

  • Submodel Reference Deleted: Generated when Submodel references are removed from an AAS

Submodel Repository Events (MQTT & Kafka)#

  • Submodel Created: Generated when new Submodels are created

  • Submodel Updated: Triggered when Submodel structure or metadata changes

  • Submodel Deleted: Fired when Submodels are removed

  • SubmodelElement Created: Generated when new SubmodelElements are added

  • SubmodelElement Updated: Triggered for individual property value updates

  • SubmodelElement Deleted: Fired when SubmodelElements are removed

  • SubmodelElements Patched: Generated when multiple elements are updated in batch

  • File Value Updated: Triggered when file attachments are modified

  • File Value Deleted: Generated when file attachments are removed

ConceptDescription Repository Events (MQTT & Kafka)#

  • ConceptDescription Created: Triggered when new ConceptDescriptions are created

  • ConceptDescription Updated: Fired when ConceptDescription metadata changes

  • ConceptDescription Deleted: Generated when ConceptDescriptions are removed

Registry Events (Kafka Only)#

  • Descriptor Registration: Fired when AAS or Submodel descriptors are registered

  • Descriptor Update: Triggered when registry information is modified

  • Descriptor Deletion: Generated when descriptors are removed from registries

Supported Event Protocols#

MQTT Event Communication#

MQTT provides lightweight, efficient event communication ideal for IoT scenarios:

  • Low Overhead: Minimal bandwidth requirements for resource-constrained environments

  • Quality of Service: Configurable delivery guarantees (QoS 0, 1, 2)

  • Topic-based Routing: Hierarchical topic structure for selective event subscription

  • Retained Messages: Last known state available for new subscribers

  • Bi-directional Communication: Support for both event publishing and command messaging

Apache Kafka Event Streaming#

Kafka offers enterprise-grade event streaming capabilities:

  • High Throughput: Handle millions of events per second

  • Durability: Persistent event storage with configurable retention

  • Partitioning: Parallel processing and horizontal scaling

  • Exactly-Once Semantics: Guaranteed message delivery without duplicates

  • Schema Evolution: Support for evolving event structures over time

Event Payload Structure#

BaSyx events follow the same structure as the element that was changed.

Property Change Event#

{
    "modelType" : "Property",
    "valueType" : "xs:string",
    "category" : "VARIABLE",
    "description" : [ {
        "language" : "en-us",
        "text" : "Legally valid designation of the natural or judicial person which is directly responsible for the design, production, packaging and labeling of a product in respect to its being brought into circulation."
    }, {
        "language" : "de",
        "text" : "Bezeichnung für eine natürliche oder juristische Person, die für die Auslegung, Herstellung und Verpackung sowie die Etikettierung eines Produkts im Hinblick auf das 'Inverkehrbringen' im eigenen Namen verantwortlich ist"
    } ],
    "idShort" : "InstanceId"
}

Industrial Use Cases#

Real-time Monitoring and Alerting#

Event-driven monitoring enables immediate response to critical changes:

  • Threshold Monitoring: Trigger alerts when sensor values exceed predefined limits

  • Equipment Status Tracking: Monitor machine state changes and availability

  • Quality Control: Detect and respond to quality parameter deviations

  • Predictive Maintenance: Correlate events to predict maintenance needs

Workflow Automation#

Events can trigger automated business processes:

  • Supply Chain Orchestration: Initiate procurement when inventory levels change

  • Quality Assurance: Automatically trigger inspection workflows for new products

  • Compliance Reporting: Generate reports when regulatory-relevant data changes

  • Data Synchronization: Keep external systems synchronized with AAS state

Analytics and Business Intelligence#

Event streams provide valuable data for analysis:

  • Performance Metrics: Calculate KPIs based on operational events

  • Trend Analysis: Identify patterns in equipment behavior over time

  • Cost Optimization: Track resource usage and operational efficiency

  • Customer Insights: Analyze product usage patterns from connected devices

Getting Started with BaSyx Events#

1. Minimal Setup with MQTT#

Start with the lightweight MQTT-based event communication:

  • Simple Docker Compose setup with MQTT broker

  • Pre-configured AAS Repository with MQTT event publishing

  • Example event consumers and monitoring tools

  • Basic event filtering and routing examples

2. Enterprise Kafka Setup#

Explore high-throughput event streaming:

  • Kafka cluster with AKHQ management interface

  • Multiple BaSyx components with Kafka integration

  • Advanced event processing and analytics examples

  • Event schema management and evolution

BaSyx Infrastructure Setup#

After executing

docker-compose up -d

the following components are started:

  • AAS Repository (http://localhost:8081/shells)

  • Submodel Repository (http://localhost:8081/submodels)

  • ConceptDescription Repository (http://localhost:8081/concept-descriptions)

  • AAS Registry (http://localhost:8082/shell-descriptors)

  • Submodel Registry (http://localhost:8083/submodel-descriptors)

  • AAS Discovery (http://localhost:8084/lookup/shells)

  • AAS Web UI (http://localhost:3000)

By leveraging the registry integration features of AAS Repository and Submodel Repository, the preconfigured AAS Environment serializations are loaded and automatically registered.

Advanced Event Processing#

Event Filtering and Routing#

  • Content-based Filtering: Route events based on payload content

  • Pattern Matching: Use regular expressions for complex event selection

  • Aggregation Windows: Combine multiple events into summary notifications

  • Rate Limiting: Control event frequency to prevent system overload

Event Transformation#

  • Format Conversion: Transform events between different schemas

  • Enrichment: Add contextual information from external sources

  • Correlation: Link related events across different AAS components

  • Anonymization: Remove sensitive data while preserving analytical value

Error Handling and Reliability#

  • Dead Letter Queues: Handle events that cannot be processed

  • Retry Mechanisms: Automatic retry with exponential backoff

  • Circuit Breakers: Prevent cascade failures in event processing

  • Monitoring and Alerting: Track event processing health and performance

🌟 BaSyx Kafka Events Example Setup#

This guide will help you set up and run the BaSyx Kafka Events Example using Docker. Make sure Docker is installed on your system before proceeding.

🚀 Getting Started#

✅ Prerequisites#

Ensure you have Docker installed and running on your device.

📦 How to Start the Example Containers#

  1. Open a terminal in this folder.

  2. Start the BaSyx containers with the following command:

    docker compose up -d

    This will launch all required services in detached mode.

🌐 Accessing the BaSyx Containers#

Service

URL

AKHQ Web GUI

http://localhost:8101

AAS Registry

http://localhost:8102/shell-descriptors

Submodel Registry

http://localhost:8103/submodel-descriptors

AAS Repository

http://localhost:8104/shells

Submodel Repository

http://localhost:8104/submodels

Submodel Service

http://localhost:8105/submodel

AAS Web GUI

http://localhost:8106

📖 Usage Instructions#

  1. Open the AKHQ GUI and verify that the events triggered by the AASX file deployment are successfully delivered.

  2. Monitor events using the Kafka CLI Consumer:

    docker logs -f consumer-aas-example

    More information about the Kafka CLI Consumer can be found in the Confluent Documentation.

⚠️ Important Notice#

The Registry events only handle descriptor updates for registration operations. For a more comprehensive view, including updates and detailed information, refer to the Repository events.

📌 Tear Down#

To stop and remove the BaSyx containers:

  1. Open a terminal in this folder.

  2. Shut down the containers with:

    docker compose down

Additional Resources#