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
+94 -51
View File
@@ -1,24 +1,54 @@
# 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
The most useful result is not datasheet sensitivity but the head-to-head
comparison against the Nooelec observer on identical real traffic.
30-minute run (`captures/2026-08-31T23-17-47-hil`, gain 42.1 dB,
CSD high / LNA path active):
600 s run, `captures/2026-09-01T09-22-28-hil`, gain 42.1 dB, observer
state "degraded", CSD high (FEM enabled in RX):
```
SDR classified originals : 127
Heltec RX (CRC ok) : 124 matched
per-meter match rate : 97 % (32 meters)
SDR classified originals : 41
Heltec RX candidates : 122 (CRC ok: 56)
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
essentially frame-for-frame, and in earlier runs the Heltec decoded frames
from ~50 distinct meters where the SDR decoded far fewer, i.e. the
SX1262 + KCT8103L RX chain is at least competitive with an R820T dongle
plus whip antenna at the same location.
Neither receiver dominates. In the per-meter table of that run:
- meters where both agree, e.g. 61471660 (6 SDR / 6 Heltec / 6 matched),
04774139 (3/3/3), 04769582 (2/2/2);
- meters only the SDR decoded, e.g. 04766714 (3/0), 04766710 (3/0),
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)
@@ -32,55 +62,59 @@ plus whip antenna at the same location.
| -80..-71 | 0 | 11 | 0 % |
| <= -100 | 0 | 1 | 0 % |
Interpretation: with the current configuration the usable working point is
about -65 dBm chip-referred and better. Frames below that are received
(sync + length parse succeed) but accumulate bit errors. Most failures are
long (100-118 byte) Techem frames, consistent with errors accumulating over
frame length rather than a hard sensitivity floor.
Interpretation: the usable working point with the current configuration is
about -65 dBm chip-referred and better. Below that, frames are still
detected (sync matches, length parses) but accumulate bit errors. Failures
concentrate in long (100-118 byte) Techem frames, consistent with errors
accumulating over frame length rather than a hard sensitivity floor.
Open: how much of this is FEM configuration vs modem parameters (RX
bandwidth 234.3 kHz is generous; a narrower filter may improve SNR).
Firmware counters from the 600 s run corroborate the shape:
`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
The firmware exposes `set fem_rx_csd 0|1`, which controls the KCT8103L CSD
level while in RX (CSD high = FEM enabled/LNA path, CSD low = FEM disabled).
TX always forces CSD 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.
`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
two runs of equal duration on the same meter population. NOT yet measured
- do not claim a result. The RSSI/CRC table above is for CSD high.
Results: see the "KCT8103L RX front-end A/B" section appended below once a
run has completed. Do not assume a direction before measuring - meter
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 repeat at the SDR : +44.8 dB over noise floor (IQ std 88.6)
our transmissions : median +12.9 dB over noise floor (min 6.2, max 38.5)
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
the RTL-SDR's full scale (u8 amplitude ~125 of 127). Consequences:
In the *degraded* observer state the levels overlap and clipping is
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
into ADC compression and mostly fail to decode.
- At tuner gain 20.7 dB our repeats are only marginally compressed but the
meters drop to ~8 dB SNR and decode poorly.
- No single tuner gain serves both, because the required dynamic range
exceeds what an 8-bit dongle provides in this bench geometry.
Consequence: with a fully sensitive dongle, meter originals decode well at
high gain but our own transmission is driven into compression and
rtl-wmbus receives it with a few byte errors (CRC fails). Observed
directly - the decoded hex differed from the transmitted frame in 1-2
bytes, e.g. transmitted `...78534f4c5458...` received `...78514f4c5448...`,
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
(-9 dBm) and the lowest documented PA table (paDutyCycle 0x01, hpMax 0x00).
Remaining mitigation is physical (antenna separation / attenuator), which
is not scriptable from this host.
(-9 dBm) and the lowest documented PA table (paDutyCycle 0x01, hpMax 0x00,
SX1262 datasheet table 13-21). Remaining mitigation is physical (antenna
separation or an inline attenuator) and is not scriptable from this host.
Consequences for verification methodology - see docs/TESTING.md:
1. real-meter originals and Heltec RX match rate are measured at high gain;
2. Heltec TX decodability is proven separately with synthetic C1 bursts
that are not preceded by a weak frame (phase A of `hil/run.sh`);
3. RF-level repeat evidence is available from IQ burst-pair timing.
Note: `rtl_sdr -g 0` selects *automatic* gain, not 0 dB. The lowest real
fixed gain on this tuner is 0.9 dB. At 0.9 and 7.7 dB fixed gain the
degraded dongle decoded nothing at all (neither meters nor our TX), so low
gain is not a usable workaround in that state.
## 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 %) |
A longer gap gives the rtl-wmbus demodulator time to recover its level
estimate after the weak original before the very strong repeat arrives.
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
repeater: the firmware's own timing is accurate to a few microseconds.
estimate after the weak original before the much stronger repeat arrives.
The HIL default is therefore 200 ms, still inside the 20-200 ms
development range. This is an artefact of the observer, not the repeater:
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.