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

![Architecture diagram showing the Coreflux MQTT broker at the center connected to databases, PLCs, REST APIs, cloud brokers, email, and AI through Routes](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/product-overview-diagram.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=8e40e7ae59a9ca0254a45a115bc4f448)

## Route Categories

> **[System Routes](./system-routes)**
>
> Configure MQTT bridges and Sparkplug roles.

> **[Streaming Routes](./streaming/kafka)**
>
> Connect MQTT topics to external event-streaming platforms.

> **[Notification Routes](./notifications/email)**
>
> Send alerts and reports to people from MQTT events.

> **[Data Storage Routes](./data-storage/overview)**
>
> Store MQTT data in PostgreSQL, MySQL, MongoDB, OpenSearch, Snowflake, and more.

> **[REST API Routes](./rest-api-routes)**
>
> HTTP client/server for external API integration and webhook endpoints.

> **[Industrial Routes](./industrial/overview)**
>
> Connect to PLCs via Modbus, Siemens S7, OPC UA, ADS, Allen-Bradley, and FINS.

> **[MCP Routes](./mcp-routes)**
>
> Connect to external tools and services through MCP.

> **[AI Routes](./ai-routes)**
>
> Add an autonomous AI assistant that can read topics and call tools.

> **[Media Routes](./media-routes)**
>
> Barcode scanning and video streaming capabilities.

> **[Overload configuration](./route-config)**
>
> Choose wait or drop when a route cannot keep up with incoming MQTT.

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

***

## Basic Syntax

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

**route\_name** `string` *required*

Unique identifier for the route. Use descriptive names like `CloudBridge`, `SensorDataIndexer`, `AlertEmailer`.

**route\_type** `type` *required*

The type of route (see Available Route Types below).

**CONFIG\_SECTION** `block`

Configuration blocks specific to the route type (e.g., `MQTT_CONFIG`, `MONGODB_CONFIG`, `REST_API_CONFIG`).

**ROUTE\_CONFIG** `block`

Optional. Controls wait-or-drop behavior when this route cannot keep up with incoming MQTT. Works on every route type. See [Route Overload Configuration](./route-config).

**MAPPING** `block`

Defines topic mappings for data flow between source and destination.

***

## Available Route Types

**System**

| Route Type | Description |
| - | - |
| `MQTT_BRIDGE` | Broker-to-broker topic synchronization |
| `SPARKPLUG_B` | Sparkplug decoding and edge-node publishing |
| `SPARKPLUG_HOST` | Sparkplug Primary Host Application |

**Streaming**

| Route Type | Description |
| - | - |
| `KAFKA` | Stream data both ways with Apache Kafka |

**Notification**

| Route Type | Description |
| - | - |
| `EMAIL` | Send templated emails from MQTT messages |

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

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

**Other**

| Route Type | Description |
| - | - |
| `REST_API` | REST API client/server |
| `MQTT_TO_REST` | Forward MQTT messages to REST endpoints |
| `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 |

***

## Quick Examples

**Email Alerts**

Send email notifications from MQTT events:

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

**Modbus TCP**

Read data from PLCs via Modbus:

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

**REST API**

Connect to external REST APIs:

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

**PostgreSQL Storage**

Store MQTT data in PostgreSQL:

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

**MQTT Bridge**

Connect two brokers and sync topics:

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

***

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

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

### When a route cannot keep up

Incoming MQTT can outpace the destination. Add `ADD ROUTE_CONFIG` on any route to choose whether that route waits or drops the newest message. Routes without the block use the broker default (`balanced`). See [Route Overload Configuration](./route-config).

***

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

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

**Edge-to-Cloud Sync**

Bridge local edge data to cloud brokers:

```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 USE_TLS "true"
    ADD MAPPING allSensors
        WITH SOURCE_TOPIC "local/sensors/#"
        WITH DESTINATION_TOPIC "edge-01/sensors/#"
        WITH DIRECTION "out"
```

**Industrial Integration**

Read data from PLCs via multiple protocols:

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

**Real-Time Analytics**

Store sensor data for analysis:

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

**Alert Notifications**

Email stakeholders when critical events occur:

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

## Next Steps

> **[Industrial Routes](./industrial/overview)**
>
> Connect to PLCs and industrial equipment.

> **[Data Storage](./data-storage)**
>
> Store MQTT data in databases.


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