Files
heltec-repeater/README.md
T

5.0 KiB

Wireless M-Bus C1 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.

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

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

Serial console (scriptable, JSON output):

./result-py/bin/python3 hil/dut_cmd.py <port> --listen 5 status stats
# full command list: 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 events RF-confirmed in IQ 5 / 5 in the IQ window (100 %)
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
  • Repeats are bit-exact: 63/63 logged TX payloads equalled the received raw frame plus C-mode bytes.
  • 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);
  • 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).

Closing the remaining gap needs physical antenna separation or an inline attenuator, which is not scriptable from the host.

Documentation