# MQTT Bridge Implementation for MeshCore This document describes the MQTT bridge implementation that allows MeshCore repeaters to uplink packet data to multiple MQTT brokers. ## Quick Start Guide ### Essential Commands to Get MQTT Repeater Running **1. Connect to device console via repeater login or serial console (115200 baud)** ```bash # Connect to device via serial ``` **2. Configure WiFi Credentials** ```bash set wifi.ssid YourWiFiNetwork set wifi.pwd YourWiFiPassword ``` **3. Reboot to Connect to WiFi** ```bash reboot ``` **4. Verify Configuration** ```bash get wifi.ssid get bridge.enabled get mqtt.origin get mqtt.iata ``` If you wish to change mqtt.iata, use `set mqtt.iata XXX` **5. Restart Bridge (if needed)** ```bash # Option A: Toggle bridge off then on set bridge.enabled off set bridge.enabled on # Option B: Full device reboot reboot ``` **That's it!** The device will now: - Connect to WiFi automatically - Start uplinking mesh packets to Let's Mesh Analyzer - Publish to both custom MQTT broker and Let's Mesh Analyzer servers - Use device name as MQTT origin (set automatically) --- ## Overview The MQTT bridge implementation provides: - Multiple MQTT broker support (up to 3 brokers) - Automatic reconnection with exponential backoff - JSON message formatting for status, packets, and raw data - Configurable topics and QoS levels - Packet queuing during connection issues ## Files Added ### Core Implementation - `src/helpers/bridges/MQTTBridge.h` - MQTT bridge class definition - `src/helpers/bridges/MQTTBridge.cpp` - MQTT bridge implementation - `src/helpers/MQTTMessageBuilder.h` - JSON message formatting utilities - `src/helpers/MQTTMessageBuilder.cpp` - JSON message formatting implementation ### Integration - Updated `examples/simple_repeater/MyMesh.h` - Added MQTT bridge support - Updated `examples/simple_repeater/MyMesh.cpp` - Added MQTT bridge integration and raw radio data capture - Updated `src/helpers/CommonCLI.h` - Added MQTT, WiFi, and timezone configuration fields - Updated `src/helpers/CommonCLI.cpp` - Added MQTT, WiFi, and timezone CLI commands - Updated `variants/heltec_v3/platformio.ini` - Added MQTT build configuration - Updated `variants/station_g2/platformio.ini` - Added MQTT build configuration for Station G2 ## Build Configuration To build the MQTT bridge firmware: ### Heltec V3 ```bash pio run -e Heltec_v3_repeater_bridge_mqtt ``` ### Station G2 ```bash pio run -e Station_G2_repeater_bridge_mqtt ``` ### Custom MQTT Server Configuration You can configure a custom MQTT server using build flags in `platformio.ini`: ```ini [env:Heltec_v3_repeater_bridge_mqtt] build_flags = ${Heltec_lora32_v3.build_flags} -D WITH_MQTT_BRIDGE=1 -D MQTT_SERVER='"your-mqtt-broker.com"' -D MQTT_PORT=1883 -D MQTT_USERNAME='"your-username"' -D MQTT_PASSWORD='"your-password"' ``` **Build Flags:** - `MQTT_SERVER` - MQTT broker hostname - `MQTT_PORT` - MQTT broker port (default: 1883) - `MQTT_USERNAME` - MQTT username - `MQTT_PASSWORD` - MQTT password ## Default Configuration The MQTT bridge comes with the following defaults: - **Origin**: "MeshCore-Repeater" - **IATA**: "SEA" - **Status Messages**: Enabled - **Packet Messages**: Enabled - **Raw Messages**: Disabled - **TX Messages**: Disabled (RX only by default) - **Status Interval**: 5 minutes (300000 ms) - **Default Broker**: meshtastic.pugetmesh.org:1883 (username: meshdev, password: large4cats) - **WiFi SSID**: "ssid_here" (must be configured) - **WiFi Password**: "password_here" (must be configured) - **Timezone**: "America/Los_Angeles" (Pacific Time with DST support) - **Timezone Offset**: -8 hours (fallback) - **Let's Mesh Analyzer US**: Enabled (mqtt-us-v1.letsmesh.net:443) - **Let's Mesh Analyzer EU**: Enabled (mqtt-eu-v1.letsmesh.net:443) ## CLI Commands ### MQTT Commands #### Get Commands - `get mqtt.origin` - Get device origin name - `get mqtt.iata` - Get IATA code - `get mqtt.status` - Get status message setting (on/off) - `get mqtt.packets` - Get packet message setting (on/off) - `get mqtt.raw` - Get raw message setting (on/off) - `get mqtt.tx` - Get TX message setting (on/off) - `get mqtt.interval` - Get status publish interval (ms) - `get mqtt.server` - Get MQTT server hostname - `get mqtt.port` - Get MQTT server port - `get mqtt.username` - Get MQTT username - `get mqtt.password` - Get MQTT password - `get mqtt.analyzer.us` - Get US Let's Mesh Analyzer server setting (on/off) - `get mqtt.analyzer.eu` - Get EU Let's Mesh Analyzer server setting (on/off) #### Set Commands - `set mqtt.origin ` - Set device origin name - `set mqtt.iata ` - Set IATA code - `set mqtt.status on|off` - Enable/disable status messages - `set mqtt.packets on|off` - Enable/disable packet messages - `set mqtt.raw on|off` - Enable/disable raw messages - `set mqtt.tx on|off` - Enable/disable TX packet messages - `set mqtt.interval ` - Set status publish interval (1000-3600000 ms) - `set mqtt.server ` - Set MQTT server hostname - `set mqtt.port ` - Set MQTT server port (1-65535) - `set mqtt.username ` - Set MQTT username - `set mqtt.password ` - Set MQTT password - `set mqtt.analyzer.us on|off` - Enable/disable US Let's Mesh Analyzer server - `set mqtt.analyzer.eu on|off` - Enable/disable EU Let's Mesh Analyzer server ### WiFi Commands #### Get Commands - `get wifi.ssid` - Get WiFi SSID - `get wifi.pwd` - Get WiFi password #### Set Commands - `set wifi.ssid ` - Set WiFi SSID - `set wifi.pwd ` - Set WiFi password ### Timezone Commands #### Get Commands - `get timezone` - Get timezone string (e.g., "America/Los_Angeles") - `get timezone.offset` - Get timezone offset in hours (-12 to +14) #### Set Commands - `set timezone ` - Set timezone string (IANA format or abbreviation) - `set timezone.offset ` - Set timezone offset in hours (-12 to +14) #### Supported Timezone Formats - **IANA strings**: `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`, etc. - **Common abbreviations**: `PDT`, `PST`, `MDT`, `MST`, `CDT`, `CST`, `EDT`, `EST`, `BST`, `GMT`, `CEST`, `CET` - **UTC offsets**: `UTC-8`, `UTC+5`, `+5`, `-8`, etc. ### Bridge Commands #### Get Commands - `get bridge.source` - Get packet source (rx/tx) - `get bridge.enabled` - Get bridge enabled status (on/off) #### Set Commands - `set bridge.source rx|tx` - Set packet source (rx for received, tx for transmitted) - `set bridge.enabled on|off` - Enable/disable bridge ## Command Architecture The CLI commands are organized into two levels: ### Bridge Commands (`bridge.*`) **Low-level bridge control** - These settings apply to all bridge types (MQTT, RS232, ESP-NOW, etc.): - `bridge.enabled` - Master switch for the entire bridge system - `bridge.source` - Controls which packet events to capture (RX vs TX) ### Bridge-Specific Commands (`mqtt.*`, `wifi.*`, `timezone.*`) **Implementation-specific settings** - These only apply to the MQTT bridge: - `mqtt.*` - MQTT broker configuration, message types, and formatting - `wifi.*` - WiFi connection settings for MQTT connectivity - `timezone.*` - Timezone configuration for accurate timestamps This design allows MeshCore to support multiple bridge types simultaneously while keeping configuration clean and logical. ## MQTT Topics The bridge publishes to three main topics with the following structure: ### Status Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/status` Device connection status and metadata (retained messages). ### Packets Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/packets` Full packet data with RF characteristics and metadata. ### Raw Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/raw` Minimal raw packet data for map integration. **Note**: `{DEVICE_PUBLIC_KEY}` is the device's public key in hexadecimal format (64 characters). ## JSON Message Formats ### Status Message ```json { "status": "online|offline", "timestamp": "2024-01-01T12:00:00.000000", "origin": "Device Name", "origin_id": "DEVICE_PUBLIC_KEY", "model": "device_model", "firmware_version": "firmware_version", "radio": "radio_info", "client_version": "meshcore-custom-repeater/{build_date}" } ``` ### Packet Message ```json { "origin": "MeshCore-HOWL", "origin_id": "A1B2C3D4E5F67890...", "timestamp": "2024-01-01T12:00:00.000000", "type": "PACKET", "direction": "rx|tx", "time": "12:00:00", "date": "01/01/2024", "len": "45", "packet_type": "4", "route": "F|D|T|U", "payload_len": "32", "raw": "F5930103807E5F1E...", "SNR": "12.5", "RSSI": "-65", "hash": "A1B2C3D4E5F67890", "path": "node1,node2,node3" } ``` ### Raw Message ```json { "origin": "MeshCore-HOWL", "origin_id": "A1B2C3D4E5F67890...", "timestamp": "2024-01-01T12:00:00.000000", "type": "RAW", "data": "F5930103807E5F1E..." } ``` ## Key Features ### Raw Radio Data Capture - Captures actual raw radio transmission data (including radio headers) - Uses proper MeshCore packet hashing (SHA256-based) - Provides accurate SNR/RSSI values from actual radio reception - Supports both RX and TX packet uplinking (configurable) ### Timezone Support - Full timezone support with automatic DST handling - Supports IANA timezone strings, common abbreviations, and UTC offsets - Separates local time (for timestamps) and UTC time (for time/date fields) - Uses JChristensen/Timezone library for accurate timezone conversions ### WiFi Configuration - Runtime WiFi credential management via CLI - Persistent storage across reboots - Automatic reconnection with exponential backoff ### NTP Time Synchronization - Automatic time synchronization with NTP servers - Periodic time updates (every hour) - Proper UTC system time handling ### Let's Mesh Analyzer Integration - **JWT Authentication**: Ed25519-signed tokens for secure MQTT authentication - **WebSocket MQTT**: Support for MQTT over WebSocket connections (TLS/SSL) - **Dual Server Support**: Both US and EU servers enabled by default - **Automatic Token Generation**: Creates authentication tokens using device's Ed25519 keys - **Username Format**: `v1_{UPPERCASE_PUBLIC_KEY}` (e.g., `v1_7E7662676F7F0850A8A355BAAFBFC1EB7B4174C340442D7D7161C9474A2C9400`) - **Server Configuration**: - US Server: `mqtt-us-v1.letsmesh.net:443` (WebSocket with TLS) - EU Server: `mqtt-eu-v1.letsmesh.net:443` (WebSocket with TLS) ## First-Time Setup ### Prerequisites - MeshCore device with MQTT bridge firmware flashed - WiFi network credentials - MQTT broker (optional - default broker is provided) - LoRa-capable device for configuration (repeater console) - MeshCore network access ### Step 1: Initial Boot and Network Connection 1. **Flash the firmware** to your device using PlatformIO or the build script 2. **Deploy the device** in your mesh network location 3. **Ensure WiFi connectivity** - the device will automatically connect to WiFi if credentials are pre-configured 4. **Verify mesh network access** - device should be discoverable by other mesh nodes ### Step 2: Connect via LoRa Repeater Console Use a MeshCore companion device to configure the Repeater's MQTT bridge. 1. **Connect to the mesh** using your companion 2. **Locate the MQTT bridge device** in your contacts 3. **Log into your Repeater** using the default password (password) or whatever you configured via serial console 3. **Tap on the repeater console** on your repeater's settings 4. **Send configuration commands** via LoRa to the MQTT bridge device ### Step 3: Configure WiFi Connection The device needs internet connectivity to publish to MQTT brokers. **Via LoRa Repeater Console:** ``` # Set your WiFi credentials set wifi.ssid "YourWiFiNetwork" set wifi.pwd "YourWiFiPassword" # Verify WiFi settings get wifi.ssid get wifi.pwd ``` ### Step 4: Configure Device Identity Set up your device's identity for MQTT topics and status messages. **Via LoRa Repeater Console:** ``` # Set IATA code for topic structure (e.g., airport code) set mqtt.iata "SEA" # Verify settings (origin is set automatically to device name) get mqtt.origin get mqtt.iata ``` ### Step 5: Configure Timezone Set your local timezone for accurate timestamps. **Via LoRa Repeater Console:** ``` # Set timezone (choose one method) set timezone "America/Los_Angeles" # IANA format set timezone "PDT" # Abbreviation set timezone "UTC-8" # UTC offset # Verify timezone get timezone ``` ### Step 6: Configure MQTT Settings Customize which messages to publish and how often. **Via LoRa Repeater Console:** ``` # Configure MQTT server (optional - uses defaults if not set) set mqtt.server "your-mqtt-broker.com" set mqtt.port 1883 set mqtt.username "your-username" set mqtt.password "your-password" # Enable/disable message types set mqtt.status on # Device status messages set mqtt.packets on # Packet data messages set mqtt.raw off # Raw packet data (optional) set mqtt.tx off # Transmitted packets (optional) # Set status publish interval (default: 5 minutes) set mqtt.interval 300000 # Verify settings get mqtt.server get mqtt.port get mqtt.username get mqtt.status get mqtt.packets get mqtt.interval ``` ### Step 7: Verify MQTT Broker Connection Check that the device can connect to MQTT brokers. **Via LoRa Repeater Console:** ``` # Check bridge status get bridge.enabled # If disabled, enable it set bridge.enabled on # Check MQTT analyzer servers (optional) get mqtt.analyzer.us get mqtt.analyzer.eu ``` ### Step 8: Monitor MQTT Messages Once configured, the device will automatically publish messages to MQTT brokers. **Default MQTT Broker**: `meshtastic.pugetmesh.org:1883` - Username: `meshdev` - Password: `large4cats` **Topic Structure**: - Status: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/status` - Packets: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/packets` - Raw: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/raw` **Example Topics**: - `meshcore/SEA/7E7662676F7F0850A8A355BAAFBFC1EB7B4174C340442D7D7161C9474A2C9400/status` - `meshcore/SEA/7E7662676F7F0850A8A355BAAFBFC1EB7B4174C340442D7D7161C9474A2C9400/packets` ### Step 9: Troubleshooting #### Device Won't Connect to WiFi **Via LoRa Repeater Console:** ``` # Check WiFi settings get wifi.ssid get wifi.pwd # Reset WiFi settings set wifi.ssid "" set wifi.pwd "" # Reconfigure with correct credentials set wifi.ssid "YourWiFiNetwork" set wifi.pwd "YourWiFiPassword" ``` #### No MQTT Messages Appearing **Via LoRa Repeater Console:** ``` # Check bridge status get bridge.enabled # Check message types get mqtt.status get mqtt.packets # Check device identity (origin is set automatically) get mqtt.origin get mqtt.iata # Enable bridge if needed set bridge.enabled on ``` #### Timezone Issues **Via LoRa Repeater Console:** ``` # Check current timezone get timezone # Try different timezone formats set timezone "America/New_York" # IANA format set timezone "EST" # Abbreviation set timezone "UTC-5" # UTC offset ``` #### LoRa Configuration Issues - **Device not responding**: Ensure both devices are on the same mesh network - **Commands not working**: Check that the target device is reachable via LoRa - **No response to get commands**: Verify the device is powered and in range ### Step 10: Advanced Configuration (Optional) #### Custom MQTT Broker If you want to use your own MQTT broker instead of the default: ``` # Note: Custom broker configuration requires code modification # The default broker is: meshtastic.pugetmesh.org:1883 # Username: meshdev, Password: large4cats ``` #### Let's Mesh Analyzer Servers The device automatically connects to Let's Mesh Analyzer servers for additional monitoring: - **US Server**: `mqtt-us-v1.letsmesh.net:443` (WebSocket with TLS) - **EU Server**: `mqtt-eu-v1.letsmesh.net:443` (WebSocket with TLS) These are enabled by default and use JWT authentication with your device's Ed25519 keys. ## Testing 1. Flash the MQTT bridge firmware to your device 2. Follow the first-time setup instructions above 3. Monitor MQTT broker for incoming messages 4. Verify message formats match the JSON schemas in this document ## Dependencies - **PubSubClient**: MQTT client library - **ArduinoJson**: JSON message formatting (v6.17.3) - **NTPClient**: Network time protocol client - **Timezone**: Timezone conversion library (JChristensen/Timezone) - **WiFi**: ESP32 WiFi functionality - **Ed25519**: Cryptographic library for JWT token signing - **JWTHelper**: Custom JWT token generation for Let's Mesh Analyzer authentication ## Future Enhancements - Full WebSocket MQTT implementation (currently JWT tokens are generated but WebSocket publishing is pending) - Multiple broker configuration via CLI - Advanced packet filtering - Custom topic templates - TLS/SSL support for secure connections - Real-time WebSocket MQTT publishing to Let's Mesh Analyzer servers