From 9a65fa2040fc6a4adc64dce1448d931b70779b7d Mon Sep 17 00:00:00 2001 From: Lars Nolden Date: Tue, 1 Sep 2026 09:35:05 +0200 Subject: [PATCH] docs: withdraw degraded-observer match rate, record observer drift and IQ TX proof --- docs/FINDINGS.md | 34 ++++++--- docs/RF_FRONTEND_TESTS.md | 145 ++++++++++++++++++++++++-------------- 2 files changed, 120 insertions(+), 59 deletions(-) diff --git a/docs/FINDINGS.md b/docs/FINDINGS.md index 5173838..a95b2bc 100644 --- a/docs/FINDINGS.md +++ b/docs/FINDINGS.md @@ -52,18 +52,36 @@ ## CONFIRMED (measurement methodology) -- Heltec RX is competitive with the Nooelec observer on identical traffic: - 124 of 127 SDR-classified originals matched byte-exactly in a 30 min run - (97 % across 32 meters). +- WITHDRAWN: an earlier entry claimed "Heltec matched 124 of 127 SDR + originals (97 %)". That measurement was taken while the dongle was in its + 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 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 - with 9-10 ms duration (matches 100 kbps x ~100 bytes) - the repeat is - real RF, independently observed, even when rtl-wmbus cannot decode it. -- The observer, not the repeater, limits repeat decoding: our TX arrives - ~36 dB stronger than meter traffic and sits at RTL-SDR full scale. +- Real repeats are emitted as correct RF: aligning firmware TX timestamps + to bursts in the same stream's IQ confirmed 48 of 57 TX events (84 %), + 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 + 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 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 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 diff --git a/docs/RF_FRONTEND_TESTS.md b/docs/RF_FRONTEND_TESTS.md index 600e570..51128eb 100644 --- a/docs/RF_FRONTEND_TESTS.md +++ b/docs/RF_FRONTEND_TESTS.md @@ -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.