C3MA/DD3-LoRa-Bridge-MultiSender
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite README for current multi-meter behavior

Browse Source
This commit is contained in:
acidburns
2026-02-04 19:03:43 +01:00
parent c62f07bf44
commit 31a3eea5dd
1 changed files with 90 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
README.md
View File

@@ -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/<device_id>/state`
## Receiver behavior
Fault topic (retained):
- `smartmeter/<device_id>/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/<device_id>/test`.