HiveMQ Logo
Connecting Legacy to AI: A Tutorial on HiveMQ Edge Brokers

Connecting Legacy to AI: A Tutorial on HiveMQ Edge Brokers

author Kamiel Straatman

Written by Kamiel Straatman

Category: HiveMQ Edge

Published: August 29, 2023

HiveMQ recently released HiveMQ Edge — an open-source software gateway with an edge-optimized MQTT broker. HiveMQ Edge was developed to help manufacturing organizations simplify and modernize their industrial IoT infrastructure by converting legacy industrial network protocols like Modbus, S7, and OPC-UA into the MQTT format at the edge for upstream integration with enterprise and cloud systems. HiveMQ Edge is an MQTT v3.x and v5 broker, MQTT bridge, MQTT-SN gateway and modular protocol-conversion runtime all-in-one optimized for Edge compute. So it runs on lightweight x86 and ARM-based (industrial) hardware.

HiveMQ Edge implements the MQTT and MQTT-SN protocols (the de-facto M2M messaging standards). And through its 100% compliance with the MQTT specification, it is leading when it comes to professional adoption of all possibilities of the Internet of Things for companies. Along with included Modbus and OPC-UA adapters and an MQTT bridge, HiveMQ offers a complete all-in-one edge solution, with more adapters to come.

As members of the OASIS committee, the HiveMQ team was directly involved in the creation and release of MQTT 5.0, the newest version of the lightweight protocol, and is leading the development of the MQTT-SN 2.0 standard.

The Setup

To test drive this unique solution, this article will help you set up the edge broker, acquire data from OPC-UA and Modbus-TCP sources, and connect it to an upstream cloud broker.

The setup will be as indicated below with focus on the blue encircled items:

The HiveMQ Edge Broker Set-up
The HiveMQ Edge Broker Set-up

Step 1 – Installing and Managing the Edge Broker

Downloading and installing the Edge broker:

  • Download the latest version of the broker here: HiveMQ Edge binary package
  • Install a Java Runtime minimum version 11, please see:
  • Unzip the downloaded software and start by running ./<HiveMQ-dir>/bin/ (or run.bat)
  • When the log indicates "Started HiveMQ Edge in", then Open a local browser and connect to
  • Login with admin/hivemq:
The HiveMQ Edge Gateway

Note: The Edge broker will not retain any setup information you enter through the GUI by default. The rationale behind this is that edge brokers usually are configured on runtime or with API’s. If you want to retain setup information, as entered in the upcoming sections, please alter the ./<HiveMQ-dir>/conf/config.xml file as below:



Step 2 – Connecting an MQTT Client

To monitor what data is flowing through the broker, a subscription to all topics — indicated by ‘#’ wildcard — is very useful. We use the HiveMQ CLI client in this example but basically any MQTT compliant (GUI) client will do. The HiveMQ client along with installation guidelines can be found here:

In a separate command line window, connect to the local broker with: mqtt sub -h -t "#". The system will basically do nothing besides waiting for incoming MQTT messages. And since we do not generate data at this moment all is silent for now, but not for long.

Step 3 – Publish a Test Message with MQTT

In a separate command line window publish a message to the local broker with: mqtt pub -h -t "testtopic/subtopic" -m "Hello world". Now watch what happened in the windows where the subscribe is active. It will show the payload of the message we’ve just sent. You’ve just got yourself a decent MQTT broker!

Step 4 – Set Up the Simulator

To test the edge broker, a simulation module is supplied. This module will generate fictional information at a rate and in a topic of your choice.

To set this up, open the web management page of the edge broker ( and select from the left menu Protocol Adapters. Then select the Create new adapter button on the Simulated Edge Device tile:

The HiveMQ Edge Protocol Adapters Set-up
The HiveMQ Edge Protocol Adapters Set-up

In the Settings tab, fill in a descriptive identifier of your choice and under the Subscription tab click Add Item. Then configure the MQTT destination topic of the simulated data.

Create a New Adapter
Create a New Adapter

When all data is entered select the Create button. Now watch the subscribe window. A message like below will be shown as it is generated by the simulator every 10 seconds by default.

# mqtt sub -h -t "#" {"value":0.55204256354421,"timestamp":1692898007302}

Step 5 – Setting Up an OPC-UA Adapter and Simulator

Since we don’t have an OPC-UA PLC at hand, we will use the Prosys OPC-UA simulator/free edition. It can be downloaded here:

Now we add the OPC-UA adapter to the broker. This is done as described in Step 4: in the Installed Protocol Adapters tab we select the Create new adapter button of the OPC-UA to MQTT Protocol Adapter tile.

Under the Settings tab we need to set the OPC-UA Server URI. This can be found on the Status tab of the OPC-UA simulator. Simply copy this URI into the adapter settings as shown below:

OPCUA Simulator Server
OPCUA Simulator Server

To select the right information, we want to read from the OPC-UA device and define its destination topic. We need to fill in the Subscription tab for the OPC-UA adapter. This data can also be copied from the simulator as shown below. Also define a descriptive MQTT destination topic, as shown.

HiveMQ Edge Set-up

Hit Create when done and watch the subscribe monitoring windows.

Now watch the subscribe window. A message like below will be shown as it is published by the OPC-UA adapter reading real-time values from the OPC-UA simulator.

# mqtt sub -h -t "#" {"value":1.902113}

Step 6 – Setting up the Modbus-TCP Adapter

To add the Modbus adapter the method is identical as the ones above. Select under Installed protocol adapters tab the Create new adapter button of the ModBus to MQTT Protocol Adapter tile and configure.

For the Modbus simulator we use Modbus Server Pro. It must be defined in Settings as shown below:

Setting up the Modbus-TCP Adapter
Setting up the Modbus-TCP Adapter

The Settings tab defines, besides the publishing topic, the Modbus holding-register that needs to be read. In this example a total of 4 (0-3) are shown:

The HiveMQ Edge Setup

After you hit the Create button, start watching the subscribe monitoring windows. A message like below will be shown as it is published by the Modbus adapter reading real-time holding-registers from the mod simulator. Notice the 4 indexes referring to the holding-registers.


By default, only changed register values are published on MQTT here, but that behavior can be altered in the Publishing tab.

Step 7A – Bridging to Cloud Broker

An edge-broker is usually deployed as a single device on shop floors and industrial edges. But the local data harvested is usually needed on a higher, data-centric level. Therefore, the HiveMQ edge broker comes standard with a bridge built right in. This bridge makes propagating to a central cloud broker simple and so can facilitate having multiple (as in thousands) edge brokers all consolidating into one large (cloud) broker as shown in the setup picture above.

So, in this section we set up a cloud broker and connect our local bridge to it. The first step is to get you a cloud broker. For this we will set up a central HiveMQ Cloud broker with a Serverless (as in free, no credit card needed) subscription plan: so, please follow instructions on When done, you will be shown the screen as below:

HiveMQ Cloud Serverless Set-up
HiveMQ Cloud Serverless Set-up

Please set up a user under the Access Management in the cloud broker, give the user publish and subscribe permissions and note down the username and password you decided on, because we’ll need them later:

HiveMQ Cloud Serverless Set-up
HiveMQ Cloud Serverless Set-up

Now we configure the MQTT on our local broker so data is sent upstream toward the cloud broker. To configure the broker, select in the local edge broker menu on the left the MQTT bridges option and hit Add bridge connection in the upper right. Configure the (remote) bridge according to the information from the HiveMQ cloud instance:

Bridge configuration
Bridge configuration

As HiveMQ cloud only accepts encrypted connections, we need to enable TLS in the Security tab.

Lastly we need to define what local information will be sent upstream. This is done by selecting the + button and defining a filter. By basically not filtering and selecting the MQTT wildcard #, all data is sent upstream.

Step 7B - Test the Remote broker setup

To ensure data is ‘upstreamed’ correctly we can just watch the data flowing through the upstream cloud broker. To do so we can, in a separate command line window, connect to the remote broker with (as an example, use your own credentials/hostnames):

mqtt sub -h <<cluster-url-to-your-cloud-server>> -p 8883 -s -u <<your-created-user>> -pw <<your-created-password>> -t "#"

All data published to the local broker (check your window where you subscribed to the local broker) will also be pushed to the remote (cloud) broker, ready for upstream consumption. Check in window where you subscribed to your cloud!

Final Step

We hope you found this setup session useful. As you can see, setting up HiveMQ Edge to collect data and then bridge that data to a broker in the cloud is fairly straightforward. Feel free to reach me or dive deeper and try HiveMQ Edge on GitHub.

author Kamiel Straatman

About Kamiel Straatman

Kamiel is part of Solutions Engineering team at HiveMQ. Based out of the Netherlands, Kamiel is an IoT enthusiast with many years of experience working in the data center domain and Azure & AWS cloud architectures.

mail icon Contact Kamiel
newer posts Enabling Predictive Maintenance in Industry 4.0 with MQTT and Edge Computing
Ten Key Considerations for Selecting an MQTT Broker for UNS older posts