Skip to main content

​
MQTT Bridge Overview

The MQTT_BRIDGE route connects your Coreflux broker to another MQTT broker and keeps selected topics in sync between them. Use it for edge-to-cloud synchronization, linking multiple sites, or mirroring data to a backup broker.
Like call forwarding for messages. You decide which topics get forwarded and in which direction, and the bridge relays every matching message between the two brokers automatically.

​
When to use it

  • Push local sensor data from an edge device up to a cloud broker.
  • Pull commands or configuration from a central broker down to remote sites.
  • Keep two brokers continuously in sync for redundancy.
Let’s look at how to define a bridge, starting with the most common scenarios.

​
Quick Start

Forward local sensor data up to a cloud broker over TLS:
DEFINE ROUTE EdgeToCloud WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloud-provider.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeDevice001"
        WITH USERNAME "edge_user"
        WITH PASSWORD "secure_password"
        WITH USE_TLS "true"
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH DESTINATION_TOPIC "edge-001/sensors/+/data"
        WITH DIRECTION "out"

​
Connection Configuration

A bridge has two endpoints: a SOURCE_CONFIG (usually your local broker) and a DESTINATION_CONFIG (the remote broker). Use WITH BROKER SELF for the local Coreflux broker, or provide explicit connection details for a remote one.
​
BROKER_ADDRESS
string
required
IP address or hostname of the broker. Use SELF for the local broker.
​
BROKER_PORT
integer
required
MQTT port (typically 1883 for unencrypted, 8883 for TLS).
​
CLIENT_ID
string
required
Unique client identifier for the bridge connection.
​
USERNAME
string
Authentication username.
​
PASSWORD
string
Authentication password.
​
USE_TLS
boolean
Enable TLS encryption. Default: false.
​
ALLOW_UNTRUSTED_CERTS
boolean
Allow untrusted certificates. Default: false.
​
SERVER_CA_CERT_PATH
string
Path to CA certificate file.
​
CLIENT_CERT_PATH
string
Path to client certificate for mTLS.
​
CLIENT_CERT_PASS
string
Client certificate password.
​
RECONNECTION_RETRIES
integer
Number of reconnection attempts. Default: 5.

​
Mapping Configuration

Each ADD MAPPING block defines which topics are bridged and in which direction.
​
SOURCE_TOPIC
string
required
Topic pattern to subscribe to on the source broker. Supports wildcards.
​
DESTINATION_TOPIC
string
required
Topic to publish to on the destination broker.
​
DIRECTION
string
required
Data flow direction: out (source→dest), in (dest→source), or both.

​
Secure mTLS Bridge

For production links between sites, encrypt both endpoints and authenticate with mutual TLS: 
DEFINE ROUTE SecureBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER_ADDRESS "192.168.1.10"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "SecureSource"
        WITH USE_TLS "true"
        WITH SERVER_CA_CERT_PATH "/certs/ca.pem"
        WITH CLIENT_CERT_PATH "/certs/client.pem"
        WITH CLIENT_CERT_PASS "cert_password"
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "secure.cloud.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "SecureDest"
        WITH USE_TLS "true"
        WITH ALLOW_UNTRUSTED_CERTS "false"
    ADD MAPPING secureMapping
        WITH SOURCE_TOPIC "secure/+/data"
        WITH DESTINATION_TOPIC "cloud/+/data"
        WITH DIRECTION "out"

​
Best Practices

Always enable TLS when connecting to external brokers:
WITH USE_TLS "true"
Each bridge connection needs a unique CLIENT_ID to avoid conflicts:
WITH CLIENT_ID "EdgeDevice001-SensorBridge"
Use WITH BROKER SELF during development:
ADD SOURCE_CONFIG
    WITH BROKER SELF
Store passwords securely and use app-specific passwords where available.
Configure appropriate retry settings:
WITH RECONNECTION_RETRIES '10'

​
Troubleshooting

  • Verify IP address and port are correct
  • Check firewall allows outbound connections on the configured port
  • Ensure remote broker is running and accessible
  • Try increasing RECONNECTION_RETRIES
  • Verify certificate paths are correct
  • Ensure certificates are valid and not expired
  • Check certificate chain is complete
  • For testing, use ALLOW_UNTRUSTED_CERTS "true" (not recommended for production)
  • Verify SOURCE_TOPIC and DESTINATION_TOPIC are correct
  • Check DIRECTION setting matches your expected data flow
  • Ensure CLIENT_ID is unique across all connections
  • Check broker logs for subscription errors

​
Next Steps

Email

Send alerts and notifications from MQTT messages.

Kafka

Stream data between MQTT and Apache Kafka.
Last modified on July 3, 2026