> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/system-connectivity/messaging-event-streaming/hivemq-integration.md).

# HiveMQ Integration

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](https://www.hivemq.com/products/mqtt-cloud-broker/) cluster, or a self-hosted [HiveMQ Platform](https://docs.hivemq.com/hivemq/latest/user-guide/) installation with administrative access to its configuration.
* Access to the [Admin UI](/2-4-2/access/admin-ui.md) with sufficient [user permissions](/2-4-2/access/user-management.md).
* Basic knowledge of MQTT and the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md), and [mappings](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md)).

## 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](/2-4-2/connectors/enterprise-connectors/mqtt.md), 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](/2-4-2/connectors/enterprise-connectors/mqtt/mqttconnection.md)).
* 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](https://console.hivemq.cloud) 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](https://docs.hivemq.com/hivemq-cloud/authn-authz.html).

### Preparing a Self-Hosted HiveMQ Platform

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

{% hint style="danger" %}
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](https://docs.hivemq.com/hivemq/latest/user-guide/security.html)).
{% endhint %}

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](https://docs.hivemq.com/hivemq/latest/user-guide/listeners.html)). 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`.

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}

### 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.

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}

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](/2-4-2/connectors/enterprise-connectors/mqtt/mqttconnection.md).

### 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.

{% code lineNumbers="true" %}

```yaml
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
```

{% endcode %}

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](/2-4-2/data-flows/rule-engine.md)).

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.

{% code lineNumbers="true" %}

```yaml
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'
```

{% endcode %}

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](https://hivemq.github.io/mqtt-cli/) tool that HiveMQ provides:

{% code lineNumbers="true" %}

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

{% endcode %}

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

4. 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`.
5. 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:

{% code lineNumbers="true" %}

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

{% endcode %}

6. Use the [Data Explorer](/2-4-2/monitoring/data-explorer.md) to check that the message arrives on `enterprise/backend/hivemq/commands`.

## Service Commissioning File Example

{% file src="/files/sf3RFUjXQGn8cppBF4ni" %}

{% code title="hivemq-example.yml" lineNumbers="true" expandable="true" %}

```yaml
---
# ----------------------------------------------------------------------------
# Service Commissioning File
# ----------------------------------------------------------------------------
# Copyright: Cybus GmbH
# Contact: support@cybus.io
# ----------------------------------------------------------------------------
# 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'
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-2/guides/system-connectivity/messaging-event-streaming/hivemq-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.