New: Cybus Helm Charts 3.0.0.
Learn more.
Ctrlk
Contact Uscybus.io
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Heisenware Integration

How to integrate the Heisenware low-code platform with Connectware, including connecting the Heisenware MQTT client, feeding dashboards from Unified Namespace topics, and routing operator inputs back.

This guide describes how to integrate the Heisenware low-code app building platform with Connectware. Heisenware connects to the Connectware MQTT broker with its MQTT Client connector, subscribes to Unified Namespace (UNS) topics to feed dashboards and operator apps, and publishes operator inputs back into the topic hierarchy. A complete example file is available at the end of this guide.

Objectives

  • Creating a Connectware user and role that Heisenware uses to authenticate against the Connectware MQTT broker.

  • Connecting the Heisenware MQTT Client connector to the Connectware broker.

  • Subscribing to UNS topics to feed Heisenware dashboards and operator apps.

  • Publishing operator inputs from Heisenware and routing them into the topic hierarchy with a mapping.

Prerequisites

To follow this guide, you will need the following:

Connectware and Heisenware Integration

Heisenware is a low-code platform for building industrial applications, such as shop floor dashboards, operator apps, and monitoring tools. You assemble the backend logic from functions on a canvas and connect the function outputs to UI widgets. The function catalog includes the MQTT Client connector, an MqttClient class that manages client connections to an MQTT broker over TCP, TLS, and WebSockets.

The integration uses this connector in both directions:

  • Consuming UNS data: Heisenware connects out to the Connectware broker and subscribes to the UNS topics that the dashboard or operator app displays. Connectware remains the central broker, so no inbound firewall port to Heisenware is required, and Heisenware sees the same governed data as every other consumer.

  • Producing operator inputs: Heisenware apps publish operator inputs, such as a setpoint or an order confirmation, to a dedicated heisenware namespace. A Connectware mapping routes these messages into the topic hierarchy, so you control what enters the UNS and can validate or transform the messages on the way.

The only Connectware-side preparation is a user with scoped permissions and the routing mapping, both defined in a service commissioning file. The rest of the integration is configured in the Heisenware App Builder.

The MQTT topics in this guide follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). Adjust the topic filters and permissions to your own hierarchy.

Heisenware also provides an HTTP/REST connector that can call REST APIs, for example a route hosted by the Connectware HTTP Server. This guide focuses on MQTT, which fits streaming dashboard data best.

Creating a Connectware User for Heisenware

The Heisenware MQTT client authenticates against the Connectware broker with username and password, like any other MQTT client. For more information, see MQTT Client Authentication. We create the user and its role in the service commissioning file with the Cybus::User and Cybus::Role resources.

Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.

Integration Parameters

We add the password of the MQTT user and the UNS topic root as parameters, so you can set them when you install the service:

  • heisenwarePassword: The password that Heisenware uses to authenticate.

  • topicRoot: The root of the UNS topic hierarchy. Defaults to enterprise.

Heisenware User and Role

The role follows the principle of least privilege: Heisenware reads the whole UNS hierarchy for its dashboards and writes only into its own heisenware namespace. The read operation is equivalent to MQTT subscribe, the write operation to MQTT publish. For more information, see Permissions.

The resource identifier of the user becomes the username, prefixed with the service ID that you assign when you install the service. For example, with the service ID heisenware, the Heisenware app authenticates as heisenware.app.

Instead of defining the user in the service commissioning file, you can also create it in the Admin UI: click User on the navigation panel, add a user, and assign the same MQTT permissions in the Add Permissions panel. In that case, the username has no service ID prefix.

Connecting Heisenware to Connectware

You configure the Heisenware side in the App Builder. The following steps describe the workflow at a high level. For the complete function reference, see the MQTT Client connector in the Heisenware documentation.

Creating the MQTT Client Instance

  1. In the Heisenware App Builder, open the Function Explorer and browse to the Connectors category.

  2. Drag the MQTT Client connector onto the canvas.

  3. Call the create function and set an instance name, for example connectware.

  4. Call the connect function of the new instance. Set the url argument to mqtts://${CONNECTWARE_HOST}:8883 and pass the credentials in the options object: set username to the Connectware user, for example heisenware.app, and password to the value of the heisenwarePassword parameter.

Replace the following value:

  • ${CONNECTWARE_HOST}: The hostname or IP address of your Connectware instance.

The connect function returns true once the connection is established. Use the isConnected function to check the connection state at any time.

The mqtts:// scheme connects with TLS. The Heisenware backend must trust the server certificate of your Connectware instance. If Connectware uses a self-signed certificate, replace it with a certificate that is signed by a certificate authority that the Heisenware backend trusts. For more information, see CA Certificates. For unencrypted test setups, you can use mqtt://${CONNECTWARE_HOST}:1883 instead. Use TLS on port 8883 for production.

Heisenware provides a pre-configured instance named internal-mqtt that is connected to the internal broker of the Heisenware platform. Do not use this instance for the Connectware integration. Create a separate instance that connects to the Connectware broker.

Subscribing to UNS Topics

The onJsonMessage function subscribes to a topic filter and handles incoming messages in one step. The listener fires for every message, parses the payload as JSON, and provides the source topic in the __topic__ attribute of the data object:

  1. Call the onJsonMessage function of the connectware instance.

  2. Set the topic filter to the part of the UNS that the app displays, for example enterprise/hamburg/assembly/line-1/#. The MQTT wildcards + (single level) and # (multi-level) are supported.

  3. Connect the listener output to a display widget, such as a chart or a value box.

Subscribe as narrowly as the app allows. A dashboard that shows one production line does not need enterprise/#, and smaller subscriptions keep the message load in the Heisenware app low.

A Connectware endpoint publishes its values in a JSON structure that the listener parses directly. For example, a temperature reading on the topic enterprise/hamburg/assembly/line-1/press-01/temperature arrives with a payload like the following:

Publishing Operator Inputs

Operator apps write data back, for example a setpoint that a worker enters in a form. Use the publishJson function, which serializes a JSON object and publishes it to a topic:

  1. Call the publishJson function of the connectware instance from your app logic, for example triggered by a button widget.

  2. Set the topic to the heisenware namespace, mirroring the equipment hierarchy, for example heisenware/hamburg/assembly/line-1/press-01/operator-input.

  3. Pass the operator input as the message object.

A published message looks like the following:

The Heisenware user has write permission only on the heisenware/# namespace, so a misconfigured app cannot publish into the UNS directly.

Routing Operator Inputs into the UNS

A mapping republishes the operator inputs from the heisenware namespace into the UNS hierarchy. The named wildcard #topic matches the remainder of the topic path and reuses it in the output topic as $topic:

A message published to heisenware/hamburg/assembly/line-1/press-01/operator-input now arrives on enterprise/hamburg/assembly/line-1/press-01/operator-input, where any other Connectware service can pick it up, for example to write the setpoint to a PLC.

This mapping is the single point where Heisenware data enters the UNS. To validate or reshape the messages before they are republished, add filter or transform rules to the mapping. For more information, see Data Processing Rules and Cybus::Mapping.

Verifying the Integration

  1. Install the service commissioning file, assign a service ID, for example heisenware, and set the heisenwarePassword parameter. See Installing Services.

  2. In the Heisenware App Builder, call the connect function and check that it returns true. If the connection fails, check the broker URL, the port, the certificate settings, and the credentials. Remember that the username carries the service ID prefix, for example heisenware.app.

  3. Publish a test message to a UNS topic that the app subscribes to, for example enterprise/hamburg/assembly/line-1/press-01/temperature, with an MQTT client or the Admin UI. Check that the connected widget in Heisenware shows the value.

  4. Trigger an operator input in the Heisenware app.

  5. Open the Data Explorer and check the message on the heisenware namespace and its republished copy in the UNS hierarchy, for example on enterprise/hamburg/assembly/line-1/press-01/operator-input.

Service Commissioning File Example

heisenware-example.yml
2KB
Open
PreviousAVEVA PI System IntegrationNextCloud & IoT Platforms

Last updated

Was this helpful?