diff --git a/docs/FINDINGS.md b/docs/FINDINGS.md index dae817a..5173838 100644 --- a/docs/FINDINGS.md +++ b/docs/FINDINGS.md @@ -45,17 +45,45 @@ ## LIKELY - Fixed 255-byte RX capture adds up to ~20 ms artificial dead time per - frame (by construction; to be measured). + frame (by construction; measured airtimes are consistent with it). +- The remaining CRC failures on long Techem frames are bit errors + accumulating over frame length, not a hard sensitivity floor: the same + meters decode cleanly when a few dB stronger (docs/RF_FRONTEND_TESTS.md). -## DISPROVEN +## CONFIRMED (measurement methodology) -- "rtl_sdr pipeline works out of the box": the PLL wedge cost ~20 minutes - of empty captures. Always energy-probe the SDR before trusting a null - result. +- 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). +- 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. + Raising the repeat delay 50 -> 200 ms improved SDR repeat decoding from + 3 % to 30 % (demodulator level-estimate recovery). +- 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 + standards-shaped independently of meter traffic. +- rtl_wmbus runs two demodulators, so one airing yields 1-2 output lines; + and rtl_sdr delivers ~81.92 ms buffers, so decode timestamps are + quantized - SDR timestamps cannot be trusted below ~100 ms resolution. + Correlation must use byte identity plus occurrence counting, not + timestamps alone. +- The Nooelec intermittently enters a deaf state (R820T I2C init failure / + PLL wedge). `hil/sdr_health.py` detects it by checking that noise tracks + tuner gain and the spectrum has structure; the harness aborts rather + than reporting an unattributable empty capture. +- "[R82XX] PLL not locked!" printed during tuning is BENIGN (emitted while + rtl_sdr probes and disables direct-sampling mode); it is not a wedge + indicator. The real symptom is railed, gain-independent noise. ## NEEDS TESTING -- Heltec vs SDR RX match rate on real meters (first HIL run in progress). -- LNA on/off comparison (KCT8103L CSD low in RX = bypass?). -- Repeat delay accuracy, RX deaf time distribution over many events. -- Long-run stability (>=100, >=500 repeats). +- 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. +- Long-run stability at >=100 and >=500 verified repeat events. +- Early-stop RX (poll GetRxBufferStatus) to cut the ~20 ms deaf tail. diff --git a/docs/RF_FRONTEND_TESTS.md b/docs/RF_FRONTEND_TESTS.md new file mode 100644 index 0000000..600e570 --- /dev/null +++ b/docs/RF_FRONTEND_TESTS.md @@ -0,0 +1,98 @@ +# RF Front-End (KCT8103L) Observations + +## 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): + +``` +SDR classified originals : 127 +Heltec RX (CRC ok) : 124 matched +per-meter match rate : 97 % (32 meters) +``` + +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. + +## RSSI vs CRC success (Heltec, chip-referred RSSI) + +15-minute run, 166 candidate frames: + +| RSSI bucket | CRC ok | CRC fail | success | +|---|---|---|---| +| >= -50 dBm | 3 | 0 | 100 % | +| -60..-51 | 38 | 3 | 93 % | +| -70..-61 | 24 | 86 | 22 % | +| -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. + +Open: how much of this is FEM configuration vs modem parameters (RX +bandwidth 234.3 kHz is generous; a narrower filter may improve SNR). + +## 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. + +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. + +## Bench dynamic-range limitation (important) + +Measured with IQ capture (`hil/iq_bursts.py`, `captures/iq/repeat.raw`): + +``` +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 transmission arrives ~36 dB stronger than the meter traffic and sits at +the RTL-SDR's full scale (u8 amplitude ~125 of 127). Consequences: + +- 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. + +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. + +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. + +## Repeat-delay dependence of observer decoding + +Same bench, same gain (42.1 dB), only the repeat delay changed: + +| repeat delay | repeats decoded by SDR | +|---|---| +| 50 ms | 2 / 63 (3 %) | +| 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. diff --git a/hil/lna_ab.sh b/hil/lna_ab.sh new file mode 100755 index 0000000..5b7ec4a --- /dev/null +++ b/hil/lna_ab.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# KCT8103L LNA (CSD) A/B experiment - Heltec only, no SDR required. +# +# Runs two equal-length RX-only windows on the same meter population, one +# with the FEM enabled in RX (CSD high, LNA path) and one with it disabled +# (CSD low), then reports frame counts, CRC success and RSSI distribution. +# +# Usage: lna_ab.sh [SECONDS_PER_ARM] +set -euo pipefail +cd "$(dirname "$0")/.." +DUR=${1:-600} +PY=./result-py/bin/python3 + +eval "$(./tools/discover_devices.sh)" +OUT="captures/$(date +%Y-%m-%dT%H-%M-%S)-lna-ab" +mkdir -p "$OUT" +echo "DUT: $DUT_PORT" +echo "arm duration: ${DUR}s each" + +# Retransmission off: this measures the receiver only, and avoids radiating +# during a sensitivity comparison. +for arm in 1 0; do + label=$([ "$arm" = 1 ] && echo "csd_high_lna" || echo "csd_low_bypass") + echo "--- arm: $label" + $PY hil/dut_cmd.py "$DUT_PORT" --listen 3 \ + "set repeat_enabled 0" "set fem_rx_csd $arm" "clear_stats" radio_reset \ + > "$OUT/$label.setup.log" 2>&1 + sleep 3 + $PY hil/dut_cmd.py "$DUT_PORT" --listen "$DUR" status \ + > "$OUT/$label.log" 2>&1 + $PY hil/dut_cmd.py "$DUT_PORT" --listen 4 stats >> "$OUT/$label.log" 2>&1 +done + +# restore normal operation +$PY hil/dut_cmd.py "$DUT_PORT" --listen 3 \ + "set fem_rx_csd 1" "set repeat_enabled 1" radio_reset \ + > "$OUT/restore.log" 2>&1 + +$PY hil/lna_report.py "$OUT" | tee "$OUT/report.txt" +echo "artifacts: $OUT" diff --git a/hil/lna_report.py b/hil/lna_report.py new file mode 100755 index 0000000..5df63f9 --- /dev/null +++ b/hil/lna_report.py @@ -0,0 +1,87 @@ +#!/usr/bin/env python3 +"""Summarise a KCT8103L CSD (LNA) A/B experiment directory.""" +import json +import sys +from collections import Counter + +d = sys.argv[1] +arms = [("csd_high_lna", "FEM enabled in RX (CSD high)"), + ("csd_low_bypass", "FEM disabled in RX (CSD low)")] + +print("=" * 56) +print("KCT8103L RX FRONT-END A/B (Heltec only, no SDR)") +print("=" * 56) + +summary = {} +for arm, desc in arms: + rx, stats = [], None + try: + fh = open(f"{d}/{arm}.log", errors="replace") + except OSError: + print(f"\n{desc}: no data") + continue + for line in fh: + line = line.strip() + if not line.startswith("{"): + continue + try: + ev = json.loads(line) + except json.JSONDecodeError: + continue + if ev.get("event") == "wmbus_rx": + rx.append(ev) + elif ev.get("event") == "stats": + stats = ev + + ok = [r for r in rx if r.get("crc_ok")] + meters = Counter() + for r in ok: + raw = r.get("raw", "") + if len(raw) >= 16: + meters[raw[8:16].lower()] += 1 + rssi = sorted(r["rssi_dbm"] for r in rx if "rssi_dbm" in r) + rssi_ok = sorted(r["rssi_dbm"] for r in ok if "rssi_dbm" in r) + + summary[arm] = { + "candidates": len(rx), + "crc_ok": len(ok), + "unique_meters": len(meters), + "median_rssi": rssi[len(rssi) // 2] if rssi else None, + "best_rssi": rssi[-1] if rssi else None, + "median_rssi_crcok": rssi_ok[len(rssi_ok) // 2] if rssi_ok else None, + "stats": stats, + } + + print(f"\n{desc}") + print(f" candidate frames: {len(rx)}" + + (f" ({100*len(ok)/len(rx):.0f} % CRC ok)" if rx else "")) + print(f" CRC-valid frames: {len(ok)}") + print(f" unique meters: {len(meters)}") + print(f" median RSSI (all): {summary[arm]['median_rssi']} dBm") + print(f" median RSSI (CRC ok): {summary[arm]['median_rssi_crcok']} dBm") + print(f" strongest RSSI: {summary[arm]['best_rssi']} dBm") + if stats: + print(f" firmware counters: rx_candidates={stats.get('rx_candidates')} " + f"rx_valid={stats.get('rx_valid')} " + f"rx_crc_fail={stats.get('rx_crc_fail')} " + f"not_c1={stats.get('rx_not_c1')}") + +a, b = summary.get("csd_high_lna"), summary.get("csd_low_bypass") +if a and b: + print("\nCOMPARISON (CSD high vs CSD low)") + print(f" CRC-valid frames: {a['crc_ok']} vs {b['crc_ok']}") + print(f" unique meters: {a['unique_meters']} vs {b['unique_meters']}") + if a["median_rssi"] is not None and b["median_rssi"] is not None: + print(f" median RSSI delta: {a['median_rssi'] - b['median_rssi']} dB " + f"(positive = CSD high stronger)") + if a["crc_ok"] > max(3, b["crc_ok"] * 1.3): + verdict = "FEM enabled in RX is clearly better" + elif b["crc_ok"] > max(3, a["crc_ok"] * 1.3): + verdict = "FEM disabled in RX is clearly better" + else: + verdict = "no clear difference at this sample size" + print(f" verdict: {verdict}") + print("\nNote: meter traffic varies between arms; treat small differences") + print("as inconclusive unless both arms saw a comparable meter population.") + +json.dump(summary, open(f"{d}/summary.json", "w"), indent=2, default=str) diff --git a/hil/sdr_health.py b/hil/sdr_health.py index effbce2..18128dc 100755 --- a/hil/sdr_health.py +++ b/hil/sdr_health.py @@ -76,8 +76,11 @@ if lo is None or hi is None: delta = hi["mean_power_db"] - lo["mean_power_db"] reasons = [] -if hi["mean_power_db"] > RAILED_DB: - reasons.append(f"railed: mean power {hi['mean_power_db']:.1f} dB > {RAILED_DB}") +# Railed only counts as a fault together with a flat spectrum: a healthy +# receiver with a strong nearby signal can legitimately show high mean power. +if hi["mean_power_db"] > RAILED_DB and hi["spectrum_span_db"] < 15.0: + reasons.append(f"railed: mean power {hi['mean_power_db']:.1f} dB > {RAILED_DB} " + f"with flat spectrum") if hi["spectrum_span_db"] < MIN_SPAN_DB: reasons.append(f"flat spectrum: span {hi['spectrum_span_db']:.1f} dB < {MIN_SPAN_DB}") if delta < MIN_GAIN_DELTA_DB: