Overview

The "IE Databus Example" module is a Mendix module designed to demonstrate the integration of the Industrial Edge (IE) Databus into a Mendix application. The IE Databus is a high-performance, low-latency communication layer used to facilitate real-time data exchange between different systems in industrial environments.

Documentation

Introduction & Overview

The "IE Databus Example" module is a Mendix module designed to demonstrate the integration of the Industrial Edge (IE) Databus into a Mendix application. The IE Databus is a high-performance, low-latency communication layer used to facilitate real-time data exchange between different systems in industrial environments.

The Databus provides access to the data of the field devices. The Industrial Edge Runtime sends the data from the field devices to the Databus. If you want to use this data for your custom application, you must connect your application to the Databus of the corresponding Industrial Edge Device (IED). Connectors are needed to fetch data from field devices. The configuration of the application is stored in the Databus, which allows the access of the app to the Databus.

This module provides an example implementation of how to publish and subscribe to topics within the Industrial Edge Databus. It simplifies the process of integrating industrial equipment and devices into Mendix applications using the capabilities of the IE Databus.

Detailed Documentation can be found here:

• Industrial-Operations-X
• Industrial Edge Documentation

Typical Use Cases

The "IE Databus" is typically used in the following scenarios:

• Industrial IoT Data Monitoring: Real-time data acquisition from industrial machinery and equipment, which can be displayed or used in Mendix apps.
• Predictive Maintenance: Sending sensor data from machinery to an analytics engine that predicts potential failures.
• Data Aggregation: Collect data from multiple machines, aggregate them, and send the combined data to a central monitoring system.
• Remote Monitoring: Allow real-time data to be streamed to a Mendix app for remote monitoring of factory operations.
• Data distribution: Distribute data between different apps.

Prerequisites

Ensure the following dependencies are installed from the Marketplace:

• Mendix Version 10.6.11 or higher
• MqttConnector Marketplace Module

Setup the databus

Installation Guide

Step 1: Import the Module

• Open your Mendix project in Studio Pro.
• Download from the marketplace the MqttConnector module and the IEDatabusExample
• Wait for the module to be added to your project.

Step2: Configure the Module

• Add the navigation microflow 00.Pages - NAV_Databus_Overview to your navigation menu.

Step 3: Configure Security

• Ensure that the appropriate roles and permissions are configured to allow the use of the IE Databus functionality.

Usage Guide

Domain Model

The persistent part of the domain model structure matches the response structure of the meta data topics. Since we want to make it possible to connect to multiple Databus, the domain model starts with a Databus entity at the top. A databus can manage the messages of several connectors (also known as adapters).

The DataPoint entity serves as a wrapper for several data points and contains the information of the topic on which the data is published and, if permitted, the topic on which data may be published.

The DataPointDefinition entity always represents a specific data point. This contains information about the specific variable ID, the name and the data type.

Since we also want to show in this example how to subscribe to a topic and use the data, we have added the LatestValue entity to this domain model by always storing the last value received. On closer inspection, it is noticeable that all values are saved here as a string. If you want to work with these values (e.g. calculate something), you may need to map them to the correct data type, which you can do using the information from the DataPointDefinition.

The actual processing of incoming messages is done via the non-persistent entities.

Folder Structure

_USE_ME

The _USE_ME folder contains the typical examples of the Databus functions:

• How to connect to the Databus,
• How to process the metadata,
• How to subscribe to a specific topic,
• How to process incoming messages and
• How to publish messages to a specific topic.

Private

This folder includes all the background logic. Modify these documents only in special cases.

Example:  Connect to the Databus

1. In you app, navigate to the Databus Overviewpage. Here you can find all created databus or create a new one.
2. Click on “New” to create a new Databus. When we create a new databus, we use the existing functions of the MQTTConnector. The Databus entity is a specialization of the ConnectionDetail entity of the MQTTConnector.
   • For the internal data bus, you must establish a connection with the broker host: ie-databus at port 1883. The external data bus runs on the device IP at port 9883. (Details about the difference between internal and external Databus can be found in the IE Documentation. As a short summary: The internal databus handles the data exchange within an Edge device, as soon as I want to use data via MQTT outside the Edge device (receive/send) the external databus is added.)
   • The access data for the Databus or the External Databus must be stored under “Authentication method”. That the selector to BASIC
   • If security is activated in the external data bus, the corresponding certificates must be stored here, by activating the slider.
3. Click the “Connect/Reconnect” button to establish a connection.

To better understand the technical implementation, look in the folder _USE_ME - 01.DatabusConnection.

Example: Process Metadata

1. Click on the Info icon of the databus.
2. On the left side of the detail page you will find an overview of the connectors for this databus. The connectors displayed also depend on the user that was used to log on to the databus.

There are two ways to create these connectors in Mendix:

• Use the “New” button to create the connector manually. It expects a name and a metadata topic
• You can also create a connector that has the metadata topic ie/m/#. This one will autmatically check for all available metadata topics and create the connectors automatically.

In both cases you have to click on the Get Metadata button. Then deactivate the button again to see the list of connectors + the metadata structure.

What happens technically in the background is basically that we subscribe to a topic. As described in the Databus documentation: “Metadata messages need to set the retain=true flag for the MQTT message. This is needed to make the metadata available to clients which connect at a later time.”

As soon as you subscribe to a metadata topic, you receive the metadata structure.

The subscribe process is covered by the MQTTConnector through a Java action.

This Java action expects an “On message microflow” which is executed as soon as a message comes in on this topic. In the case of metadata handling, we have created a logic that handles the mapping for us.

For details, you can look at the corresponding microflow in _USE_ME - 02.MetadataHandling – Topic_OnMessage_MetaData.

Example: Subscribe to topic

As just described, the subscription process is covered by the MQTT connector functions. We have included an example where you can see exactly how the process works and how the data can be further processed in Mendix at the end.

You can find the details in the _USE_ME - 03.SubscribeToTopics.

On the example page you can see the real-time values after you have subscribed to a topic.

Process incoming messages

The exciting part is the processing of incoming messages.

This can vary depending on the use case and it is also possible that different microflows are used for different topics. It is important to note that you would then have to create a separate subscription logic to process the data correctly - therefore always pass the correct “On message microflow” to the JavaAction.

For this example, we have chosen a very generic approach that covers a broad range of scenarios.

We always save the current value together with the DataPointDefinition so that we have the context information available.

Example: Publish messages to a topic.

An example of how to publish a message to a topic can be found in the folder: 05.PublishOnTopic.

Happy coding! Enjoy seamless integration of Siemens Edge devices with the Mendix Connector.