diff --git a/MQTT_IMPLEMENTATION.md b/MQTT_IMPLEMENTATION.md index 9a1b7455e..fdad77ed4 100644 --- a/MQTT_IMPLEMENTATION.md +++ b/MQTT_IMPLEMENTATION.md @@ -21,19 +21,26 @@ The MQTT bridge implementation provides: ### Integration - Updated `examples/simple_repeater/MyMesh.h` - Added MQTT bridge support -- Updated `examples/simple_repeater/MyMesh.cpp` - Added MQTT bridge integration -- Updated `src/helpers/CommonCLI.h` - Added MQTT configuration fields -- Updated `src/helpers/CommonCLI.cpp` - Added MQTT CLI commands +- 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 +``` + ## Default Configuration The MQTT bridge comes with the following defaults: @@ -42,40 +49,103 @@ The MQTT bridge comes with the following defaults: - **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) ## CLI Commands -### Get 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) -### Set Commands +#### 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) +### 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: +The bridge publishes to three main topics with the following structure: -### Status Topic: `meshcore/{IATA}/status` +### Status Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/status` Device connection status and metadata (retained messages). -### Packets Topic: `meshcore/{IATA}/packets` +### Packets Topic: `meshcore/{IATA}/{DEVICE_PUBLIC_KEY}/packets` Full packet data with RF characteristics and metadata. -### Raw Topic: `meshcore/{IATA}/raw` +### 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 @@ -125,18 +195,45 @@ Minimal raw packet data for map integration. } ``` +## 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 + ## Testing 1. Flash the MQTT bridge firmware to your device 2. Connect to the device via serial console -3. Configure WiFi connection (if not already connected) -4. Check MQTT settings: `get mqtt.origin` -5. Monitor MQTT broker for incoming messages +3. Configure WiFi connection: `set wifi.ssid "YourSSID"` and `set wifi.pwd "YourPassword"` +4. Configure timezone: `set timezone "America/Los_Angeles"` +5. Check MQTT settings: `get mqtt.origin` +6. Monitor MQTT broker for incoming messages ## Dependencies - **PubSubClient**: MQTT client library -- **ArduinoJson**: JSON message formatting +- **ArduinoJson**: JSON message formatting (v6.17.3) +- **NTPClient**: Network time protocol client +- **Timezone**: Timezone conversion library (JChristensen/Timezone) - **WiFi**: ESP32 WiFi functionality ## Future Enhancements diff --git a/variants/station_g2/platformio.ini b/variants/station_g2/platformio.ini index 59450b638..9c11c121c 100644 --- a/variants/station_g2/platformio.ini +++ b/variants/station_g2/platformio.ini @@ -21,8 +21,8 @@ build_flags = -D PIN_BOARD_SDA=5 -D PIN_BOARD_SCL=6 -D PIN_USER_BTN=38 - -D PIN_GPS_RX=15 - -D PIN_GPS_TX=7 + -D PIN_GPS_RX=7 + -D PIN_GPS_TX=15 -D SX126X_DIO2_AS_RF_SWITCH=true -D SX126X_DIO3_TCXO_VOLTAGE=1.8 -D SX126X_CURRENT_LIMIT=140 @@ -42,7 +42,6 @@ lib_deps = [env:Station_G2_repeater] extends = Station_G2 -board_build.partitions = default_16MB.csv ; standard 16MB partition table (compatible with MQTT bridge) build_flags = ${Station_G2.build_flags} -D ADVERT_NAME='"Station G2 Repeater"' @@ -54,9 +53,6 @@ build_flags = ; -D MESH_DEBUG=1 build_src_filter = ${Station_G2.build_src_filter} +<../examples/simple_repeater> - - - - - - lib_deps = ${Station_G2.lib_deps} ${esp32_ota.lib_deps} @@ -118,9 +114,6 @@ build_flags = ; -D MESH_DEBUG=1 build_src_filter = ${Station_G2.build_src_filter} +<../examples/simple_repeater> - - - - - - lib_deps = ${Station_G2.lib_deps} ${esp32_ota.lib_deps} @@ -169,38 +162,6 @@ lib_deps = ${Station_G2.lib_deps} ${esp32_ota.lib_deps} -[env:Station_G2_room_server_observer_mqtt] -extends = Station_G2 -board_build.partitions = default_16MB.csv ; standard 16MB partition table -build_flags = - ${Station_G2.build_flags} - -D ADVERT_NAME='"Station G2 Room Observer"' - -D ADVERT_LAT=0.0 - -D ADVERT_LON=0.0 - -D ADMIN_PASSWORD='"password"' - -D ROOM_PASSWORD='"hello"' - -D WITH_MQTT_BRIDGE=1 - -D MAX_MQTT_BROKERS=3 - -D MQTT_MAX_PACKET_SIZE=1024 -; -D MQTT_DEBUG=1 -; -D MESH_PACKET_LOGGING=1 -; -D MESH_DEBUG=1 - -D CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y -build_src_filter = ${Station_G2.build_src_filter} - + - + - + - + - +<../examples/simple_room_server> -lib_deps = - ${Station_G2.lib_deps} - ${esp32_ota.lib_deps} - elims/PsychicMqttClient@^0.2.4 - bblanchon/ArduinoJson - arduino-libraries/NTPClient - JChristensen/Timezone - paulstoffregen/Time - [env:Station_G2_room_server] extends = Station_G2 build_src_filter = ${Station_G2.build_src_filter} @@ -275,12 +236,11 @@ lib_deps = ${Station_G2.lib_deps} densaugeo/base64 @ ~1.4.0 -[env:Station_G2_repeater_observer_mqtt] +[env:Station_G2_repeater_bridge_mqtt] extends = Station_G2 -board_build.partitions = default_16MB.csv ; standard 16MB partition table build_flags = ${Station_G2.build_flags} - -D ADVERT_NAME='"MQTT Observer"' + -D ADVERT_NAME='"MQTT Bridge"' -D ADVERT_LAT=0.0 -D ADVERT_LON=0.0 -D ADMIN_PASSWORD='"password"' @@ -291,24 +251,15 @@ build_flags = -D MQTT_DEBUG=1 -D MESH_PACKET_LOGGING=1 -D MESH_DEBUG=1 - -D CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=y -# -D WIFI_SSID='"ssid"' -# -D WIFI_PWD='"password"' -# -D MQTT_SERVER='"your-mqtt-broker.com"' -# -D MQTT_PORT=1883 -# -D MQTT_USERNAME='"your-username"' -# -D MQTT_PASSWORD='"your-password"' build_src_filter = ${Station_G2.build_src_filter} + + - + + +<../examples/simple_repeater> lib_deps = ${Station_G2.lib_deps} ${esp32_ota.lib_deps} - elims/PsychicMqttClient@^0.2.4 - bblanchon/ArduinoJson + knolleary/PubSubClient @ ^2.8 + bblanchon/ArduinoJson @ 6.17.3 arduino-libraries/NTPClient JChristensen/Timezone - paulstoffregen/Time