hil: LNA A/B experiment scripts, refine health railed check
This commit is contained in:
+37
-9
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
Executable
+40
@@ -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"
|
||||
Executable
+87
@@ -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)
|
||||
+5
-2
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user