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.

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:

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)

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, rf_proof.json).

Serial console (scriptable, JSON output):

./result-py/bin/python3 hil/dut_cmd.py <port> --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.

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
  • 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
  • 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.
  • 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

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

S
Description
No description provided
Readme
30 MiB
Languages
C 49.3%
Python 17.9%
JavaScript 16.6%
Shell 7.9%
CSS 3.8%
Other 4.5%