docs: withdraw degraded-observer match rate, record observer drift and IQ TX proof

This commit is contained in:
Lars Nolden
2026-09-01 09:35:05 +02:00
parent fdc31d8227
commit 9a65fa2040
2 changed files with 120 additions and 59 deletions
+26 -8
View File
@@ -52,18 +52,36 @@
## CONFIRMED (measurement methodology) ## CONFIRMED (measurement methodology)
- Heltec RX is competitive with the Nooelec observer on identical traffic: - WITHDRAWN: an earlier entry claimed "Heltec matched 124 of 127 SDR
124 of 127 SDR-classified originals matched byte-exactly in a 30 min run originals (97 %)". That measurement was taken while the dongle was in its
(97 % across 32 meters). degraded state, so the SDR decoded few originals and the Heltec matched
nearly all of them. With the observer state recorded, the honest figure is
58.5 % of SDR originals matched (600 s run, observer "degraded"), with
each receiver also decoding meters the other missed. See
docs/RF_FRONTEND_TESTS.md.
- Repeat payloads are byte-exact: 63/63 logged `tx_payload` values equalled - Repeat payloads are byte-exact: 63/63 logged `tx_payload` values equalled
mode bytes + the received raw frame. No corruption in the RX->TX path. mode bytes + the received raw frame. No corruption in the RX->TX path.
- Our repeats DO radiate. IQ capture shows burst pairs at 54-55 ms spacing - Real repeats are emitted as correct RF: aligning firmware TX timestamps
with 9-10 ms duration (matches 100 kbps x ~100 bytes) - the repeat is to bursts in the same stream's IQ confirmed 48 of 57 TX events (84 %),
real RF, independently observed, even when rtl-wmbus cannot decode it. with alignment error median 1.3 ms (max 3.6 ms) and burst duration within
- The observer, not the repeater, limits repeat decoding: our TX arrives 0.5 ms (median) of the computed airtime. Firmware repeat delay measured
~36 dB stronger than meter traffic and sits at RTL-SDR full scale. 200.0 ms min/median/max against a 200 ms setting.
- Firmware TX reliability over 600 s: tx_attempts 58, tx_success 58,
tx_timeout 0, tx_failures 0, recoveries 0.
- The observer, not the repeater, limits repeat DECODING. In the dongle's
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
1-2 byte errors and fails CRC (observed directly: transmitted
`...78534f4c5458...` decoded as `...78514f4c5448...`, rest bit-exact).
Raising the repeat delay 50 -> 200 ms improved SDR repeat decoding from Raising the repeat delay 50 -> 200 ms improved SDR repeat decoding from
3 % to 30 % (demodulator level-estimate recovery). 3 % to 30 % (demodulator level-estimate recovery).
- The dongle's sensitivity drifts ~17 dB within minutes of streaming, so
captures taken at "the same gain" at different times are NOT comparable.
Meter decodes and our own TX measurements must come from one stream
(`hil/capture_both.sh`).
- `rtl_sdr -g 0` selects AUTOMATIC gain, not 0 dB; lowest real fixed gain
is 0.9 dB. Low fixed gain is not a usable workaround while degraded:
at 0.9 and 7.7 dB nothing decoded at all.
- Synthetic C1 bursts from the Heltec (L = 19/40/60/98) are decoded by - Synthetic C1 bursts from the Heltec (L = 19/40/60/98) are decoded by
rtl-wmbus as valid C1 with correct CRCs, including two airings of the rtl-wmbus as valid C1 with correct CRCs, including two airings of the
same frame 50/100/200 ms apart. TX framing is therefore correct and same frame 50/100/200 ms apart. TX framing is therefore correct and
+94 -51
View File
@@ -1,24 +1,54 @@
# RF Front-End (KCT8103L) Observations # RF Front-End (KCT8103L) Observations
## Important caveat about the observer
The Nooelec dongle used as reference receiver is not a stable instrument on
this bench. Measured with `hil/sdr_health.py`:
```
fresh after replug : mean power @42.1 dB gain ~ +22 dB, spectrum span ~51 dB,
noise tracks gain by ~25 dB -> "full"
after minutes of
continuous streaming: mean power ~ +5 dB, span ~18-21 dB,
noise tracks gain by ~8 dB -> "degraded"
wedged / bypassed : railed ~ +40 dB, span < 10 dB,
noise does not track gain -> "deaf"
```
The drop from "full" to "degraded" is roughly 17 dB of sensitivity and
happens within minutes. Every reported comparison therefore carries the
observer state, and cross-run comparisons at "the same gain" are invalid.
This is why `hil/capture_both.sh` derives meter decodes and our own TX
measurements from a *single* rtl_sdr stream.
An earlier draft of this document claimed a 97 % Heltec-vs-SDR match rate.
That number was taken while the dongle was degraded (it decoded far fewer
originals, so the Heltec matched nearly all of them) and is withdrawn.
## Measured RX performance vs the SDR ## Measured RX performance vs the SDR
The most useful result is not datasheet sensitivity but the head-to-head 600 s run, `captures/2026-09-01T09-22-28-hil`, gain 42.1 dB, observer
comparison against the Nooelec observer on identical real traffic. state "degraded", CSD high (FEM enabled in RX):
30-minute run (`captures/2026-08-31T23-17-47-hil`, gain 42.1 dB,
CSD high / LNA path active):
``` ```
SDR classified originals : 127 SDR classified originals : 41
Heltec RX (CRC ok) : 124 matched Heltec RX candidates : 122 (CRC ok: 56)
per-meter match rate : 97 % (32 meters) matched originals : 24 -> 58.5 % of SDR originals
unique meters seen : 35 (union of both receivers)
``` ```
Per-meter table is in that run's `report.txt`. The Heltec matched the SDR Neither receiver dominates. In the per-meter table of that run:
essentially frame-for-frame, and in earlier runs the Heltec decoded frames - meters where both agree, e.g. 61471660 (6 SDR / 6 Heltec / 6 matched),
from ~50 distinct meters where the SDR decoded far fewer, i.e. the 04774139 (3/3/3), 04769582 (2/2/2);
SX1262 + KCT8103L RX chain is at least competitive with an R820T dongle - meters only the SDR decoded, e.g. 04766714 (3/0), 04766710 (3/0),
plus whip antenna at the same location. 04769365 (2/0), 04766705 (2/0);
- meters only the Heltec decoded, e.g. 20898871 (0/4), 67537334 (0/3),
04767753 (0/3).
So the SX1262 + KCT8103L chain is broadly comparable to an R820T dongle
with a whip antenna at this location, with per-meter differences that are
most likely antenna-pattern and multipath effects rather than a systematic
sensitivity gap.
## RSSI vs CRC success (Heltec, chip-referred RSSI) ## RSSI vs CRC success (Heltec, chip-referred RSSI)
@@ -32,55 +62,59 @@ plus whip antenna at the same location.
| -80..-71 | 0 | 11 | 0 % | | -80..-71 | 0 | 11 | 0 % |
| <= -100 | 0 | 1 | 0 % | | <= -100 | 0 | 1 | 0 % |
Interpretation: with the current configuration the usable working point is Interpretation: the usable working point with the current configuration is
about -65 dBm chip-referred and better. Frames below that are received about -65 dBm chip-referred and better. Below that, frames are still
(sync + length parse succeed) but accumulate bit errors. Most failures are detected (sync matches, length parses) but accumulate bit errors. Failures
long (100-118 byte) Techem frames, consistent with errors accumulating over concentrate in long (100-118 byte) Techem frames, consistent with errors
frame length rather than a hard sensitivity floor. accumulating over frame length rather than a hard sensitivity floor.
Open: how much of this is FEM configuration vs modem parameters (RX Firmware counters from the 600 s run corroborate the shape:
bandwidth 234.3 kHz is generous; a narrower filter may improve SNR). `rx_candidates=178, rx_valid=58, rx_crc_fail=66, rx_not_c1=54`
(`rx_not_c1` are sync matches that are not C-mode: T1 traffic and false
syncs from the deliberately short 8-bit preamble detector).
## LNA / CSD experiment ## LNA / CSD experiment
The firmware exposes `set fem_rx_csd 0|1`, which controls the KCT8103L CSD `set fem_rx_csd 0|1` controls the KCT8103L CSD level while in RX (high =
level while in RX (CSD high = FEM enabled/LNA path, CSD low = FEM disabled). FEM enabled/LNA path, low = FEM disabled). TX always forces CSD high.
TX always forces CSD high. `hil/lna_ab.sh` runs two equal-length RX-only arms and reports frame
counts, CRC success and RSSI distribution per arm.
Status: hook implemented and available; a controlled A/B comparison needs Results: see the "KCT8103L RX front-end A/B" section appended below once a
two runs of equal duration on the same meter population. NOT yet measured run has completed. Do not assume a direction before measuring - meter
- do not claim a result. The RSSI/CRC table above is for CSD high. traffic varies between arms, so only large differences are meaningful.
## Bench dynamic-range limitation (important) ## Bench dynamic-range limitation
Measured with IQ capture (`hil/iq_bursts.py`, `captures/iq/repeat.raw`): Measured on a single stream (`iq_proof.json` of the 600 s run):
``` ```
meter original at the SDR : +8.4 dB over noise floor (IQ std 1.3) our transmissions : median +12.9 dB over noise floor (min 6.2, max 38.5)
our repeat at the SDR : +44.8 dB over noise floor (IQ std 88.6) meter transmissions: median +9.8 dB over noise floor (min 6.0, max 37.2)
clipped ADC samples: 0.006 % of the capture
``` ```
Our transmission arrives ~36 dB stronger than the meter traffic and sits at In the *degraded* observer state the levels overlap and clipping is
the RTL-SDR's full scale (u8 amplitude ~125 of 127). Consequences: negligible. In the *full* state, however, an earlier IQ capture showed our
repeat at +44.8 dB over floor with IQ amplitude at the dongle's full scale
(rms 88.6 of 127) while the meter original sat at +8.4 dB - a ~36 dB gap.
- At tuner gain 42.1 dB the meters decode well but our repeats are driven Consequence: with a fully sensitive dongle, meter originals decode well at
into ADC compression and mostly fail to decode. high gain but our own transmission is driven into compression and
- At tuner gain 20.7 dB our repeats are only marginally compressed but the rtl-wmbus receives it with a few byte errors (CRC fails). Observed
meters drop to ~8 dB SNR and decode poorly. directly - the decoded hex differed from the transmitted frame in 1-2
- No single tuner gain serves both, because the required dynamic range bytes, e.g. transmitted `...78534f4c5458...` received `...78514f4c5448...`,
exceeds what an 8-bit dongle provides in this bench geometry. with the rest of a 113-byte frame bit-exact.
This is exactly the overload situation the task description warns about.
Mitigations applied in firmware: SX1262 at its minimum configured power Mitigations applied in firmware: SX1262 at its minimum configured power
(-9 dBm) and the lowest documented PA table (paDutyCycle 0x01, hpMax 0x00). (-9 dBm) and the lowest documented PA table (paDutyCycle 0x01, hpMax 0x00,
Remaining mitigation is physical (antenna separation / attenuator), which SX1262 datasheet table 13-21). Remaining mitigation is physical (antenna
is not scriptable from this host. separation or an inline attenuator) and is not scriptable from this host.
Consequences for verification methodology - see docs/TESTING.md: Note: `rtl_sdr -g 0` selects *automatic* gain, not 0 dB. The lowest real
1. real-meter originals and Heltec RX match rate are measured at high gain; fixed gain on this tuner is 0.9 dB. At 0.9 and 7.7 dB fixed gain the
2. Heltec TX decodability is proven separately with synthetic C1 bursts degraded dongle decoded nothing at all (neither meters nor our TX), so low
that are not preceded by a weak frame (phase A of `hil/run.sh`); gain is not a usable workaround in that state.
3. RF-level repeat evidence is available from IQ burst-pair timing.
## Repeat-delay dependence of observer decoding ## Repeat-delay dependence of observer decoding
@@ -92,7 +126,16 @@ Same bench, same gain (42.1 dB), only the repeat delay changed:
| 200 ms | 6 / 20 (30 %) | | 200 ms | 6 / 20 (30 %) |
A longer gap gives the rtl-wmbus demodulator time to recover its level A longer gap gives the rtl-wmbus demodulator time to recover its level
estimate after the weak original before the very strong repeat arrives. estimate after the weak original before the much stronger repeat arrives.
The HIL default is therefore 200 ms (still inside the 20-200 ms The HIL default is therefore 200 ms, still inside the 20-200 ms
development range). This is an artefact of the observer, not of the development range. This is an artefact of the observer, not the repeater:
repeater: the firmware's own timing is accurate to a few microseconds. the firmware's own repeat delay measures 200.0 ms min/median/max.
## Verification strategy that follows from all this
1. Meter originals and Heltec RX match rate: rtl-wmbus decodes at high gain.
2. Heltec TX framing is decodable as C1: proven with synthetic bursts that
are not preceded by a weak frame (`hil/verify_tx.py`).
3. Real repeats: proven at RF level from the same stream's IQ by aligning
firmware TX timestamps to observed bursts (`hil/verify_repeats_iq.py`),
which is immune to both compression and observer sensitivity drift.