> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MQTT Bridge Route

> Connect two MQTT brokers for edge-to-cloud synchronization, multi-site connectivity, and backup systems

## 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.

> [!TIP]
>
> **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

**Edge to cloud (out)**

Forward local sensor data up to a cloud broker over TLS:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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"
```

**Cloud to edge (in)**

Pull commands from a cloud broker down to the local broker:

```lot wrap  theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE CloudCommands 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-Commands"
        WITH USE_TLS "true"
    ADD MAPPING commands
        WITH SOURCE_TOPIC "local/commands/#"
        WITH DESTINATION_TOPIC "edge-001/commands/#"
        WITH DIRECTION "in"
```

**Bidirectional (both)**

Keep two brokers fully in sync in both directions:

```lot wrap  theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE FullSync WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "partner-broker.example.com"
        WITH BROKER_PORT '1883'
        WITH CLIENT_ID "SyncClient"
    ADD MAPPING bidirectionalSync
        WITH SOURCE_TOPIC "shared/data/#"
        WITH DESTINATION_TOPIC "partner/data/#"
        WITH DIRECTION "both"
```

***

## 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 Settings**
>
> **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.

> **Authentication**
>
> **USERNAME** `string`
>
> Authentication username.
>
> **PASSWORD** `string`
>
> Authentication password.

> **TLS/Security**
>
> **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.

> **Connection Handling**
>
> **RECONNECTION\_RETRIES** `integer`
>
> Number of reconnection attempts. Default: 5.

***

## Mapping Configuration

Each `ADD MAPPING` block defines which topics are bridged and in which direction.

> **Topic Mapping**
>
> **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:

```lot wrap  theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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

> **Use TLS for External Connections**
>
> Always enable TLS when connecting to external brokers:
>
> ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> WITH USE_TLS "true"
> ```

> **Unique Client IDs**
>
> Each bridge connection needs a unique CLIENT\_ID to avoid conflicts:
>
> ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> WITH CLIENT_ID "EdgeDevice001-SensorBridge"
> ```

> **Test with Local Broker First**
>
> Use `WITH BROKER SELF` during development:
>
> ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> ADD SOURCE_CONFIG
>     WITH BROKER SELF
> ```

> **Secure Credentials**
>
> Store passwords securely and use app-specific passwords where available.

> **Handle Reconnection**
>
> Configure appropriate retry settings:
>
> ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> WITH RECONNECTION_RETRIES '10'
> ```

***

## Troubleshooting

> **Bridge Connection Timeout**
>
> * 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`

> **TLS/Certificate Errors**
>
> * 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)

> **Messages Not Bridging**
>
> * 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

> **[System Routes](../system-routes)**
>
> Compare bridging and Sparkplug roles.

> **[Sparkplug B](./sparkplug-b)**
>
> Publish and consume structured industrial MQTT data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.