Configure Advanced Features of MQTT Bridges

This guide introduces advanced feature configurations available for the MQTT over TCP Bridge in EMQX Edge. These features provide fine-grained control over how data is bridged between edge and cloud, helping optimize performance, routing, and reliability in real-world deployments.

If you’re new to bridges, see the Quick Start Guide before continuing.

For a complete list of configuration options, refer to the Data Bridge Configuration.

Topic Mapping and Remapping

EMQX Edge supports dynamic topic transformation between local and remote brokers. This includes:

• Stripping or modifying topic prefixes
• Replacing parts of the topic hierarchy
• Preserving or reshaping specific segments of a topic

This is especially useful in bridged deployments where local and remote brokers use different topic structures. It helps maintain a consistent routing logic without manual reconfiguration and supports the creation of a Unified Namespace (UNS).

Wildcard-Based Topic Transformation

EMQX Edge uses MQTT wildcards as patterns for topic remapping:

• +: Matches exactly one level in the topic hierarchy (e.g., a single segment).
• #: Matches zero or more levels and must appear at the end of the topic pattern.

These wildcards act as placeholders for dynamic segments and allow EMQX Edge to manipulate incoming or outgoing topics based on matches.

You can use these wildcards in remote_topic and local_topic fields, and optionally apply a prefix and suffix to modify the resulting topic after matching.

Example: Subscribing with Topic Remapping

Consider a subscription where you want to remove the prefix system/nano, and add a custom prefix (cmd/) and suffix (/remote).

If a message arrives from the remote broker on the topic:

system/nano/start

With the following configuration:

bridges.mqtt.mybridge {
  ...
  subscription = [
    {
      remote_topic = "+/nano/#"   # Matches topics like system/nano/start
      local_topic  = "#"          # Preserves only the matched suffix (start)
      prefix       = "cmd"
      suffix       = "remote"
    }
  ]
}

The resulting local topic becomes:

cmd/start/remote

The prefix and suffix are applied after wildcard filtering.

This pattern can also be used for forwarding rules, enabling consistent topic transformations in both directions.

Transparent Bridging

Transparent bridging forwards is a mode that automatically forwards all subscribe and unsubscribe requests from local clients to a remote broker. This mode requires no predefined topic configurations and is ideal when you want the remote broker to mirror all local client subscriptions.

To enable transparent bridging, set the transparent field to true in the configuration:

bridges.mqtt.mybridge {
  transparent = true
}

Once enabled, EMQX Edge will dynamically relay all subscription activity from local clients to the remote bridge target.

Hybrid Bridging

Hybrid bridging allows you to define multiple target servers for a single bridge. If one server becomes unavailable, EMQX Edge will automatically attempt to connect to the next in the list.

This approach provides connection resilience and makes it possible to fall back from modern protocols like QUIC to traditional ones like TCP/TLS.

Configuration Example

bridges.mqtt.mybridge {
  hybrid_bridging = true
  hybrid_servers = [
    "mqtt-quic://127.0.0.1:14567",
    "mqtt-tcp://127.0.0.1:1883",
    "tls+mqtt-tcp://127.0.0.1:8883",
    "mqtt-tcp://127.0.0.1:1884"
  ]
}

EMQX Edge will try each URL in sequence on reconnect attempts until a successful connection is established.

Interface Binding

In production environments with multiple network interfaces, it is often necessary to bind MQTT bridge traffic to a specific interface for performance, security, or routing reasons.

You can use the bind_interface setting under the tcp section to control which interface is used.

Configuration Example

bridges.mqtt.mybridge {
  tcp {
    bind_interface = wlan0
    nodelay = false
  }
}

• bind_interface: Specifies the name of the network interface to which bridge traffic should be bound (e.g., wlan0). This ensures that packets are sent through a specific interface.
• nodelay:
  • When set to true, EMQX Edge will keep retrying the interface binding if it initially fails. This is useful in strict networking scenarios where fallback to the system default route is not acceptable.
  • When set to false, binding failure is ignored and the bridge skips the connection attempt for that cycle.

Set nodelay = true when interface binding is mandatory and fallback behavior must be prevented.

Message Caching and Retry

In real-world deployments, especially at the edge, unstable or slow network conditions can lead to message retransmission, congestion, and eventual data loss. EMQX Edge provides configurable caching and retry mechanisms to improve message delivery reliability in such environments.

These settings allow fine-grained control over how the bridge handles in-flight messages, retry timing, and cancellation policies.

Configuration Example

bridges.mqtt.emqx1 {
  keepalive            = 30s
  max_send_queue_len   = 512
  resend_interval      = 5000
  resend_wait          = 3000
  cancel_timeout       = 10000
}

• keepalive: Heartbeat interval for the bridge connection. Used as a timing reference for retry logic.
• max_send_queue_len: Maximum number of messages that can be buffered (queued) for retransmission. Acts as the in-flight window for QoS messages.
• resend_interval (ms): Time between retry attempts for QoS messages. Typically set to 1/2 or 1/4 of the keepalive value for optimal performance.
• resend_wait (ms): Initial wait time before retrying a failed message. Set this longer than keepalive if you want to avoid duplicate QoS messages.
• cancel_timeout (ms): Maximum duration to wait before dropping a message if no acknowledgment is received. Defines the total retry window for each message.

Tip: To ensure that a message is retried at least once, use this formula:

(cancel_timeout - resend_wait) / resend_wait > 1

Proper tuning of these values is essential for ensuring reliable message delivery in poor network conditions, while preventing excessive retry loops or buffer overflows.

For more configuration options, refer to the Data Bridge Configuration.