Book a consultation

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.

Vladimir Romanov


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.

DimensionEdge bridgeEnterprise Bridge Extension
Where it runsInside HiveMQ EdgeInside the HiveMQ broker
LicenceOpen source; offline buffering is commercialLicence file required; 5-hour trial licence without one
DirectionsForward and remote subscriptionPUB mode forwards; SUB mode needs MQTT 5 remote
Topic rewritedestination with level referencesdestination with level references and variables
Loop preventionOn by default, hop limit 1On by default, MQTT 5 only, hop limit 1
QoSmax-qos caps and downgradesQoS 2 downgraded to QoS 1
Remote unreachableRetry 1 s doubling to 128 s, with jitterRetry 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.

A bridge between a plant broker and a central broker with hop-count loop prevention A plant broker publishes a message on a topic. The bridge forwards it to the central broker and adds the user property hmq-bridge-hop-count with value 1. A second bridge direction would send the same message back to the plant broker, but the message has already crossed one bridge and the limit is 1, so it is discarded and the loop stops. A topic prefix is added on the way north. Plant broker line1/filler/speed hop count: none Central broker siteA/line1/filler/speed hop count: 1 1 forward, add prefix siteA/, hop count 1 2 return path: bridged back 3 already bridged once, limit 1: the message is dropped Default hop-count-limit is 1. Illustrative topics.
The hop count travels with the message. A message that has already used up its allowed hops is dropped, so a two-way bridge cannot circulate the same data.

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.

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.

Aerial view of a suspension bridge crossing a wide river between forested hills in autumn
A bridge carries traffic only while it stands: the buffer settings decide what waits on the bank when it does not.

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

  1. HiveMQ Edge MQTT bridges · HiveMQEvery Edge bridge setting quoted on this page.
  2. HiveMQ Enterprise Bridge Extension · HiveMQBroker-to-broker bridging, SUB mode, cluster rules and loop prevention.
  3. HiveMQ Edge configuration · HiveMQIn-memory against file-native persistence.
  4. HiveMQ Edge documentation · HiveMQ
  5. HiveMQ clustering documentation · HiveMQReplica counts and transport.
  6. HiveMQ, Architecture Hub · SiemensA reference pattern with a local HiveMQ per factory; a Siemens page, not a partnership statement.

← HiveMQ Edge

Have a project that needs technical ownership?

Send us the situation. If it is not something we should take on, we will say so.

The Plant-Side Brief

The weekly brief for the people who own a plant’s control systems.

One email every Wednesday for engineering and operations leaders responsible for controls, SCADA, MES and OT networks. Skim the top in two minutes; read the Deep Dive when you have fifteen.

  • One modernization problem, worked through to cost, risk and a schedule you can defend. The Deep Dive.
  • End-of-support dates before they reach your plant Windows, servers, controllers and HMI software. Lifecycle Watch.
  • A checklist your engineers can run that week not a framework to admire. Field Kit.
  • Every number sourced, no vendor agenda we are paid by plants, never by vendors.