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
|
||||||
+12
-3
@@ -66,8 +66,18 @@
|
|||||||
with alignment error median 1.3 ms (max 3.6 ms) and burst duration within
|
with alignment error median 1.3 ms (max 3.6 ms) and burst duration within
|
||||||
0.5 ms (median) of the computed airtime. Firmware repeat delay measured
|
0.5 ms (median) of the computed airtime. Firmware repeat delay measured
|
||||||
200.0 ms min/median/max against a 200 ms setting.
|
200.0 ms min/median/max against a 200 ms setting.
|
||||||
- Firmware TX reliability over 600 s: tx_attempts 58, tx_success 58,
|
- Firmware TX reliability: 58/58 TX success over 600 s and 72/72 over
|
||||||
tx_timeout 0, tx_failures 0, recoveries 0.
|
1200 s; tx_timeout 0, tx_failures 0, radio recoveries 0, MCU resets 0.
|
||||||
|
- The KCT8103L RX path is essential: holding CSD low in RX costs ~41 dB of
|
||||||
|
chip-referred level and drops the visible meter population from 18 to 1
|
||||||
|
(600 s per arm, docs/RF_FRONTEND_TESTS.md). No evidence of excessive
|
||||||
|
front-end gain hurting at this site.
|
||||||
|
- Repeat-delay accuracy: +1 to +8 us against a 200 ms setting across 72
|
||||||
|
repeats. RX deaf time per repeat ~225.7 ms median, of which 12.2 ms is
|
||||||
|
the fixed-255-byte RX tail and 13.4 ms the TX airtime (docs/TIMING.md).
|
||||||
|
- The SX1262 GFSK engine cannot express wM-Bus length semantics, so RX uses
|
||||||
|
a fixed 255-byte capture; RxDone therefore fires 9.4-17.1 ms after the
|
||||||
|
real end of frame and the firmware reconstructs the true timestamp.
|
||||||
- The observer, not the repeater, limits repeat DECODING. In the dongle's
|
- The observer, not the repeater, limits repeat DECODING. In the dongle's
|
||||||
full-sensitivity state our TX arrives ~36 dB stronger than meter traffic
|
full-sensitivity state our TX arrives ~36 dB stronger than meter traffic
|
||||||
and reaches RTL-SDR full scale; rtl-wmbus then receives our repeat with
|
and reaches RTL-SDR full scale; rtl-wmbus then receives our repeat with
|
||||||
@@ -101,7 +111,6 @@
|
|||||||
|
|
||||||
## NEEDS TESTING
|
## NEEDS TESTING
|
||||||
|
|
||||||
- LNA on/off comparison (`set fem_rx_csd 0|1` hook exists, not yet measured).
|
|
||||||
- Narrower RX bandwidth (156 kHz) vs current 234.3 kHz on weak meters.
|
- Narrower RX bandwidth (156 kHz) vs current 234.3 kHz on weak meters.
|
||||||
- Long-run stability at >=100 and >=500 verified repeat events.
|
- Long-run stability at >=100 and >=500 verified repeat events.
|
||||||
- Early-stop RX (poll GetRxBufferStatus) to cut the ~20 ms deaf tail.
|
- Early-stop RX (poll GetRxBufferStatus) to cut the ~20 ms deaf tail.
|
||||||
|
|||||||
+13
-5
@@ -5,14 +5,22 @@
|
|||||||
drifted meters?
|
drifted meters?
|
||||||
- Preamble detector length: 8 bits chosen for sensitivity; false-sync rate
|
- Preamble detector length: 8 bits chosen for sensitivity; false-sync rate
|
||||||
in the field? (false syncs cost ~20 ms deaf time each at fixed-255 RX).
|
in the field? (false syncs cost ~20 ms deaf time each at fixed-255 RX).
|
||||||
- Does the KCT8103L LNA help or hurt with strong 868 MHz interferers?
|
- CLOSED: Does the KCT8103L LNA help or hurt with strong 868 MHz
|
||||||
(see planned docs/RF_FRONTEND_TESTS.md)
|
interferers? -> It helps decisively. CSD low costs ~41 dB and reduces
|
||||||
- RX dead time during retransmit: measured distribution?
|
visible meters from 18 to 1; no overload degradation observed
|
||||||
|
(docs/RF_FRONTEND_TESTS.md).
|
||||||
|
- CLOSED: RX dead time during retransmit -> ~225.7 ms median at a 200 ms
|
||||||
|
repeat delay, of which 12.2 ms is the fixed-255 RX tail and 13.4 ms the
|
||||||
|
TX airtime (docs/TIMING.md). Early-stop RX would cut the tail.
|
||||||
- Can the SX1262 re-arm RX fast enough to catch a meter's immediate
|
- Can the SX1262 re-arm RX fast enough to catch a meter's immediate
|
||||||
follow-up telegram after our TX?
|
follow-up telegram after our TX?
|
||||||
- Exact production repeater framing/hop requirements (EN 13757-5).
|
- Exact production repeater framing/hop requirements (EN 13757-5).
|
||||||
- Regulatory duty-cycle budget for a production repeater at 868.95 MHz.
|
- Regulatory duty-cycle budget for a production repeater at 868.95 MHz.
|
||||||
- Modulation shaping for TX: none vs GFSK BT=0.5 — which does rtl-wmbus /
|
- Modulation shaping for TX: none vs GFSK BT=0.5 — which does rtl-wmbus /
|
||||||
real receivers prefer? (TX currently unshaped 2-FSK.)
|
real receivers prefer? (TX currently unshaped 2-FSK.)
|
||||||
- Why did the R820T PLL wedge? (usbreset workaround in place; root cause
|
- Why does the R820T degrade and eventually die during streaming? Three
|
||||||
unknown, suspected rtl_test direct-sampling probe.)
|
failure modes are characterised in docs/HARDWARE.md; `usbreset` recovers
|
||||||
|
the first two, the third needs a physical replug. Root cause unknown
|
||||||
|
(thermal suspected). The `rtl_test -t` theory was DISPROVEN.
|
||||||
|
- Can the SX1262 RX be stopped early (poll GetRxBufferStatus after
|
||||||
|
SyncWordValid) to remove the ~12 ms fixed-capture tail?
|
||||||
|
|||||||
@@ -73,16 +73,44 @@ Firmware counters from the 600 s run corroborate the shape:
|
|||||||
(`rx_not_c1` are sync matches that are not C-mode: T1 traffic and false
|
(`rx_not_c1` are sync matches that are not C-mode: T1 traffic and false
|
||||||
syncs from the deliberately short 8-bit preamble detector).
|
syncs from the deliberately short 8-bit preamble detector).
|
||||||
|
|
||||||
## LNA / CSD experiment
|
## LNA / CSD experiment - MEASURED
|
||||||
|
|
||||||
`set fem_rx_csd 0|1` controls the KCT8103L CSD level while in RX (high =
|
`set fem_rx_csd 0|1` controls the KCT8103L CSD level while in RX (high =
|
||||||
FEM enabled/LNA path, low = FEM disabled). TX always forces CSD high.
|
FEM enabled/LNA path, low = FEM disabled). TX always forces CSD high.
|
||||||
`hil/lna_ab.sh` runs two equal-length RX-only arms and reports frame
|
`hil/lna_ab.sh` runs two equal-length RX-only arms (retransmission
|
||||||
counts, CRC success and RSSI distribution per arm.
|
disabled, so the receiver is measured in isolation).
|
||||||
|
|
||||||
Results: see the "KCT8103L RX front-end A/B" section appended below once a
|
Result, 600 s per arm, `captures/2026-09-01T10-55-00-lna-ab`:
|
||||||
run has completed. Do not assume a direction before measuring - meter
|
|
||||||
traffic varies between arms, so only large differences are meaningful.
|
| | CSD high (FEM enabled) | CSD low (FEM disabled) |
|
||||||
|
|---|---|---|
|
||||||
|
| candidate frames | 108 | 5 |
|
||||||
|
| CRC-valid frames | 35 | 5 |
|
||||||
|
| unique meters | 18 | 1 |
|
||||||
|
| median RSSI (all) | -61 dBm | -102 dBm |
|
||||||
|
| median RSSI (CRC ok) | -53 dBm | -102 dBm |
|
||||||
|
| strongest RSSI | -45 dBm | -101 dBm |
|
||||||
|
| firmware counters | candidates=190, valid=34, crc_fail=73, not_c1=83 | candidates=8, valid=5, crc_fail=0, not_c1=3 |
|
||||||
|
|
||||||
|
**Conclusion: the KCT8103L RX path is essential.** Disabling it costs about
|
||||||
|
41 dB of chip-referred signal level and cuts the visible meter population
|
||||||
|
from 18 to 1. CSD must be held high in RX.
|
||||||
|
|
||||||
|
Two secondary observations:
|
||||||
|
|
||||||
|
- With CSD low the few frames that still arrive decode with 100 % CRC
|
||||||
|
success at -102 dBm. Signal and noise both drop with the FEM disabled, so
|
||||||
|
SNR survives for the single strongest local meter; chip-referred RSSI is
|
||||||
|
therefore not comparable across arms as an SNR measure.
|
||||||
|
- No sign of the "too much gain hurts" failure mode at this site: the
|
||||||
|
high-gain arm saw strictly more meters with no CRC collapse on strong
|
||||||
|
frames. Excessive front-end gain was a plausible risk given strong
|
||||||
|
868 MHz neighbours, but it is not what limits this bench.
|
||||||
|
|
||||||
|
Cost of the sensitive configuration: with CSD high, 83 of 190 sync matches
|
||||||
|
(44 %) were not C-mode (`rx_not_c1`) - T1 traffic plus false syncs from the
|
||||||
|
deliberately short 8-bit preamble detector. Each false sync consumes one
|
||||||
|
fixed-255-byte RX window (~12 ms, docs/TIMING.md).
|
||||||
|
|
||||||
## Bench dynamic-range limitation
|
## Bench dynamic-range limitation
|
||||||
|
|
||||||
|
|||||||
@@ -55,3 +55,20 @@ set verbose 0|1 | set whitelist ID[,ID...] | set whitelist clear | reboot
|
|||||||
apply timeout to `rtl_sdr` itself.
|
apply timeout to `rtl_sdr` itself.
|
||||||
- ESP32-S3 USB re-enumerates between app CDC and ROM bootloader; flash
|
- ESP32-S3 USB re-enumerates between app CDC and ROM bootloader; flash
|
||||||
scripts rediscover the port on failure.
|
scripts rediscover the port on failure.
|
||||||
|
|
||||||
|
## LNA / FEM A/B experiment (no SDR needed)
|
||||||
|
|
||||||
|
```
|
||||||
|
nix develop --command ./hil/lna_ab.sh 600 # seconds per arm
|
||||||
|
```
|
||||||
|
|
||||||
|
Runs two RX-only arms (CSD high vs CSD low) with retransmission disabled
|
||||||
|
and reports frame counts, CRC success, unique meters and RSSI per arm.
|
||||||
|
Result: docs/RF_FRONTEND_TESTS.md.
|
||||||
|
|
||||||
|
## Interpreting observer state
|
||||||
|
|
||||||
|
Every run records `SDR sensitivity: full | degraded` from
|
||||||
|
`hil/sdr_health.py`. Treat cross-run comparisons as invalid unless both
|
||||||
|
runs report the same state -- this dongle loses ~17 dB within minutes of
|
||||||
|
streaming (docs/HARDWARE.md).
|
||||||
|
|||||||
@@ -0,0 +1,63 @@
|
|||||||
|
# Timing Instrumentation
|
||||||
|
|
||||||
|
All values measured on the DUT with `esp_timer_get_time()` (monotonic
|
||||||
|
microseconds), from `captures/2026-09-01T10-34-24-hil` (1200 s run, 72
|
||||||
|
repeats, 214 RX candidates, repeat delay set to 200 ms).
|
||||||
|
|
||||||
|
## Measured
|
||||||
|
|
||||||
|
| Quantity | min | median | max | n |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| RxDone -> reconstructed end of frame ("deaf tail") | 9 360 us | 12 240 us | 17 120 us | 214 |
|
||||||
|
| TX airtime (SetTx to TxDone) | 10 421 us | 13 422 us | 14 560 us | 72 |
|
||||||
|
| Programmed repeat delay (frame end -> TX start) | 200 001 us | 200 001 us | 200 008 us | 72 |
|
||||||
|
| Repeated frame length (over-the-air bytes) | 63 | 100 | 113 | 72 |
|
||||||
|
|
||||||
|
Independent confirmation from the SDR side (raw IQ, same run): observed
|
||||||
|
burst duration differs from the computed airtime by 0.2-1.5 ms
|
||||||
|
(median 1.2 ms), and firmware TX events align to observed RF within
|
||||||
|
0-3.1 ms (median 2.4 ms).
|
||||||
|
|
||||||
|
## Derived
|
||||||
|
|
||||||
|
```
|
||||||
|
repeat delay accuracy : +1 us to +8 us against a 200 ms setting
|
||||||
|
(jitter well under 10 us)
|
||||||
|
RX deaf time per repeat : ~225.7 ms median
|
||||||
|
= 12.2 ms deaf tail
|
||||||
|
+ 200.0 ms programmed delay
|
||||||
|
+ 13.4 ms TX airtime
|
||||||
|
```
|
||||||
|
|
||||||
|
The programmed delay dominates by design; it exists to make SDR
|
||||||
|
correlation possible during development.
|
||||||
|
|
||||||
|
## The 12 ms deaf tail
|
||||||
|
|
||||||
|
The SX1262's GFSK packet engine cannot express Wireless M-Bus length
|
||||||
|
semantics (format A carries per-block CRCs that the L-field excludes), so
|
||||||
|
RX uses a fixed 255-byte capture and the firmware truncates in software
|
||||||
|
using the L-field formulas. Consequences:
|
||||||
|
|
||||||
|
- RxDone fires `(255 - frame_bytes) * 80 us` after the frame really ended;
|
||||||
|
the firmware subtracts this to recover the true end-of-frame timestamp,
|
||||||
|
which is what the repeat delay is measured from.
|
||||||
|
- During that tail the receiver is not re-armed for sync search, costing
|
||||||
|
9.4-17.1 ms of receive availability per detected frame -- including for
|
||||||
|
false syncs from the deliberately short 8-bit preamble detector.
|
||||||
|
|
||||||
|
Optimisation candidate (not implemented): poll `GetRxBufferStatus` after
|
||||||
|
`SyncWordValid`, read the L-field as soon as it lands, then stop RX early
|
||||||
|
once the computed frame length has been received. That would cut the tail
|
||||||
|
to roughly the frame's own airtime and materially raise the duty cycle of
|
||||||
|
a production repeater.
|
||||||
|
|
||||||
|
## Relevance to the production gateway
|
||||||
|
|
||||||
|
- A production repeater using randomized 5-25 s delays will have a very
|
||||||
|
different deaf-time profile; the 200 ms figure here is a development
|
||||||
|
artefact, not a design target (see docs/STANDARDS_GAPS.md).
|
||||||
|
- The fixed-255 tail is an SX1262 packet-engine limitation, so it applies
|
||||||
|
to any SX126x-based design. Budget for it, or implement early-stop RX.
|
||||||
|
- Repeat-delay accuracy of a few microseconds shows the ESP32-S3 side has
|
||||||
|
ample timing margin; timing precision will not be the constraint.
|
||||||
Reference in New Issue
Block a user