A Step-by-Step Guide to Connecting HiveMQ Edge with HiveMQ Cloud

HiveMQ Edge is an MQTT gateway that enables interoperability between OT devices and IT systems. It translates diverse protocols into MQTT for streamlined communication and helps organize data into a unified namespace, making managing and streaming data across your infrastructure easier. It can send messages to the HiveMQ Platform (self-managed and fully-managed). 

HiveMQ Edge supports MQTT, MQTT-SN, and Protocol Converters for various industrial and automation protocols, including Modbus, OPC UA, Siemens S7, Allen-Bradley, and more.

With the 2024.3 release, HiveMQ Edge has added new commercial features: 

1. HiveMQ Data Hub is an integrated policy engine that validates, enforces, and manipulates data in motion to ensure data integrity and quality across your MQTT deployment from edge to cloud. It ensures that data is evaluated early in the supply chain, preventing subscribing clients from performing resource-consuming validation. 

2. Offline Buffering allows HiveMQ Edge to queue messages on a local disk in case of an MQTT bridge connection failure and publish them once the connection is restored, eliminating data loss.

3. Enterprise Support: HiveMQ's in-house team also provides enterprise support for this latest release of HiveMQ Edge.

The fastest way to get started with HiveMQ Edge is to connect it to HiveMQ Cloud. This step-wise guide will take you through all the necessary steps — let’s get started!

Deploying HiveMQ Edge

HiveMQ Edge is designed to work on constrained devices and in containers. In this guide, we’re going to take you through the steps to deploy Edge on a Unix-based machine.

HiveMQ Edge can also be deployed using Docker with the following command:

Step 1: Deployment of HiveMQ Edge

To deploy HiveMQ Edge on a local machine or device, navigate to our Git Repository and download and unzip the binary package. Using a Unix/Linux CLI or terminal, navigate to the package location and run HiveMQ Edge using the following commands:

Step 2: Accessing the HiveMQ Edge Interface

With HiveMQ Edge up and running, navigate to the Edge web app, which is hosted locally and accessible via a web browser, by navigating to http://localhost:8080.

The default access credentials are username: admin password: hivemq. If needed, these credentials can be modified in the configuration file.

Once logged in to HiveMQ Edge Console, you can access links to HiveMQ Edge documentation and learn more about HiveMQ Edge there.

HiveMQ Edge is now up and running, and you’ve now accessed the web app. It’s time to turn our attention to HiveMQ Cloud, where you will be bridging HiveMQ Edge to later.

Creating HiveMQ Edge Access Credentials in HiveMQ Cloud

Step 3: Logging into HiveMQ Cloud

If you don’t already use HiveMQ Cloud, you can sign up for a free account on HiveMQ Cloud Serverless or use the ‘Connect to HiveMQ Cloud’ link in the Edge web app, and it’ll open a new tab and take you to our sign-up page.

If you’re already a HiveMQ Cloud user, log into your HiveMQ Cloud account as usual.

Once you’re logged into HiveMQ Cloud, you may already have a cluster running; if that’s the case, please move to the next step. If you don’t yet have a cluster running, then select ‘Create new cluster’ and choose one of our Cloud Plans, then follow the instructions in the prompt.

Step 4: Creating Credentials for HiveMQ Edge

Now that you have logged in and have a running cluster, you must create credentials for your HiveMQ Edge deployment to bridge it to your HiveMQ Cloud cluster. To do this, navigate to your cluster via the ‘Clusters’ menu in the sidebar, then select ‘Manage Cluster’, then (on the top bar), click on ‘Access Management.’

Next, create your specific credentials under ‘Access Credentials.’ Here, we’re using the username ‘hivemq-edge’ to make it easy to know what these credentials are for and we’re selecting the ‘Publish and Subscribe’ role to ensure messages can be published back to HiveMQ Edge. When you’re happy with your credentials, click ‘Create Credentials’.

After you have created your credentials, they will appear in the ‘Access Credentials’ list, as pictured above. Before you move to the next step, we recommend copying your cluster URL to the clipboard. You can find the cluster URL on the main ‘Clusters’ view selectable on the left-hand menu bar.

Creating an MQTT Bridge from HiveMQ Edge to HiveMQ Cloud

Step 5: Setting up a bridge

Navigate to the Edge web app and select ‘MQTT Bridges’ from the sidebar menu.

Select ‘Add Bridge Connection’ from the top right corner. A new menu will appear from the right to configure the new bridge connection.

Enter the details of your HiveMQ Cloud host. The URL should still be copied to your clipboard. The required port is 8883. 

Populate those details and your recently created credentials in the configuration form. Make sure you give your connection a name, too. We are using ‘hivemq-cloud’ in this example.

We need to set up a local subscription to ensure messages from the edge make it to the cloud. Click on the ‘+’ icon to do this. To make things simple, you can subscribe to all topics using the # wildcard and also send them to the all topics wildcard.

Once you’re happy with the bridge configuration and subscription, click on the ‘Security’ tab.

Ensure you enable TLS using the toggle switch provided in the ‘Security’, then click the yellow ‘Create the bridge’ button in the bottom right of the menu panel.

The screen will return to the MQTT Bridges view, and your bridge will show ‘Disconnected’ for a little while as the connection is established. When connected, the status will turn green and state ‘Connected.’ If the bridge continues to show ‘Disconnected,’ please click on the edit connection icon next to the bridge name and review your configuration.

Step 6: Creating an Edge Protocol Adapter Connection

With the bridge in place and successfully connected, it’s time to connect HiveMQ Edge to an external device, and start sending messages to HiveMQ Cloud.

Click on ‘Protocol Adapters’ in the side menu to create your first connection.

In the ‘Protocol Adapters Catalog’ view, you will see a list of available adapters that can be used to create a connection. We are going to use OPC UA for this example.

If you have external MQTT client devices already publishing via MQTT or MQTT-SN, then you can simply connect these devices to your HiveMQ Edge instance on port 1883 and the traffic will be routed over your newly established bridge into the cloud. Alternatively, if you wish to connect PLCs, you can click ‘Create new connection’ in the adapter pane to get started. If you have no PLCs or external devices to use at this stage, then you can create a simulated connection using the ‘Simulated Edge Device’ adapter.

Selecting ‘Create new connection’ for an adapter in the catalog will bring up a connection configuration menu from the right-hand side of the view, similar to when you created a bridge connection. Create a unique identifier (name) for each connection before setting your configuration parameters.

In our example, we’re using an OPC UA temperature sensor and have set the subscription to convert the local OPC UA temperature values into ‘topic/plc/temperature.’

Each protocol adapter will have different configuration fields applicable to the data type and schema. For more details on each protocol adapter type and the configuration options, check out our documentation on GitHub.

You can add multiple subscriptions for each connection using the ‘+ Add Item’ button. Once the configuration is complete, click the yellow ‘Create’ button in the bottom right of the view.

Step 7: Monitoring Connection Status

Once the connection is established, the HiveMQ Edge web app will take you to the ‘Active Adapters’ view, and you should see the new connection change its state from ‘Disconnected’ to ‘Connected’. If the connection doesn’t connect, please review your connection configuration. This can be done by selecting the down arrow button and selecting ‘Edit’.

The connection you just created is always highlighted. Now, find the ‘Workspace’ button under actions, or click on the nucleus ‘Workspace’ icon to see your new connection in the Workspace view.

Workspace is our observability tool, which is an interactive canvas displaying all connected elements at the edge to help you identify what connections you have active at the edge and where messages are being sent. In the image above, you can see our OPC UA connection is connected and successfully sending data to HiveMQ Edge. We now have an active subscription via an MQTT Bridge to HiveMQ Cloud.

Step 8: Monitoring Edge Data Coming Through to HiveMQ Cloud

Navigate back to your HiveMQ Cloud ‘Manage Cluster’ menu and navigate to ‘Web Client’ via the top menu.

For our example, we’re using ‘Connect with generated client credentials.’ If you’d prefer to use existing client credentials, type them in and click the yellow ‘Connect Client’ button. Then ensure you’re either subscribed to all topics using the shortcuts provided once the client is connected or the destination topic you configured your connection to publish to.

Under the ‘Publish Message’ function in the ‘Web Client’ you should see your messages coming through from your edge client In our example above you can see the temperature messages coming through to HiveMQ Cloud from our OPC UA temperature sensor. 

Hopefully following these steps, you have successfully deployed HiveMQ Edge, bridged to HiveMQ Cloud, created an edge client connection, and sent messages from the device to HiveMQ Cloud via HiveMQ Edge.

HiveMQ Edge Workspace does much more than we’ve demonstrated in this blog. You can view status information and metrics that are updated in real-time. Custom metrics of each protocol adapter can be visualized at hand.

Keep an eye out for HiveMQ Edge release blogs — we have exciting enhancements planned for future releases.