HiveMQ Integration

How to integrate HiveMQ with Connectware, including HiveMQ Cloud and self-hosted platform setup, bridging shop floor data from an ISA-95 topic hierarchy, and receiving commands in return.

This guide describes how to integrate HiveMQ with Connectware. You configure a service commissioning file that bridges selected shop floor data from the Connectware Unified Namespace (UNS) to a HiveMQ broker and receives commands from enterprise applications in return. The guide covers both HiveMQ Cloud and a self-hosted HiveMQ Platform. A complete example file is available at the end of this guide.

Objectives

• Preparing a HiveMQ Cloud cluster or a self-hosted HiveMQ Platform broker for the connection.

• Establishing a TLS-encrypted MQTT connection between Connectware and HiveMQ.

• Bridging shop floor data from an ISA-95 topic hierarchy to HiveMQ topics.

• Receiving commands from enterprise applications in Connectware.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware.

• A HiveMQ broker: either a HiveMQ Cloud cluster, or a self-hosted HiveMQ Platform installation with administrative access to its configuration.

• Access to the Admin UI with sufficient user permissions.

• Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, connections, endpoints, and mappings).

Connectware and HiveMQ Integration

HiveMQ is an enterprise MQTT platform, available as the managed HiveMQ Cloud service and as the self-hosted HiveMQ Platform. Connectware connects to it through the MQTT connector, like to any other MQTT broker.

In this integration, Connectware acts as the shop floor gateway: it connects the machines, normalizes their data into the UNS topic hierarchy, and governs who can access what. The HiveMQ broker is the enterprise messaging backbone that distributes data to IT consumers such as analytics platforms, dashboards, or other sites. The mappings in this guide bridge only selected topics of the UNS to HiveMQ, so the enterprise side sees curated data instead of raw machine traffic.

A few HiveMQ characteristics matter for this integration:

• HiveMQ supports MQTT 3.1, 3.1.1, and 5.0 with all Quality of Service (QoS) levels, including QoS 2. The MQTT connector connects with MQTT 3.1.1 unless you set protocolVersion: 5 on the connection. The default works with HiveMQ without changes; set protocolVersion: 5 only if you want to use MQTT 5 features such as message expiry or user properties (see MQTT Connection Properties).

• HiveMQ supports shared subscriptions ($share/<group>/<topic>) for both MQTT 3 and MQTT 5 clients, which lets multiple enterprise consumers split the load of the bridged telemetry among themselves.

• HiveMQ Cloud only accepts TLS connections on port 8883, authenticated with the MQTT credentials that you create in the HiveMQ Cloud console.

• If a second client connects with the same client ID, HiveMQ disconnects the first client. Choose a client ID that is unique on the broker.

The MQTT topics on the Connectware side follow an ISA-95-style equipment hierarchy (<enterprise>/<site>/<area>/<line>/<cell>). The mapping subscribes with wildcards across all levels, so any machine in the hierarchy is picked up without changing the integration. On the HiveMQ side, this guide uses the uns/ prefix for the bridged shop floor data and the cmd/ prefix for commands from enterprise applications.

Preparing HiveMQ Cloud

1. Log in to the HiveMQ Cloud console and create a cluster, or select an existing one. The overview page of the cluster shows the cluster URL, which is the hostname for the connection.

2. Open the Access Management tab of the cluster.

3. In the Access Credentials area, create a credential for Connectware: define a username and a password, and assign the Publish and Subscribe permission.

The Serverless plan assigns one of the built-in permissions (Publish and Subscribe, Publish Only, or Subscribe Only) per credential. The Starter plan and above support custom roles and permissions with topic filters, which you can use to restrict the Connectware credential to the uns/# and cmd/# topic filters used in this guide. For more information, see HiveMQ Cloud Authentication and Authorization.

Preparing a Self-Hosted HiveMQ Platform

A self-hosted HiveMQ Platform accepts MQTT connections on the standard port 1883 by default, without TLS.

HiveMQ ships with the hivemq-allow-all-extension, which authorizes every MQTT client without credentials. This is intended for evaluation only. Before you use HiveMQ in production, remove the hivemq-allow-all-extension and add a security extension, for example the HiveMQ Enterprise Security Extension or the HiveMQ File RBAC community extension (see HiveMQ Security).

To accept TLS connections on port 8883, add a tls-tcp-listener with a keystore to the config.xml file of the broker (see HiveMQ Listeners). Create a username and password for Connectware in the security extension of your choice, with permissions to subscribe to the uns/# topic filter and to publish to the cmd/# topic filter.

HiveMQ Connection Parameters

The connection requires the hostname of the broker, the credentials created for Connectware, and a client ID. We add them as parameters to the service commissioning file, so you can set them when you install the service.

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.

• hivemqHost: The hostname of the HiveMQ broker. For HiveMQ Cloud, this is the cluster URL from the overview page of the cluster, for example a1b2c3d4e5f6.s1.eu.hivemq.cloud.

• hivemqUsername and hivemqPassword: The MQTT credentials created for Connectware.

• clientId: The MQTT client ID. HiveMQ disconnects an existing connection that uses the same client ID.

• topicRoot: The root of the MQTT topic hierarchy on the Connectware side. Defaults to enterprise.

parameters:
  hivemqHost:
    description: Hostname of the HiveMQ broker or HiveMQ Cloud cluster URL
    type: string
    default: a1b2c3d4e5f6.s1.eu.hivemq.cloud

  hivemqUsername:
    description: Username of the MQTT credential created for Connectware
    type: string
    default: connectware

  hivemqPassword:
    description: Password of the MQTT credential
    type: string

  clientId:
    description: MQTT client ID, must be unique on the broker
    type: string
    default: connectware-shopfloor

  topicRoot:
    description: Root of the MQTT topic hierarchy on the Connectware side
    type: string
    default: enterprise

HiveMQ Connection

To connect to HiveMQ, we set up a Cybus::Connection resource that uses the MQTT connector with scheme: mqtts on port 8883, which matches HiveMQ Cloud and a self-hosted broker with a TLS listener.

resources:
  hivemqConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref hivemqHost
        port: 8883
        scheme: mqtts
        username: !ref hivemqUsername
        password: !ref hivemqPassword
        clientId: !ref clientId
        keepalive: 60

The MQTT connector defaults to a keep-alive interval of 0, which disables client-side keep-alive pings. A value of 60 seconds lets both sides detect a broken connection even when no data flows.

If the certificate of a self-hosted broker is not signed by a public certificate authority (CA), provide the root CA certificate with the caCert property. To connect to a self-hosted broker without a TLS listener, set scheme: mqtt and port: 1883. For all available connection parameters, see MQTT Connection Properties.

Publishing Shop Floor Data to HiveMQ

A Cybus::Mapping resource bridges telemetry from the ISA-95 topic hierarchy to HiveMQ. The named wildcards +site, +area, +line, and +cell capture the levels of the source topic, and the publish side reuses them as $site, $area, $line, and $cell to mirror the hierarchy under the uns/ prefix.

telemetryMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: !sub '${topicRoot}/+site/+area/+line/+cell/telemetry'
          qos: 1
        publish:
          connection: !ref hivemqConnection
          topic: uns/$site/$area/$line/$cell/telemetry
          qos: 1

A message published to enterprise/hamburg/assembly/line-1/press-01/telemetry now arrives on the HiveMQ topic uns/hamburg/assembly/line-1/press-01/telemetry. Any enterprise application that subscribes to uns/# receives the complete bridged hierarchy. The payload is forwarded unchanged. To reshape it before it reaches HiveMQ, for example to add a timestamp or flatten a structure, add rules to the mapping (see Rule Engine).

The mapping bridges only the telemetry leaf of the hierarchy. Machine-internal topics stay on the shop floor. To bridge additional data, add further mapping entries with their own topic filters instead of widening the wildcard, so the selection remains explicit.

Receiving Commands from HiveMQ

For the opposite direction, a Cybus::Endpoint resource subscribes to a command topic on the HiveMQ broker, and a mapping republishes every command to the Connectware topic hierarchy, where any other Connectware service can pick it up, for example to write a setpoint to a PLC.

commandEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Mqtt
    connection: !ref hivemqConnection
    subscribe:
      topic: cmd/shopfloor/commands
      qos: 1

commandMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          endpoint: !ref commandEndpoint
        publish:
          topic: !sub '${topicRoot}/backend/hivemq/commands'

Any enterprise application that is authorized to publish to cmd/shopfloor/commands on the HiveMQ broker can now send messages to the shop floor. Connectware republishes them to enterprise/backend/hivemq/commands.

Verifying the Integration

1. Install the service and set the parameters with the values of your HiveMQ broker.

2. Check that the connection is in the Connected state on the service details page in the Admin UI. If the credentials are wrong, the connection does not reach the connected state.

3. Subscribe to the bridged topics on the HiveMQ side. On HiveMQ Cloud, open the Web Client tab of the cluster, connect with your credentials, and subscribe to uns/#. For a self-hosted broker, use the MQTT CLI tool that HiveMQ provides:

mqtt sub -h ${HIVEMQ_HOST} -p 8883 -s -u ${HIVEMQ_USERNAME} -pw ${HIVEMQ_PASSWORD} -t 'uns/#'

Replace ${HIVEMQ_HOST}, ${HIVEMQ_USERNAME}, and ${HIVEMQ_PASSWORD} with the hostname and the credentials of your broker. The -s flag enables TLS.

1. Publish a test message to enterprise/hamburg/assembly/line-1/press-01/telemetry, for example with an MQTT client or the Admin UI. The message appears in the Web Client or the MQTT CLI subscription on uns/hamburg/assembly/line-1/press-01/telemetry.

2. For the opposite direction, publish a test message to cmd/shopfloor/commands, either in the Send Message area of the Web Client or with the MQTT CLI:

mqtt pub -h ${HIVEMQ_HOST} -p 8883 -s -u ${HIVEMQ_USERNAME} -pw ${HIVEMQ_PASSWORD} -t cmd/shopfloor/commands -m '{"command": "stop"}'

1. Use the Data Explorer to check that the message arrives on enterprise/backend/hivemq/commands.

Service Commissioning File Example

hivemq-example.yml

3KB

Open

hivemq-example.yml

---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------
# HiveMQ Integration (Example)
# ----------------------------------------------------------------------------

description: >
  Service commissioning file for the bidirectional integration between
  Connectware and a HiveMQ broker (Example)

metadata:
  name: HiveMQ Integration
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  hivemqHost:
    description: Hostname of the HiveMQ broker or HiveMQ Cloud cluster URL
    type: string
    default: a1b2c3d4e5f6.s1.eu.hivemq.cloud

  hivemqUsername:
    description: Username of the MQTT credential created for Connectware
    type: string
    default: connectware

  hivemqPassword:
    description: Password of the MQTT credential
    type: string

  clientId:
    description: MQTT client ID, must be unique on the broker
    type: string
    default: connectware-shopfloor

  topicRoot:
    description: Root of the MQTT topic hierarchy on the Connectware side
    type: string
    default: enterprise

resources:
  # TLS connection to the HiveMQ broker. For a self-hosted broker without a
  # TLS listener, set scheme to mqtt and port to 1883 (not recommended for
  # production).
  hivemqConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref hivemqHost
        port: 8883
        scheme: mqtts
        username: !ref hivemqUsername
        password: !ref hivemqPassword
        clientId: !ref clientId
        keepalive: 60

  # Bridges shop floor telemetry from the ISA-95 topic hierarchy to the
  # uns/ prefix on the HiveMQ broker
  telemetryMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            topic: !sub '${topicRoot}/+site/+area/+line/+cell/telemetry'
            qos: 1
          publish:
            connection: !ref hivemqConnection
            topic: uns/$site/$area/$line/$cell/telemetry
            qos: 1

  # Receives commands that enterprise applications publish to the HiveMQ
  # broker on the cmd/shopfloor/commands topic
  commandEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref hivemqConnection
      subscribe:
        topic: cmd/shopfloor/commands
        qos: 1

  commandMapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref commandEndpoint
          publish:
            topic: !sub '${topicRoot}/backend/hivemq/commands'