# 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, 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). ## What is here ``` firmware/ ESP-IDF app: SX1262 GFSK driver, wM-Bus C1 RX/TX, repeater state machine, recovery ladder, JSON telemetry firmware/test/ host-side frame-layer tests (run under AddressSanitizer) hil/ hardware-in-the-loop harness (run.sh is the entry point) tools/ device discovery, flashing, reset docs/ hardware evidence, RF config, findings, timing, gaps captures/ per-run artifacts (logs, reports, IQ) 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/-hil/` (`report.txt`, `report.json`, `serial.log`, `rtlwmbus.log`, `rf_proof.json`). Serial console (scriptable, JSON output): ```bash ./result-py/bin/python3 hil/dut_cmd.py --listen 5 status stats # 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`: | Metric | Value | |---|---| | Heltec RX candidates / CRC-valid | 214 / 72 | | SDR-classified originals | 129 (44 meters) | | Heltec matched SDR originals | 47 (36.4 %) | | Heltec TX attempts / success | 72 / 72 (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 | Key hardware findings: - **Pin mapping and FEM control verified** on real hardware — SX1262 on GPIO8-14, KCT8103L on GPIO7/2/5 with CPS driven by DIO2, TCXO on DIO3 at 1.8 V. [docs/HARDWARE.md](docs/HARDWARE.md) - **The KCT8103L RX path is essential**: disabling it (CSD low) costs ~41 dB 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) - **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) ## Measurement caveats — read before trusting any number The RTL-SDR observer is the weakest instrument in this setup and the harness is built around that: 1. Its sensitivity drifts ~17 dB within minutes of streaming, so captures at "the same gain" minutes apart are not comparable. 2. Its tuner dies mid-stream (`i2c wr failed`) without `rtl_sdr` exiting — a naive long capture silently returns "no traffic". The harness uses bounded segments with reset-and-resume. 3. It can de-enumerate entirely, needing a physical replug. `hil/sdr_health.py` gates every run and every report states the observer state (`full` / `degraded`), so an empty capture is always attributable. An earlier claimed "97 % RX match rate" was withdrawn after it turned out to have been measured against a degraded observer. Our transmission also arrives far stronger than meter traffic (up to ~36 dB at full observer sensitivity), which pushes the dongle into compression so 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`); - `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. 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 - [HARDWARE.md](docs/HARDWARE.md) — board, pin mapping, FEM, observer faults - [RF_CONFIG.md](docs/RF_CONFIG.md) — C1 PHY and SX1262 register settings - [RF_FRONTEND_TESTS.md](docs/RF_FRONTEND_TESTS.md) — RX comparisons, LNA A/B - [TIMING.md](docs/TIMING.md) — latency and deaf-time instrumentation - [SDR_BASELINE.md](docs/SDR_BASELINE.md) — Phase 0 observer baseline - [FINDINGS.md](docs/FINDINGS.md) — confirmed / disproven / needs testing - [OPEN_QUESTIONS.md](docs/OPEN_QUESTIONS.md) — open and closed questions - [STANDARDS_GAPS.md](docs/STANDARDS_GAPS.md) — deviations from EN 13757/OMS - [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) — OLED + button local UI: design, constraints, and implementation notes (implemented in firmware/main/ui.c)