HiveMQ Edge: The Open-Source Gateway from PLC to MQTT
HiveMQ Bridge: Edge-to-Cloud Bridging, Topic Mapping and Loop Prevention
HiveMQ bridge explained: how Edge and the Enterprise Bridge Extension forward topics, map names, prevent loops, handle QoS and behave when the link drops.
A HiveMQ bridge is an MQTT client that connects one broker to another and moves selected messages between them. It is how a plant broker or an Edge gateway sends data to a site or enterprise broker without clustering across the network between them. This page covers the mechanics as HiveMQ documents them for Edge and for the Enterprise Bridge Extension: what you configure, how topic names are mapped, how loops are prevented, what happens to QoS, and what happens when the link drops. It is a child of HiveMQ Edge and part of the HiveMQ hub. Settings are as read from HiveMQ’s documentation on 20 November 2026.
The short answer: a bridge forwards topics you list, can rewrite them with a destination pattern, counts hops in an MQTT 5 user property so messages do not loop, caps QoS where you tell it to, and buffers during an outage only with a commercial feature on Edge.
How a HiveMQ bridge works
Two directions, set separately. On Edge, forwarded-topics send local messages to the remote broker, and remote-subscriptions pull remote messages into the local broker. A bridge with neither section starts but processes nothing, and Edge logs a warning. Each bridge has a unique id, a remote-broker host and port (default 1883), optional username and password, and optional TLS and WebSocket settings. TLS is off by default; mutual TLS turns on when a keystore is set. We would never leave a bridge that crosses a firewall without TLS.
Edge and the broker use different tools. Edge’s bridge is open source and bidirectional. The HiveMQ broker’s Enterprise Bridge Extension is a separate extension that runs under a licence file; HiveMQ’s documentation says that without one it uses a free trial licence valid for 5 hours, and does not state the price or tier. It forwards PUBLISH messages to an MQTT 3.1.1 or MQTT 5 remote broker in its default PUB mode, and its SUB mode receives from a remote broker and publishes locally, which needs an MQTT 5 remote because it uses shared subscriptions. In a cluster, HiveMQ says to install identically configured extensions on every node. For the cluster itself, see HiveMQ clustering and high availability.
| Dimension | Edge bridge | Enterprise Bridge Extension |
|---|---|---|
| Where it runs | Inside HiveMQ Edge | Inside the HiveMQ broker |
| Licence | Open source; offline buffering is commercial | Licence file required; 5-hour trial licence without one |
| Directions | Forward and remote subscription | PUB mode forwards; SUB mode needs MQTT 5 remote |
| Topic rewrite | destination with level references | destination with level references and variables |
| Loop prevention | On by default, hop limit 1 | On by default, MQTT 5 only, hop limit 1 |
| QoS | max-qos caps and downgrades | QoS 2 downgraded to QoS 1 |
| Remote unreachable | Retry 1 s doubling to 128 s, with jitter | Retry indefinitely, 1 s doubling to 2 min |
HiveMQ bridge topic mapping and prefixes
Filters pick the messages; destination renames them. Each forwarded topic has a filter using normal MQTT wildcards and an optional excludes list. The destination pattern rewrites the topic before it is published, using level references such as {#}, {2} or {1-3}, static text, prefixes and postfixes. HiveMQ’s example turns a/b/c/d into prefix/b/c/data with prefix/{2-3}/data. Its Cloud example forwards everything (#) with the destination hivemq-edge/{#}, which adds a hivemq-edge/ prefix.
Why the prefix matters. If each plant forwards line1/filler/speed unchanged, two plants collide on one central topic. A prefix with a site name, or a full enterprise and site path, keeps them apart. This is where a Unified Namespace is made or broken, and it deserves a written topic standard before any bridge is configured. See the Unified Namespace guide and HiveMQ and the Unified Namespace. Edge also has ISA-95 topic prefixing as an open-source feature.
Retained messages need a decision. preserve-retain defaults to false on Edge, and preserve-retained defaults to false on the Enterprise extension. HiveMQ’s pages we read give no more detail, so test what a late-joining subscriber sees at the central broker.
HiveMQ bridge loop prevention
The problem. A bridge that forwards # in one direction and subscribes to # in the other will send each message back and forth for ever. Two-way bridges are normal in a plant when commands flow down and data flows up, so loops are a real risk, not a theory.
The mechanism. Loop prevention is enabled by default. The bridge adds an MQTT 5 user property named hmq-bridge-hop-count and discards a message whose count exceeds hop-count-limit. The default limit is 1. HiveMQ’s Edge documentation says that with the default limit of 1 no duplicate messages are possible, and that a higher limit allows a fixed number of duplicates but never an endless loop. The Enterprise extension discards over-limit messages and logs a loop-prevention dropped-publish metric for them. On the Enterprise extension the feature is MQTT 5 only.
Topic design is the second guard. HiveMQ’s Edge page notes that a correct topic structure can prevent duplicates. In our view, the best loop prevention is never to subscribe in one direction to a topic tree that the other direction forwards. Keep data going up and commands going down in separate trees.
QoS and the HiveMQ bridge
QoS is capped, not promised. The Edge max-qos setting caps a forwarded topic or remote subscription and downgrades anything higher; HiveMQ recommends setting it explicitly for each one. The Enterprise extension downgrades all QoS 2 messages to QoS 1 to support shared subscriptions. Each hop is its own MQTT session, so the guarantee applies hop by hop, not from PLC to cloud. In our view, design for at-least-once delivery and make consumers tolerate duplicates, and keep that principle in mind with MQTT in manufacturing.
When the link drops
Edge: buffering is commercial. HiveMQ’s documentation states offline buffering is a commercial Edge feature. With it, QoS 1 and QoS 2 messages queue per topic filter up to queue-limit, which defaults to the global maximum queue size. QoS 0 messages queue in memory and do not count against that limit. When a queue is full, new messages are discarded by default, and the discard-oldest strategy drops the oldest instead. persist defaults to true so queued messages keep their QoS; set to false, they are downgraded to QoS 0 and Edge logs it. Queued messages survive a restart only with file-native persistence, and stopping a bridge from the REST API or UI discards its queue. Reconnection starts at 1 second and doubles up to 128 seconds with up to 25 percent random jitter.
Session settings change what resumes. clean-start defaults to false in the config file, but bridges created from the UI or REST API default to true, which starts a fresh session each time. session-expiry defaults to 3600 seconds and applies only to MQTT 5 remotes. Check which one your bridge actually has.
Enterprise extension. It retries indefinitely, with the delay doubling from 1 second to 2 minutes, and records failures in logs and metrics. Its clean-start default of false is recommended to avoid loss while the remote broker is unavailable.

A reference pattern: local broker per factory
The Siemens Architecture Hub has a page titled HiveMQ, labelled a partner solution. It describes Siemens Industrial Edge devices connecting PLCs and sensors, a HiveMQ instance in each factory enforcing topic structure and access control, and local brokers bridging or tunnelling selected topics to a central HiveMQ cluster for ERP, MES and analytics. The page says local brokers keep running during outages. That is a design statement on a marketing page, not a measured result, and it contains no partnership agreement text. HiveMQ’s own documented multi-site tool is the bridge, and we found no HiveMQ source on clusters stretched over a plant WAN. See HiveMQ multi-site architecture for the design view.
Where it gets hard
- Buffer sizing. HiveMQ gives the setting names but no guidance on sizing against a link outage. Work it out from message rate, size and the longest outage you must ride through, then test it.
- Retained messages across the bridge are lightly documented; test late-joiner behaviour.
- Credentials and TLS. Username and password are both required in the config file, and credentials are sent only when both are set. Plan rotation.
- Version differences. Loop prevention and SUB mode need MQTT 5 on the Enterprise extension. An MQTT 3.1.1 remote limits you.
- Silent loss. Full queues discard new messages by default. Alert on bridge queue depth, not only on connection state.
For the data policies that can validate payloads before they cross, see HiveMQ Data Hub. Up one level: HiveMQ Edge. Across to a sibling: HiveMQ Edge protocol adapters. The hub is HiveMQ technologies.
Frequently asked questions
What is a HiveMQ bridge?
A HiveMQ bridge is an MQTT client connection that forwards messages between two brokers. HiveMQ Edge includes open-source bidirectional bridging. Its broker has a separate HiveMQ Enterprise Bridge Extension that runs under a licence file. Each bridge forwards selected topics to a remote broker, subscribes to topics on it, or does both, and can rewrite topic names on the way.
How does a HiveMQ bridge prevent message loops?
Loop prevention is on by default. The bridge counts hops in an MQTT 5 user property named hmq-bridge-hop-count and discards messages above the hop-count-limit, which defaults to 1. HiveMQ's documentation says that with the default limit duplicates are not possible. Raising the limit allows a fixed number of duplicates but still no loops.
What happens to data when the bridge link goes down?
On Edge, offline buffering is a commercial feature. HiveMQ's documentation says QoS 1 and QoS 2 messages queue per topic filter up to a queue limit, new messages are discarded when the queue is full unless discard-oldest is chosen, and queued messages survive a restart only with file-native persistence. QoS 0 messages queue in memory only.
Does QoS survive a HiveMQ bridge?
Only up to the limits you set. The bridge's max-qos setting caps the QoS and downgrades higher levels, and HiveMQ's Enterprise Bridge Extension downgrades all QoS 2 messages to QoS 1. Each hop is its own MQTT session, so a guarantee applies per hop. Design for at-least-once delivery and make consumers tolerate duplicates.
Should I cluster across plants or bridge them?
HiveMQ's documented multi-site tool is bridging: regional or plant brokers bridge to a central cluster. We found no HiveMQ statement that clusters must not span a WAN, and no statement that a stretched cluster over a plant WAN is supported. In our view, bridging is the safer default for plant-to-enterprise links.
References and further reading
- HiveMQ Edge MQTT bridges · HiveMQEvery Edge bridge setting quoted on this page.
- HiveMQ Enterprise Bridge Extension · HiveMQBroker-to-broker bridging, SUB mode, cluster rules and loop prevention.
- HiveMQ Edge configuration · HiveMQIn-memory against file-native persistence.
- HiveMQ Edge documentation · HiveMQ
- HiveMQ clustering documentation · HiveMQReplica counts and transport.
- HiveMQ, Architecture Hub · SiemensA reference pattern with a local HiveMQ per factory; a Siemens page, not a partnership statement.