docs: refresh README for lora-refactor behavior
This commit is contained in:
acidburns
155
README.md
155
README.md
@@ -1,88 +1,127 @@
|
|||||||
# DD3-LoRa-Bridge-MultiSender
|
# DD3-LoRa-Bridge-MultiSender
|
||||||
|
|
||||||
Unified firmware for LilyGO T3 v1.6.1 (ESP32 + SX1276 + SSD1306) running as either:
|
Firmware for LilyGO T3 v1.6.1 (`ESP32 + SX1276 + SSD1306`) that runs as either:
|
||||||
- `Sender`: reads meter values and sends binary batches over LoRa.
|
- `Sender` (PIN `GPIO14` HIGH): reads one IEC 62056-21 meter, batches samples, sends over LoRa.
|
||||||
- `Receiver`: accepts batches, ACKs with optional time, publishes to MQTT/web.
|
- `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`).
|
||||||
|
- Sender batches up to `30` samples and retries on missing ACK (`BATCH_MAX_RETRIES=2`, retry policy `Keep`).
|
||||||
|
- Receiver uses STA mode when config is valid, otherwise AP fallback with web config.
|
||||||
|
|
||||||
`[msg_kind:1][dev_id_short:2][payload...][crc16:2]`
|
## LoRa Frame Protocol (Current)
|
||||||
|
|
||||||
|
On-air frame format:
|
||||||
|
|
||||||
|
`[msg_kind:1][device_short_id:2][payload...][crc16:2]`
|
||||||
|
|
||||||
`msg_kind`:
|
`msg_kind`:
|
||||||
- `0`: `BATCH_UP` (Sender -> Receiver)
|
- `0` = `BatchUp`
|
||||||
- `1`: `ACK_DOWN` (Receiver -> Sender)
|
- `1` = `AckDown`
|
||||||
|
|
||||||
Removed from protocol:
|
### `BatchUp`
|
||||||
- protocol version field
|
|
||||||
- payload type field
|
|
||||||
- MeterData JSON/compressed LoRa path
|
|
||||||
- standalone TimeSync packets
|
|
||||||
|
|
||||||
CRC16 validation is still required on every frame.
|
Transport is chunked (`batch_id`, `chunk_index`, `chunk_count`, `total_len`) and reassembled before payload decode.
|
||||||
|
|
||||||
## Payloads
|
Payload codec (`src/payload_codec.cpp`) currently uses:
|
||||||
|
- `kMagic=0xDDB3`
|
||||||
|
- `kSchema=2`
|
||||||
|
- metadata: sender, batch, timestamp, interval, battery, fault counters
|
||||||
|
- data arrays: `energy_wh[]`, `p1_w[]`, `p2_w[]`, `p3_w[]`
|
||||||
|
|
||||||
### 1) `BATCH_UP`
|
`n == 0` is valid and used for sync request packets.
|
||||||
- Uses existing binary batch/chunk transport.
|
|
||||||
- `sample_count == 0` is valid and means `SYNC_REQUEST`.
|
|
||||||
|
|
||||||
### 2) `ACK_DOWN` (7 bytes)
|
### `AckDown` (7 bytes)
|
||||||
- `flags` (`u8`): bit0 = `time_valid`
|
|
||||||
- `batch_id` (`u16`, big-endian)
|
|
||||||
- `epoch_utc` (`u32`, big-endian)
|
|
||||||
|
|
||||||
Receiver sets:
|
`[flags:1][batch_id_be:2][epoch_utc_be:4]`
|
||||||
- `time_valid=1` only when receiver time is authoritative and sane.
|
|
||||||
- Otherwise `time_valid=0` and `epoch_utc=0`.
|
|
||||||
|
|
||||||
## Time bootstrap safety
|
- `flags bit0`: `time_valid`
|
||||||
|
- Receiver repeats ACK (`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`).
|
||||||
|
|
||||||
Sender starts with:
|
## Time Bootstrap Guardrail
|
||||||
|
|
||||||
|
On sender boot:
|
||||||
- `g_time_acquired=false`
|
- `g_time_acquired=false`
|
||||||
- no real sampling/batching
|
- no normal sampling/transmit yet
|
||||||
- periodic `SYNC_REQUEST` every `SYNC_REQUEST_INTERVAL_MS` (default `15000ms`)
|
- sync request every `SYNC_REQUEST_INTERVAL_MS` (15s)
|
||||||
|
|
||||||
Sender only accepts time from `ACK_DOWN` if:
|
Only after valid ACK time is received:
|
||||||
- `time_valid == 1`
|
|
||||||
- `epoch_utc >= 2026-02-01 00:00:00 UTC` (`MIN_ACCEPTED_EPOCH_UTC = 1769904000`)
|
|
||||||
|
|
||||||
Only then:
|
|
||||||
- system time is set
|
- system time is set
|
||||||
- `g_time_acquired=true`
|
- normal 1 Hz sampling and periodic LoRa batch transmit start
|
||||||
- normal 1 Hz sampling + batch transmit starts
|
|
||||||
|
|
||||||
This guarantees no pre-`2026-02-01` epoch reaches MQTT or SD/DB paths.
|
This blocks pre-threshold timestamps from MQTT/SD paths.
|
||||||
|
|
||||||
## Receiver behavior
|
## Sender Meter Path
|
||||||
|
|
||||||
On `BATCH_UP`:
|
Implemented in `src/meter_driver.cpp` + sender loop in `src/main.cpp`:
|
||||||
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.
|
|
||||||
|
|
||||||
## Sender/Receiver debug logs (`SERIAL_DEBUG_MODE`)
|
- UART: `Serial2`, RX pin `GPIO34` (`PIN_METER_RX`), `9600 7E1`
|
||||||
|
- Frame detection: starts at `'/'`, ends at `'!'`, timeout protection included
|
||||||
|
- Parsed OBIS values:
|
||||||
|
- `1-0:1.8.0` (total energy)
|
||||||
|
- `1-0:16.7.0` (total power)
|
||||||
|
- `1-0:36.7.0`, `56.7.0`, `76.7.0` (phase powers)
|
||||||
|
- `1-0:1.8.0*Wh` is automatically scaled to kWh
|
||||||
|
|
||||||
Sender:
|
Sender samples every second and transmits batches every 30 seconds.
|
||||||
- `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`
|
|
||||||
|
|
||||||
Receiver:
|
## Receiver Behavior
|
||||||
- `ack: tx batch_id=%u time_valid=%u epoch=%lu samples=%u`
|
|
||||||
|
|
||||||
## Removed hardware dependency
|
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 samples, log to SD, update web UI, publish MQTT.
|
||||||
|
|
||||||
DS3231 RTC support was removed:
|
## MQTT Topics and Payloads
|
||||||
- no RTC files
|
|
||||||
- no RTC init/load/set logic
|
|
||||||
- no `ENABLE_DS3231` flow
|
|
||||||
|
|
||||||
## Build
|
State topic:
|
||||||
|
- `smartmeter/<device_id>/state`
|
||||||
|
|
||||||
|
Fault topic (retained):
|
||||||
|
- `smartmeter/<device_id>/faults`
|
||||||
|
|
||||||
|
State JSON fields (`src/json_codec.cpp`):
|
||||||
|
- `id`, `ts`, `e_kwh`
|
||||||
|
- `p_w`, `p1_w`, `p2_w`, `p3_w`
|
||||||
|
- `bat_v`, `bat_pct`
|
||||||
|
- optional link fields: `rssi`, `snr`
|
||||||
|
- fault/reject fields: `err_last`, `rx_reject`, `rx_reject_text` (+ non-zero counters)
|
||||||
|
|
||||||
|
Home Assistant discovery is enabled (`ENABLE_HA_DISCOVERY=true`) and publishes config topics under:
|
||||||
|
- `homeassistant/sensor/<device_id>/<key>/config`
|
||||||
|
|
||||||
|
## Web UI, Wi-Fi, Storage
|
||||||
|
|
||||||
|
- Wi-Fi/MQTT/NTP/web-auth config persists in Preferences (`wifi_manager`).
|
||||||
|
- AP fallback SSID prefix: `DD3-Bridge-`.
|
||||||
|
- Default web credentials: `admin/admin`.
|
||||||
|
- SD logging enabled (`ENABLE_SD_LOGGING=true`).
|
||||||
|
|
||||||
|
## Build Environments
|
||||||
|
|
||||||
|
From `platformio.ini`:
|
||||||
|
|
||||||
|
- `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
|
```bash
|
||||||
pio run -e lilygo-t3-v1-6-1
|
~/.platformio/penv/bin/pio run -e lilygo-t3-v1-6-1
|
||||||
pio run -e lilygo-t3-v1-6-1-test
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Test Mode
|
||||||
|
|
||||||
|
`ENABLE_TEST_MODE` replaces normal sender/receiver loops with dedicated test loops (`src/test_mode.cpp`).
|
||||||
|
It sends/receives JSON test frames and publishes to `smartmeter/<device_id>/test`.
|
||||||
|
|||||||
Reference in New Issue
Block a user