diff --git a/README.md b/README.md index bfa70ea..988adf4 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,129 @@ # DD3-LoRa-Bridge-MultiSender -Unified firmware for LilyGO T3 v1.6.1 (ESP32 + SX1276 + SSD1306) running as either: -- `Sender`: reads energy-only values from multiple IEC 62056-21 meters and sends binary batches over LoRa. -- `Receiver`: accepts batches, ACKs with optional time, publishes to MQTT/web. +Firmware for LilyGO T3 v1.6.1 (`ESP32 + SX1276 + SSD1306`) that runs as either: +- `Sender` (PIN `GPIO14` HIGH): reads multiple IEC 62056-21 meters, batches data, sends over LoRa. +- `Receiver` (PIN `GPIO14` LOW): receives/ACKs batches, publishes MQTT, serves web UI, logs to SD. -## Protocol (minimal) +## Current Architecture -Frame format: +- Single codebase, role selected at boot via `detect_role()` (`include/config.h`, `src/config.cpp`). +- LoRa link uses explicit CRC16 frame protection in firmware (`src/lora_transport.cpp`), in addition to LoRa PHY CRC. +- Sender batches up to `30` samples and retransmits on missing ACK (`BATCH_MAX_RETRIES=2`, policy `Keep`). +- Receiver handles AP fallback when STA config is missing/invalid and exposes a config/status web UI. -`[msg_kind:1][dev_id_short:2][payload...][crc16:2]` +## LoRa Frame Protocol (Current) + +Frame format on-air: + +`[msg_kind:1][device_short_id:2][payload...][crc16:2]` `msg_kind`: -- `0`: `BATCH_UP` (Sender -> Receiver) -- `1`: `ACK_DOWN` (Receiver -> Sender) +- `0` = `BatchUp` +- `1` = `AckDown` -Removed from protocol: -- protocol version field -- payload type field -- MeterData JSON/compressed LoRa path -- standalone TimeSync packets +### `BatchUp` -CRC16 validation is still required on every frame. +`BatchUp` is chunked in transport (`batch_id`, `chunk_index`, `chunk_count`, `total_len`) and then decoded via `payload_codec`. -## Payloads +Payload header contains: +- fixed magic/schema fields (`kMagic=0xDDB3`, `kSchema=2`) +- `schema_id` +- sender/batch/time/error metadata -### 1) `BATCH_UP` -- Uses existing binary batch/chunk transport. -- `sample_count == 0` is valid and means `SYNC_REQUEST`. -- Payload starts with `schema_id`: - - `0`: legacy schema (kept for compatibility) - - `1`: `EnergyMulti` schema (ts + integer kWh for up to 3 meters) +Supported payload schemas in this branch: +- `schema_id=1` (`EnergyMulti`): integer kWh for up to 3 meters (`energy1_kwh`, `energy2_kwh`, `energy3_kwh`) +- `schema_id=0` (legacy): older energy/power delta encoding path remains decode-compatible -### 2) `ACK_DOWN` (7 bytes) -- `flags` (`u8`): bit0 = `time_valid` -- `batch_id` (`u16`, big-endian) -- `epoch_utc` (`u32`, big-endian) +`n == 0` is used as sync request (no meter samples). -Receiver sets: -- `time_valid=1` only when receiver time is authoritative and sane. -- Otherwise `time_valid=0` and `epoch_utc=0`. +### `AckDown` (7 bytes) -## Time bootstrap safety +`[flags:1][batch_id_be:2][epoch_utc_be:4]` -Sender starts with: +- `flags bit0`: `time_valid` +- Receiver sends ACK repeatedly (`ACK_REPEAT_COUNT=3`, `ACK_REPEAT_DELAY_MS=200`). +- Sender accepts time only if `time_valid=1` and `epoch >= MIN_ACCEPTED_EPOCH_UTC` (`2026-02-01 00:00:00 UTC`). + +## Time Bootstrap Guardrail + +On sender boot: - `g_time_acquired=false` -- no real sampling/batching -- periodic `SYNC_REQUEST` every `SYNC_REQUEST_INTERVAL_MS` (default `15000ms`) +- only sync requests every `SYNC_REQUEST_INTERVAL_MS` (15s) +- no normal sampling/transmit until valid ACK time received -Sender only accepts time from `ACK_DOWN` if: -- `time_valid == 1` -- `epoch_utc >= 2026-02-01 00:00:00 UTC` (`MIN_ACCEPTED_EPOCH_UTC = 1769904000`) +This prevents publishing/storing pre-threshold timestamps. -Only then: -- system time is set -- `g_time_acquired=true` -- normal 1 Hz sampling + batch transmit starts +## Multi-Meter Sender Behavior -This guarantees no pre-`2026-02-01` epoch reaches MQTT or SD/DB paths. +Implemented in `src/meter_driver.cpp` + sender path in `src/main.cpp`: -## Multi-meter sender mode - -- Meter protocol: IEC 62056-21 ASCII Mode D -- UART framing: `9600 7E1` -- Extracted OBIS: only total energy `1-0:1.8.0` -- Conversion: kWh is sent as integer using `floor` (`12345.67 -> 12345`) - -### Meter count by build mode +- Meter protocol: IEC 62056-21 ASCII, Mode D style framing (`/ ... !`) +- UART settings: `9600 7E1` +- Parsed OBIS: `1-0:1.8.0` +- Conversion: floor to integer kWh (`floorf`) +Meter count is build-dependent (`include/config.h`): - Debug builds (`SERIAL_DEBUG_MODE=1`): `METER_COUNT=2` - - keeps USB serial logs on UART0 - - uses UART1 + UART2 for meters - Prod builds (`SERIAL_DEBUG_MODE=0`): `METER_COUNT=3` - - no serial logging - - reclaims UART0 for meter 3 RX -### Meter RX pins (TTGO T3 v1.6.1 defaults) +Default RX pins: +- Meter1: `GPIO34` (`Serial2`) +- Meter2: `GPIO25` (`Serial1`) +- Meter3: `GPIO3` (`Serial`, prod only because debug serial is disabled) -- `PIN_METER1_RX = GPIO34` (UART2 RX) -- `PIN_METER2_RX = GPIO25` (UART1 RX) -- `PIN_METER3_RX = GPIO3` (UART0 RX, prod only) +## Receiver Behavior -All pins are configurable in `include/config.h`. +For valid `BatchUp` decode: +1. Reassemble chunks and decode payload. +2. Send `AckDown` immediately. +3. Drop duplicate batches per sender (`batch_id` tracking). +4. If `n==0`: treat as sync request only. +5. Else convert to `MeterData`, log to SD, update web UI, publish MQTT. -## Receiver MQTT output (EnergyMulti) +## MQTT Topics and Payloads -For `schema_id=1`, MQTT payload includes integer fields: -- `energy1_kwh` -- `energy2_kwh` -- `energy3_kwh` (when meter count is 3) +State topic: +- `smartmeter//state` -## Receiver behavior +Fault topic (retained): +- `smartmeter//faults` -On `BATCH_UP`: -1. Decode batch/chunks. -2. Send `ACK_DOWN` immediately. -3. If `sample_count == 0`: treat as `SYNC_REQUEST`, do not publish MQTT/update stats. -4. Else decode and publish samples as normal. +For `EnergyMulti` samples, state JSON includes: +- `id`, `ts` +- `energy1_kwh`, `energy2_kwh`, optional `energy3_kwh` +- `bat_v`, `bat_pct` +- optional link fields: `rssi`, `snr` +- fault/reject fields: `err_last`, `rx_reject`, `rx_reject_text` (+ non-zero counters) -## Sender/Receiver debug logs (`SERIAL_DEBUG_MODE`) +Home Assistant discovery publishing is enabled (`ENABLE_HA_DISCOVERY=true`) but still advertises legacy keys (`e_kwh`, `p_w`, `p1_w`, `p2_w`, `p3_w`) in `src/mqtt_client.cpp`. -Sender: -- `sync: request tx batch_id=%u` -- `ack: rx ok batch_id=%u time_valid=%u epoch=%lu set=%u` -- `ack: timeout batch_id=%u retry=%u` +## Web UI, Wi-Fi, Storage -Receiver: -- `ack: tx batch_id=%u time_valid=%u epoch=%lu samples=%u` +- STA config is stored in Preferences (`wifi_manager`). +- If STA/MQTT config is unavailable, receiver starts AP mode with SSID prefix `DD3-Bridge-`. +- Web auth defaults are `admin/admin` (`WEB_AUTH_DEFAULT_USER/PASS`). +- SD logging is enabled (`ENABLE_SD_LOGGING=true`). -## Removed hardware dependency +## Build Environments -DS3231 RTC support was removed: -- no RTC files -- no RTC init/load/set logic -- no `ENABLE_DS3231` flow +From `platformio.ini`: -## Build +- `lilygo-t3-v1-6-1` +- `lilygo-t3-v1-6-1-test` +- `lilygo-t3-v1-6-1-868` +- `lilygo-t3-v1-6-1-868-test` +- `lilygo-t3-v1-6-1-payload-test` +- `lilygo-t3-v1-6-1-868-payload-test` +- `lilygo-t3-v1-6-1-prod` +- `lilygo-t3-v1-6-1-868-prod` + +Example: ```bash -pio run -e lilygo-t3-v1-6-1 -pio run -e lilygo-t3-v1-6-1-test -pio run -e lilygo-t3-v1-6-1-prod +~/.platformio/penv/bin/pio run -e lilygo-t3-v1-6-1 ``` + +## Test Mode + +`ENABLE_TEST_MODE` replaces normal sender/receiver loops with dedicated test loops (`src/test_mode.cpp`). +It sends/receives plain JSON test frames and publishes to `smartmeter//test`.