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

# Routes Overview

> Connect your Coreflux broker to external systems, databases, industrial equipment, and other brokers using LoT routes

## What are Routes?

Routes define connections between your Coreflux MQTT broker and external systems. They enable broker-to-broker communication, database storage, industrial protocol integration, REST API connectivity, email notifications, AI integration, and media processing - all without writing custom middleware.

<Tip>
  Routes extend your broker's capabilities by creating managed connections to external systems - all configured through LoT syntax.
</Tip>

<Frame caption="Routes connect your Coreflux MQTT broker to databases, industrial equipment, APIs, cloud services, and more">
  <img src="https://mintcdn.com/coreflux/A0D_IE52Pl2ItO0u/images/routes-overview-diagram.png?fit=max&auto=format&n=A0D_IE52Pl2ItO0u&q=85&s=1f41236b69c4a0dc4fc5e18047a80db6" alt="Architecture diagram showing the Coreflux MQTT broker at the center connected to databases, PLCs, REST APIs, cloud brokers, email, and AI through Routes" width="739" height="488" data-path="images/routes-overview-diagram.png" />
</Frame>

## Route Categories

<CardGroup cols={2}>
  <Card title="System Routes" icon="server" href="./system-routes">
    Broker clustering and scalability configurations for high-availability deployments.
  </Card>

  <Card title="Data Pipeline Routes" icon="arrow-right-arrow-left" href="./data-pipeline-routes">
    MQTT bridges, email notifications, and MQTT-to-REST forwarding.
  </Card>

  <Card title="Data Storage Routes" icon="database" href="./data-storage/overview">
    Store MQTT data in PostgreSQL, MySQL, MongoDB, OpenSearch, Snowflake, and more.
  </Card>

  <Card title="REST API Routes" icon="globe" href="./rest-api-routes">
    HTTP client/server for external API integration and webhook endpoints.
  </Card>

  <Card title="Industrial Routes" icon="industry" href="./industrial/overview">
    Connect to PLCs via Modbus, Siemens S7, OPC UA, ADS, Allen-Bradley, and FINS.
  </Card>

  <Card title="MCP Routes" icon="brain" href="./mcp-routes">
    Connect to external tools and services through MCP.
  </Card>

  <Card title="AI Routes" icon="robot" href="./ai-routes">
    Add an autonomous AI assistant that can read topics and call tools.
  </Card>

  <Card title="Media Routes" icon="video" href="./media-routes">
    Barcode scanning and video streaming capabilities.
  </Card>
</CardGroup>

This page covers the fundamentals of route configuration. Choose a specific route category above for detailed syntax and examples.

***

## Basic Syntax

```lot theme={null}
DEFINE ROUTE <route_name> WITH TYPE <route_type>
    ADD <CONFIG_SECTION>
        WITH <parameter> "<value>"
    ADD MAPPING <mapping_name>
        WITH SOURCE_TOPIC "<source>"
        WITH DESTINATION_TOPIC "<destination>"
```

### Components

<ParamField path="route_name" type="string" required>
  Unique identifier for the route. Use descriptive names like `CloudBridge`, `SensorDataIndexer`, `AlertEmailer`.
</ParamField>

<ParamField path="route_type" type="type" required>
  The type of route (see Available Route Types below).
</ParamField>

<ParamField path="CONFIG_SECTION" type="block">
  Configuration blocks specific to the route type (e.g., `MQTT_CONFIG`, `MONGODB_CONFIG`, `REST_API_CONFIG`).
</ParamField>

<ParamField path="MAPPING" type="block">
  Defines topic mappings for data flow between source and destination.
</ParamField>

***

## Available Route Types

<Tabs>
  <Tab title="System">
    | Route Type     | Description                       |
    | -------------- | --------------------------------- |
    | `MQTT_CLUSTER` | Broker clustering and scalability |
  </Tab>

  <Tab title="Data Pipeline">
    | Route Type     | Description                              |
    | -------------- | ---------------------------------------- |
    | `MQTT_BRIDGE`  | Broker-to-broker communication           |
    | `EMAIL`        | Send templated emails from MQTT messages |
    | `MQTT_TO_REST` | Forward MQTT to REST endpoints           |
  </Tab>

  <Tab title="Data Storage">
    | Route Type     | Description                    |
    | -------------- | ------------------------------ |
    | `POSTGRESQL`   | PostgreSQL database storage    |
    | `MYSQL`        | MySQL database storage         |
    | `MARIADB`      | MariaDB database storage       |
    | `SQLSERVER`    | SQL Server database storage    |
    | `MONGODB`      | MongoDB document database      |
    | `OPENSEARCH`   | OpenSearch indexing and search |
    | `CRATEDB`      | CrateDB time-series database   |
    | `SNOWFLAKE`    | Snowflake cloud data warehouse |
    | `FILE_STORAGE` | CSV/JSON file storage          |
  </Tab>

  <Tab title="Industrial">
    | Route Type      | Description                 |
    | --------------- | --------------------------- |
    | `MODBUS_TCP`    | Modbus TCP protocol         |
    | `MODBUS_SERIAL` | Modbus RTU over RS-232/485  |
    | `SIEMENS_S7`    | Siemens S7 PLCs             |
    | `OPCUA`         | OPC UA client               |
    | `ADS`           | Beckhoff TwinCAT ADS        |
    | `ALLEN_BRADLEY` | Allen-Bradley/Rockwell PLCs |
    | `ETHERNETIP`    | EtherNet/IP CIP protocol    |
    | `FINS`          | Omron FINS protocol         |
  </Tab>

  <Tab title="Other">
    | Route Type     | Description                               |
    | -------------- | ----------------------------------------- |
    | `REST_API`     | REST API client/server                    |
    | `MCP`          | Model Context Protocol for external tools |
    | `AGENT`        | Autonomous AI assistant with tool access  |
    | `BARCODE`      | Barcode encoding/decoding                 |
    | `VIDEO_INPUT`  | Video capture                             |
    | `VIDEO_OUTPUT` | Video streaming                           |
  </Tab>
</Tabs>

***

## Quick Examples

<Tabs>
  <Tab title="Email Alerts">
    Send email notifications from MQTT events:

    ```lot theme={null}
    DEFINE ROUTE AlertEmail WITH TYPE EMAIL
        ADD SMTP_CONFIG
            WITH HOST "smtp.gmail.com"
            WITH PORT '587'
            WITH USERNAME "alerts@company.com"
            WITH PASSWORD "app-password"
            WITH USE_TLS "true"
        ADD EVENT criticalAlert
            WITH SOURCE_TOPIC "alerts/critical/+"
            WITH SUBJECT "Critical Alert: {value.json.type}"
            WITH RECIPIENT "team@company.com"
    ```
  </Tab>

  <Tab title="Modbus TCP">
    Read data from PLCs via Modbus:

    ```lot theme={null}
    DEFINE ROUTE PlcReader WITH TYPE MODBUS_TCP
        ADD MODBUS_CONFIG
            WITH HOST "192.168.1.100"
            WITH PORT '502'
            WITH SLAVE_ID '1'
        ADD MAPPING Sensors
            WITH EVERY 500 MILLISECONDS
            ADD TAG Temperature
                WITH ADDRESS "100"
                WITH ADDRESS_TYPE "HOLDING_REGISTER"
                WITH DATA_TYPE "FLOAT"
                WITH SOURCE_TOPIC "plc/temperature"
    ```
  </Tab>

  <Tab title="REST API">
    Connect to external REST APIs:

    ```lot theme={null}
    DEFINE ROUTE WeatherService WITH TYPE REST_API
        ADD REST_API_CONFIG
            WITH ENABLE_CLIENT "true"
            WITH BASE_ADDRESS "https://api.weather.com"
            WITH USE_SSL "true"
        ADD EVENT GetWeather
            WITH SOURCE_TOPIC "weather/request"
            WITH DESTINATION_TOPIC "weather/response"
            WITH METHOD "GET"
            WITH ENDPOINT "/v1/current?city={value.json.city}"
    ```
  </Tab>

  <Tab title="PostgreSQL Storage">
    Store MQTT data in PostgreSQL:

    ```lot theme={null}
    DEFINE ROUTE SensorDB WITH TYPE POSTGRESQL
        ADD SQL_CONFIG
            WITH SERVER "postgres.example.com"
            WITH PORT '5432'
            WITH DATABASE "iot_data"
            WITH USERNAME "iot_user"
            WITH PASSWORD "secure_password"
        ADD EVENT StoreSensorReading
            WITH SOURCE_TOPIC "sensors/+/reading"
            WITH QUERY "INSERT INTO readings (ts, sensor, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
    ```
  </Tab>

  <Tab title="MQTT Bridge">
    Connect two brokers and sync topics:

    ```lot theme={null}
    DEFINE ROUTE CloudBridge WITH TYPE MQTT_BRIDGE
        ADD SOURCE_CONFIG
            WITH BROKER SELF
        ADD DESTINATION_CONFIG
            WITH BROKER_ADDRESS "cloud.example.com"
            WITH BROKER_PORT '8883'
            WITH CLIENT_ID "EdgeBridge"
            WITH USE_TLS "true"
        ADD MAPPING sensorSync
            WITH SOURCE_TOPIC "sensors/+/data"
            WITH DESTINATION_TOPIC "edge/sensors/+/data"
            WITH DIRECTION "out"
    ```
  </Tab>
</Tabs>

***

## Understanding Route Configuration

Routes share two common building blocks: **MQTT configuration** and **topic mappings**. You'll see these across most route types, so understanding them here saves time when setting up any specific route.

### Connecting to a Broker

Routes that communicate with MQTT brokers — like bridges — need to know which broker to talk to. The simplest option is `BROKER SELF`, which tells the route to use your local Coreflux broker:

```lot theme={null}
ADD MQTT_CONFIG
    WITH BROKER SELF
```

When you need to reach a **remote** or **authenticated** broker (for example, a cloud broker or a second Coreflux instance on your network), provide the connection details explicitly:

```lot theme={null}
ADD MQTT_CONFIG
    WITH BROKER_ADDRESS "192.168.1.50"
    WITH BROKER_PORT '1883'
    WITH CLIENT_ID "MyRouteClient"
    WITH USERNAME "user"
    WITH PASSWORD "password"
```

<Note>
  Not every route type requires an `MQTT_CONFIG` block. Database routes, email routes, and REST routes have their own configuration sections. Check the specific route page for details.
</Note>

### Controlling Data Flow with Mappings

Mappings define **which MQTT topics** flow through a route and **in which direction**. For example, to push local sensor readings to a cloud broker:

```lot theme={null}
ADD MAPPING sensorSync
    WITH SOURCE_TOPIC "sensors/+/temperature"
    WITH DESTINATION_TOPIC "cloud/sensors/+/temperature"
    WITH DIRECTION "out"
```

The `DIRECTION` parameter controls where data goes:

| Direction | What it does                | Example scenario             |
| --------- | --------------------------- | ---------------------------- |
| `out`     | Local broker to destination | Push edge data to the cloud  |
| `in`      | Destination to local broker | Pull remote commands locally |
| `both`    | Bidirectional sync          | Keep two brokers in sync     |

***

## Route Status Monitoring

Every route automatically publishes real-time health and status information to a dedicated MQTT topic. No additional configuration is required — the status topic is created as soon as the route is defined.

<Note>
  Status updates are published to a `$SYS` topic and are available to any client subscribed to the broker.
</Note>

### Status Topic

The topic follows this pattern:

```
$SYS/Coreflux/Routes/<route_name>/status
```

For example, a route named `MyS7Route` publishes its status to `$SYS/Coreflux/Routes/MyS7Route/status`.

### Status Payload

The status topic publishes a JSON object with connection health, message statistics, and timing information:

```json theme={null}
{
  "name": "MyS7Route",
  "type": "SIEMENS_S7",
  "connection": "Connected",
  "health": "Green",
  "errors": {
    "total": 0,
    "consecutive": 0,
    "rate": 0
  },
  "messages": {
    "total": 4749,
    "succeeded": 4749,
    "failed": 0
  },
  "lastActivity": "2026-03-03T15:03:14.563Z",
  "lastSuccess": "2026-03-03T15:03:14.563Z",
  "lastError": null,
  "uptime": "00:08:01",
  "connectedSince": "2026-03-03T14:55:13.299Z",
  "timestamp": "2026-03-03T15:03:14.590Z"
}
```

### Field Reference

| Field                | Type           | Description                                                             |
| -------------------- | -------------- | ----------------------------------------------------------------------- |
| `name`               | string         | The route name as defined in LoT                                        |
| `type`               | string         | The route type (e.g., `SIEMENS_S7`, `MQTT_BRIDGE`, `POSTGRESQL`)        |
| `connection`         | string         | Current connection state (`Connected`, `Disconnected`, etc.)            |
| `health`             | string         | Overall health indicator (`Green`, `Yellow`, `Red`)                     |
| `errors.total`       | integer        | Total number of errors since the route started                          |
| `errors.consecutive` | integer        | Number of consecutive errors without a successful message               |
| `errors.rate`        | number         | Current error rate                                                      |
| `messages.total`     | integer        | Total messages processed                                                |
| `messages.succeeded` | integer        | Messages processed successfully                                         |
| `messages.failed`    | integer        | Messages that failed processing                                         |
| `lastActivity`       | string         | ISO 8601 timestamp of the last message (success or failure)             |
| `lastSuccess`        | string         | ISO 8601 timestamp of the last successful message                       |
| `lastError`          | string \| null | ISO 8601 timestamp of the last error, or `null` if no errors occurred   |
| `uptime`             | string         | Time the route has been running (`HH:MM:SS`)                            |
| `connectedSince`     | string         | ISO 8601 timestamp of when the route established its current connection |
| `timestamp`          | string         | ISO 8601 timestamp of when this status update was generated             |

### Checking Route Status

You can monitor any route's health by subscribing to its status topic. Use MQTT Explorer or any MQTT client to subscribe:

```
$SYS/Coreflux/Routes/+/status
```

This wildcard subscription shows status updates for **all** active routes at once.

***

## Use Cases

<Tabs>
  <Tab title="Edge-to-Cloud Sync">
    Bridge local edge data to cloud brokers:

    ```lot theme={null}
    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 USE_TLS "true"
        ADD MAPPING allSensors
            WITH SOURCE_TOPIC "local/sensors/#"
            WITH DESTINATION_TOPIC "edge-01/sensors/#"
            WITH DIRECTION "out"
    ```
  </Tab>

  <Tab title="Industrial Integration">
    Read data from PLCs via multiple protocols:

    ```lot theme={null}
    DEFINE ROUTE SiemensPLC WITH TYPE SIEMENS_S7
        ADD S7_CONFIG
            WITH IP "192.168.1.100"
            WITH CPU_TYPE "S71500"
            WITH RACK '0'
            WITH SLOT '1'
        ADD MAPPING ProcessData
            WITH EVERY 500 MILLISECONDS
            ADD TAG Temperature
                WITH ADDRESS "DB1.DBD0"
                WITH DATA_TYPE "REAL"
                WITH SOURCE_TOPIC "plc/temperature"
    ```
  </Tab>

  <Tab title="Real-Time Analytics">
    Store sensor data for analysis:

    ```lot theme={null}
    DEFINE ROUTE AnalyticsStore WITH TYPE OPENSEARCH
        ADD OPENSEARCH_CONFIG
            WITH BASE_URL "https://analytics.example.com:9200"
            WITH USERNAME "admin"
            WITH PASSWORD "password"
            WITH USE_SSL "true"
        ADD EVENT IndexReading
            WITH SOURCE_TOPIC "sensors/#"
            WITH QUERY "CLEAN:{index: sensor-data, body: {timestamp: {timestamp}, value: {value.json}}}"
    ```
  </Tab>

  <Tab title="Alert Notifications">
    Email stakeholders when critical events occur:

    ```lot theme={null}
    DEFINE ROUTE CriticalAlerts WITH TYPE EMAIL
        ADD SMTP_CONFIG
            WITH HOST "smtp.office365.com"
            WITH PORT '587'
            WITH USE_TLS "true"
            WITH USERNAME "alerts@company.com"
            WITH PASSWORD "password"
        ADD EVENT notify
            WITH SOURCE_TOPIC "alarms/critical/+"
            WITH SUBJECT "CRITICAL: {value.json.alarm_type}"
            WITH RECIPIENT "ops-team@company.com"
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Industrial Routes" icon="industry" href="./industrial/overview">
    Connect to PLCs and industrial equipment.
  </Card>

  <Card title="Data Storage" icon="database" href="./data-storage">
    Store MQTT data in databases.
  </Card>
</CardGroup>