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

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

<Tabs>
  <Tab title="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"
    ```
  </Tab>

  <Tab title="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"
    ```
  </Tab>

  <Tab title="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"
    ```
  </Tab>
</Tabs>

***

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

<AccordionGroup>
  <Accordion title="Broker Settings">
    <ParamField path="BROKER_ADDRESS" type="string" required>
      IP address or hostname of the broker. Use `SELF` for the local broker.
    </ParamField>

    <ParamField path="BROKER_PORT" type="integer" required>
      MQTT port (typically 1883 for unencrypted, 8883 for TLS).
    </ParamField>

    <ParamField path="CLIENT_ID" type="string" required>
      Unique client identifier for the bridge connection.
    </ParamField>
  </Accordion>

  <Accordion title="Authentication">
    <ParamField path="USERNAME" type="string">
      Authentication username.
    </ParamField>

    <ParamField path="PASSWORD" type="string">
      Authentication password.
    </ParamField>
  </Accordion>

  <Accordion title="TLS/Security">
    <ParamField path="USE_TLS" type="boolean">
      Enable TLS encryption. Default: false.
    </ParamField>

    <ParamField path="ALLOW_UNTRUSTED_CERTS" type="boolean">
      Allow untrusted certificates. Default: false.
    </ParamField>

    <ParamField path="SERVER_CA_CERT_PATH" type="string">
      Path to CA certificate file.
    </ParamField>

    <ParamField path="CLIENT_CERT_PATH" type="string">
      Path to client certificate for mTLS.
    </ParamField>

    <ParamField path="CLIENT_CERT_PASS" type="string">
      Client certificate password.
    </ParamField>
  </Accordion>

  <Accordion title="Connection Handling">
    <ParamField path="RECONNECTION_RETRIES" type="integer">
      Number of reconnection attempts. Default: 5.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

## Mapping Configuration

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

<AccordionGroup>
  <Accordion title="Topic Mapping">
    <ParamField path="SOURCE_TOPIC" type="string" required>
      Topic pattern to subscribe to on the source broker. Supports wildcards.
    </ParamField>

    <ParamField path="DESTINATION_TOPIC" type="string" required>
      Topic to publish to on the destination broker.
    </ParamField>

    <ParamField path="DIRECTION" type="string" required>
      Data flow direction: `out` (source→dest), `in` (dest→source), or `both`.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

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

<AccordionGroup>
  <Accordion title="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"
    ```
  </Accordion>

  <Accordion title="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"
    ```
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="Secure Credentials">
    Store passwords securely and use app-specific passwords where available.
  </Accordion>

  <Accordion title="Handle Reconnection">
    Configure appropriate retry settings:

    ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    WITH RECONNECTION_RETRIES '10'
    ```
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Email" icon="envelope" href="./email">
    Send alerts and notifications from MQTT messages.
  </Card>

  <Card title="Kafka" icon="bolt" href="./kafka">
    Stream data between MQTT and Apache Kafka.
  </Card>
</CardGroup>