Document repeater validation and operating limits
This commit is contained in:
@@ -1,12 +1,14 @@
|
||||
# Wireless M-Bus C1 Repeater — Heltec WiFi LoRa 32 V4.3 (RF feasibility experiment)
|
||||
# Wireless M-Bus C1/T1 Repeater — Heltec WiFi LoRa 32 V4.3 (RF feasibility experiment)
|
||||
|
||||
Experimental firmware and hardware-in-the-loop test rig answering one
|
||||
question: **can the SX1262 + KCT8103L front-end on the Heltec V4.3 serve as
|
||||
the basis for a Wireless M-Bus gateway/repeater?**
|
||||
|
||||
Short answer: yes for RX and TX at the PHY level. It receives real C1
|
||||
meter telegrams, retransmits them bit-exact after a configurable delay, and
|
||||
returns to RX reliably. Quantitative limits and caveats are below.
|
||||
Short answer: yes for RX and TX at the PHY level, in both C1 and T1.
|
||||
It receives C1/T1 meter telegrams and retransmits eligible OMS uplinks after
|
||||
a configurable delay, setting the standard hop bit and repairing the CRC
|
||||
without decrypting the payload. T-mode frames are decoded (3-of-6 in software)
|
||||
and re-aired in their native mode. Quantitative limits and caveats are below.
|
||||
|
||||
This is **not** a standards-compliant repeater. See
|
||||
[docs/STANDARDS_GAPS.md](docs/STANDARDS_GAPS.md).
|
||||
@@ -26,13 +28,28 @@ flake.nix ESP-IDF + rtl-sdr + rtl-wmbus + wmbusmeters + python env
|
||||
|
||||
## Quick start
|
||||
|
||||
### Flash firmware (Heltec only)
|
||||
|
||||
Connect the Heltec over USB and run from the repository root:
|
||||
|
||||
```bash
|
||||
nix develop --command ./tools/flash.sh test
|
||||
```
|
||||
|
||||
This builds the current local source and automatically discovers and flashes
|
||||
the Heltec; no SDR is required. Use `debug` instead of `test` for verbose
|
||||
diagnostics. Discovery refuses missing or ambiguous devices. If flashing
|
||||
fails, the script rediscovers the USB port and retries once.
|
||||
|
||||
### Hardware-in-the-loop test (Heltec + SDR)
|
||||
|
||||
```bash
|
||||
nix build .#hil-python -o result-py # once
|
||||
nix develop --command ./hil/run.sh --duration 1200
|
||||
```
|
||||
|
||||
Exit code 0 = PASS. Artifacts land in `captures/<timestamp>-hil/`
|
||||
(`report.txt`, `report.json`, `serial.log`, `rtlwmbus.log`, `iq_proof.txt`).
|
||||
(`report.txt`, `report.json`, `serial.log`, `rtlwmbus.log`, `rf_proof.json`).
|
||||
|
||||
Serial console (scriptable, JSON output):
|
||||
|
||||
@@ -41,6 +58,59 @@ Serial console (scriptable, JSON output):
|
||||
# full command list: docs/TESTING.md
|
||||
```
|
||||
|
||||
## Phone dashboard (2026-09-09)
|
||||
|
||||
Short-press PRG to the OLED **WLAN-DIAGNOSE** page, then hold ~1.5 s to
|
||||
enable the password-protected access point. The OLED shows the SSID,
|
||||
password and `http://192.168.4.1`. The next page displays a Wi-Fi join QR
|
||||
code; scan it with a phone, then open the address. The 64-pixel-high OLED
|
||||
requires a small QR: text credentials remain available if the camera
|
||||
cannot focus. Choose **stay connected** if the phone warns about no internet.
|
||||
No app, router, internet connection or captive portal is required.
|
||||
The OLED and browser UI are in German. Tap a **?** beside a term for a
|
||||
short beginner-friendly explanation; no mouse hover is required.
|
||||
The latest signals come first; **Diagnose: Summen und Funkstatus** and
|
||||
**Optional: eigene Namen für Zähler** expand only when needed. Help panels
|
||||
close with **Schließen**, the same **?**, an outside tap or Escape. They
|
||||
remain open while the history refreshes.
|
||||
|
||||
- Wi-Fi is **off after every reboot**. Hold on either Wi-Fi page to disable
|
||||
it. OLED blanking does not stop Wi-Fi. A random per-device password is
|
||||
generated once and retained in NVS; it is not printed to serial.
|
||||
- The dashboard shows 256 recent final reception/repeat outcomes,
|
||||
CRC and decode rejections, deliberate policy skips, TX errors, RSSI,
|
||||
C1/T1 mode, timing, radio health and rolling-hour duty usage. Synthetic
|
||||
test/beacon transmissions are identified separately.
|
||||
- **TX completed means the radio reported completion, not downstream
|
||||
delivery.** Frames never detected by the Heltec cannot appear in history.
|
||||
Dashboard counters cover the current boot and are unaffected by
|
||||
`clear_stats`; history rolls off in RAM and is lost on reboot.
|
||||
- Import an optional two-column `oms_id,label` CSV, or download a template
|
||||
and export observed IDs. IDs remain eight-character strings, including
|
||||
leading zeros. Labels stay only in the browser tab's memory; refresh
|
||||
clears them. They are never uploaded or saved.
|
||||
- Manufacturer names and device types are interpreted in offline JavaScript
|
||||
from the link-layer header. Names use a bundled DLMS FLAG registry.
|
||||
This is not meter-model/driver detection or encrypted-reading decoding.
|
||||
Corrupt identities are untrusted; ambiguous IDs retain full raw identity
|
||||
details. Labels never conceal the original ID.
|
||||
- **Einstellungen am Heltec-Gerät ändern** exposes all ten existing settings:
|
||||
forwarding, delay, duty budget, TX power, whitelist, beacon interval,
|
||||
synthetic L-field, verbose serial output, FEM-CSD and preamble detection.
|
||||
Expert controls are collapsed. Every field requires its own **Übernehmen**;
|
||||
loading values never silently discards another unsent draft.
|
||||
- Only delay and duty budget persist across reboots. A revision check rejects
|
||||
stale writes; compare the current device value before explicitly resubmitting.
|
||||
Accepted settings are copied by the radio task at a processing boundary.
|
||||
TX-power/preamble changes can briefly interrupt reception for reinitialization.
|
||||
- Disabling the duty guard or raising it above 1000 ppm requires confirmation,
|
||||
not a new permission to exceed regulatory limits. **Heltec-WLAN ausschalten**
|
||||
also requires confirmation; reconnecting afterward requires the OLED.
|
||||
Anyone with access to the WPA2 AP can change settings. The same-origin/CSRF
|
||||
checks prevent cross-site browser writes, not access by other joined clients.
|
||||
|
||||
Details and verification limits: [docs/TESTING.md](docs/TESTING.md).
|
||||
|
||||
## Results (measured, not inferred)
|
||||
|
||||
Representative 1200 s run, `captures/2026-09-01T10-34-24-hil`:
|
||||
@@ -51,7 +121,7 @@ Representative 1200 s run, `captures/2026-09-01T10-34-24-hil`:
|
||||
| SDR-classified originals | 129 (44 meters) |
|
||||
| Heltec matched SDR originals | 47 (36.4 %) |
|
||||
| Heltec TX attempts / success | 72 / 72 (100 %) |
|
||||
| TX events RF-confirmed in IQ | 5 / 5 in the IQ window (100 %) |
|
||||
| TX RF confirmation | withdrawn for this run: measured with the borrow-prone aligner (see caveats) |
|
||||
| Firmware repeat delay (set 200 ms) | 200.001 ms min/median, 200.008 ms max |
|
||||
| Radio recoveries / MCU resets | 0 / 0 |
|
||||
|
||||
@@ -64,8 +134,10 @@ Key hardware findings:
|
||||
and drops visible meters from 18 to 1. No overload penalty from maximum
|
||||
front-end gain at this site.
|
||||
[docs/RF_FRONTEND_TESTS.md](docs/RF_FRONTEND_TESTS.md)
|
||||
- **Repeats are bit-exact**: 63/63 logged TX payloads equalled the received
|
||||
raw frame plus C-mode bytes.
|
||||
- **Historical bit-exact baseline**: 63/63 logged TX payloads equalled the
|
||||
received raw frame plus C-mode bytes. Since 2026-09-09, received repeats
|
||||
intentionally differ only in the OMS hop bit and affected CRC; see
|
||||
[implementation notes](docs/STANDARDS_GAPS.md#oms-hop-marking-2026-09-09).
|
||||
- **RX deaf time is ~225.7 ms** per repeat at a 200 ms delay, including a
|
||||
12.2 ms fixed-capture tail imposed by the SX1262 packet engine.
|
||||
[docs/TIMING.md](docs/TIMING.md)
|
||||
@@ -93,12 +165,17 @@ rtl-wmbus receives our repeat with 1-2 byte errors and fails CRC. Repeats
|
||||
are therefore verified two ways that are immune to this:
|
||||
|
||||
- synthetic C1 bursts prove the framing is decodable as C1 (`verify_tx.py`);
|
||||
- firmware TX timestamps are aligned to bursts in raw IQ to prove real
|
||||
repeats radiate with the right timing and airtime
|
||||
(`verify_repeats_iq.py`).
|
||||
- `hil/meter_anchored.py` fits the serial<->IQ clock on strong meter
|
||||
receptions only (a TX-fitted clock can lock at -repeat_delay and match
|
||||
every repeat to its own original -- that bug produced withdrawn results),
|
||||
then requires event-correlated FSK spectral excess against nearby non-TX
|
||||
control windows before reporting `rf_state` strong/weak.
|
||||
|
||||
Closing the remaining gap needs physical antenna separation or an inline
|
||||
attenuator, which is not scriptable from the host.
|
||||
An earlier RF-alignment tool (`verify_repeats_iq.py`) had exactly that
|
||||
clock-borrowing flaw and was removed; historical "N/N TX confirmed in IQ"
|
||||
numbers from it are withdrawn (docs/FINDINGS.md). Closing the remaining
|
||||
decode gap needs physical antenna separation or an inline attenuator,
|
||||
which is not scriptable from the host.
|
||||
|
||||
## Documentation
|
||||
|
||||
@@ -113,5 +190,5 @@ attenuator, which is not scriptable from the host.
|
||||
- [TESTING.md](docs/TESTING.md) — how to run things, known pitfalls
|
||||
- [DEVBOARD_REQUIREMENTS.md](docs/DEVBOARD_REQUIREMENTS.md) +
|
||||
[devboard_signals.csv](docs/devboard_signals.csv) — future PCB needs
|
||||
- [FUTURE_UI.md](docs/FUTURE_UI.md) — design note: OLED + button for local
|
||||
feedback (not implemented; display is untouched by this firmware)
|
||||
- [FUTURE_UI.md](docs/FUTURE_UI.md) — OLED + button local UI: design,
|
||||
constraints, and implementation notes (implemented in firmware/main/ui.c)
|
||||
|
||||
Reference in New Issue
Block a user