Skip to main content

Machine Learning

Prerequisites​

Before you begin, ensure you have the following:

Deploy​

To enable machine learning-based data prediction in OpenTwins, you must integrate Kafka-ML along with a service that supplies the required input data for the models. Refer to the architecture documentation to understand how this component interacts with the overall system.

Although OpenTwins includes two built-in services for this purpose, they both depend on Eclipse Hono, which we currently do not recommend. We strongly advise developing a custom service that sends input data to the Kafka-ML topic, ensuring it aligns with the specific requirements of your digital twin. This service can obtain the data from the related digital twin as well as from other twins, either real-time via Eclipse Ditto or historical from InfluxDB.

Kafka-ML​

To install Kafka-ML, follow the official instructions in its GitHub repository. Kafka-ML can be deployed in a Kubernetes cluster (recommended) or locally, depending on your infrastructure needs.

Kafka-ML facilitates seamless integration of machine learning models with Kafka. It provides the capability to:

  • Upload models from TensorFlow or PyTorch.
  • Train models directly within the system.
  • Deploy models for real-time inference using Kafka streams.

The Kafka-ML workflow is as follows:

  1. Input data is sent through a designated Kafka topic to trigger model inference.
  2. Kafka-ML processes the data and runs the prediction.
  3. The predicted results are returned via an output Kafka topic.

For an in-depth understanding of Kafka-ML’s features and configuration, we highly recommend consulting the official user guide available in its GitHub repository.

In OpenTwins documentation, we assume that models are already deployed, trained, and ready for inference within Kafka-ML.

Eclipse Hono to Kafka-ML​

danger

This component is currently unused because Eclipse Hono has been deprecated.
The plan is to migrate this component to the new architecture so that it reads data directly from Eclipse Ditto, ensuring a more efficient and scalable integration.

Error detection for Eclipse Hono with Kafka-ML​

danger

This component is currently unused because Eclipse Hono has been deprecated.
The plan is to migrate this component to the new architecture so that it reads data directly from Eclipse Ditto, ensuring a more efficient and scalable integration.

Connect​

To integrate Kafka-ML with OpenTwins, you need to establish an Eclipse Ditto connection in OpenTwins. This connection enables OpenTwins to receive data from Kafka-ML and update the corresponding digital twin. The process involves defining an Eclipse Ditto JavaScript mapping to convert incoming messages into the Ditto Protocol.

The connection must follow this data flow:

  1. Kafka-ML generates predictions and send data to Apache Kafka.
  2. Eclipse Ditto receives the data via a configured connection.
  3. The JavaScript mapping in Eclipse Ditto processes the data and updates the corresponding digital twin in OpenTwins.

Connection example​

Consider a machine learning model in Kafka-ML that predicts humidity and temperature for a device. The model outputs data in the format [humidity, temperature].

In OpenTwins, a twin exists with the ID example:sensor, containing two features: humidity and temperature. Each feature in Eclipse Ditto must include properties and a value. The following image shows the structure of the digital twin in Eclipse Ditto:

Example digital twin structure

To establish the connection between Kafka-ML and OpenTwins, you need to create an Apache Kafka connection in Eclipse Ditto. This connection receives and transforms predictions from Kafka-ML.

In the connection, a JavaScript mapping must be defined to transform messages from Apache Kafka. The mapping reads incoming messages, converts them to JSON, extracts values for each feature, and formats the message according to the Ditto Protocol before sending it. The function name mapToDittoProtocolMsg and the return Ditto.buildDittoProtocolMsg must always be included. The return value can be a single Ditto message or a list of Ditto messages.

Here is the JavaScript mapping for this example:

function mapToDittoProtocolMsg(headers, textPayload, bytePayload, contentType) {
    const jsonData = JSON.parse(textPayload);
    const humidity = jsonData[0];
    const temperature = jsonData[1];

    headers = Object.assign(headers, { 'Content-Type': 'application/merge-patch+json' });

    var features = {
          humidity: {
               properties: {
                    value: humidity 
               }
         },
         temperature: {
              properties: {
                   value: temperature
              }
         }
    };

    return Ditto.buildDittoProtocolMsg(
        'example',
        'sensor', 
        'things',
        'twin',
        'commands',
        'merge',
        '/features',
        headers,
        features
    );
}

In OpenTwins, there are two ways to create the connection: via the OpenTwins UI or the Eclipse Ditto API. In both cases we recommend to refer to the Eclipse Ditto documentation.

  1. In Grafana, open the OpenTwins app from the left-side menu.

  2. Navigate to the Connections section and click Create new connection.

  3. Select Kafka as the connection type and fill in the required details for the Apache Kafka broker.

    • Provide a unique identifier for the connection (avoid special characters except -).
    • If authentication is required, include the username and password in the URI.
    • The bootstrap servers usually match the URI.
    • Leave other fields as default unless necessary.

  4. Under Message Mapping, click Add JavaScript Mapping, enter an identifier, and paste the JavaScript code from above.

  5. Under Sources, click Add Source, then:

    • Specify the Kafka topic where Kafka-ML outputs predictions.
    • Set Authorization Context to pre-authenticated:kafkaml-connection.
    • Select the previously defined JavaScript mapping under Payload Mapping.

  6. Click Create Connection. If a success message appears, the Kafka-ML model is now connected.

Once the integration is complete, Kafka-ML predictions will be processed and updated in OpenTwins. For example, if Kafka-ML outputs [23.45, 23.12], the update message to digital twin will appear as follows:

Example digital twin message

With this setup, a machine learning model in Kafka-ML and OpenTwins are connected. Once the model is activated (via a script or any other method you choose), the generated data will automatically update the specified digital twin according to your configured settings. Additionally, in InfluxDB, you can differentiate between generated and real data using the authorization context.