docs: LNA A/B result (41 dB), timing instrumentation, README; close open questions
This commit is contained in:
@@ -0,0 +1,118 @@
|
||||
# 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](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
|
||||
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
|
||||
|
||||
```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`).
|
||||
|
||||
Serial console (scriptable, JSON output):
|
||||
|
||||
```bash
|
||||
./result-py/bin/python3 hil/dut_cmd.py <port> --listen 5 status stats
|
||||
# status | stats | clear_stats | radio_status | radio_reset | probe
|
||||
# test_tx | test_burst | reboot
|
||||
# set repeat_delay_ms N | set tx_power N | set repeat_enabled 0|1
|
||||
# set verbose 0|1 | set fem_rx_csd 0|1 | set pa_low 0|1
|
||||
# set test_lfield N | set whitelist ID[,ID...] | set whitelist clear
|
||||
```
|
||||
|
||||
## 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](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)
|
||||
- **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](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
|
||||
|
||||
- [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
|
||||
Reference in New Issue
Block a user