Files
heltec-repeater/docs/RF_FRONTEND_TESTS.md

182 lines
8.0 KiB
Markdown

# 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
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 : 41
Heltec RX candidates : 122 (CRC ok: 56)
matched originals : 24 -> 58.5 % of SDR originals
unique meters seen : 35 (union of both receivers)
```
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)
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: 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.
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 - MEASURED
`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 (retransmission
disabled, so the receiver is measured in isolation).
Result, 600 s per arm, `captures/2026-09-01T10-55-00-lna-ab`:
| | CSD high (FEM enabled) | CSD low (FEM disabled) |
|---|---|---|
| candidate frames | 108 | 5 |
| CRC-valid frames | 35 | 5 |
| unique meters | 18 | 1 |
| median RSSI (all) | -61 dBm | -102 dBm |
| median RSSI (CRC ok) | -53 dBm | -102 dBm |
| strongest RSSI | -45 dBm | -101 dBm |
| firmware counters | candidates=190, valid=34, crc_fail=73, not_c1=83 | candidates=8, valid=5, crc_fail=0, not_c1=3 |
**Conclusion: the KCT8103L RX path is essential.** Disabling it costs about
41 dB of chip-referred signal level and cuts the visible meter population
from 18 to 1. CSD must be held high in RX.
Two secondary observations:
- With CSD low the few frames that still arrive decode with 100 % CRC
success at -102 dBm. Signal and noise both drop with the FEM disabled, so
SNR survives for the single strongest local meter; chip-referred RSSI is
therefore not comparable across arms as an SNR measure.
- No sign of the "too much gain hurts" failure mode at this site: the
high-gain arm saw strictly more meters with no CRC collapse on strong
frames. Excessive front-end gain was a plausible risk given strong
868 MHz neighbours, but it is not what limits this bench.
Cost of the sensitive configuration: with CSD high, 83 of 190 sync matches
(44 %) were not C-mode (`rx_not_c1`) - T1 traffic plus false syncs from the
deliberately short 8-bit preamble detector. Each false sync consumes one
fixed-255-byte RX window (~12 ms, docs/TIMING.md).
## Bench dynamic-range limitation
Measured on a single stream (`iq_proof.json` of the 600 s run):
```
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
```
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.
These TX amplitudes predate PA-row telemetry. They demonstrate the
observer's compression behavior in those captures, but must not be used as
the output level of the fixed firmware: the now-removed `pa_low` diagnostic
could select an undocumented SX1261-values/SX1262-select hybrid.
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.
Firmware correction: the former “lowest documented PA table”
`(paDutyCycle=0x01, hpMax=0x00, deviceSel=0x00, paLut=0x01)` mixed the
PA-duty/hpMax values from the SX1261 +10 dBm row with SX1262 selection.
It is not a documented SX1262 row and cost about 32 dB. It has been
deleted. Current firmware uses documented SX1262
`(0x02,0x02,0x00,0x01)` with SetTxParams -9 dBm. Receiver compression must
be handled at the observer with fixed low gain, physical separation, or an
attenuator—not by misconfiguring the DUT PA.
Note: `rtl_sdr -g 0` selects *automatic* gain, not 0 dB. The lowest real
fixed gain on this tuner is 0.9 dB. In the historical degraded-observer
test, 0.9 and 7.7 dB decoded neither meters nor the then-configured TX.
With fixed firmware, a 0.9 dB-gain smoke capture measured all 9 beacons at
median +27.81 dB over floor without clipping.
## 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 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
`hil/meter_anchored.py` -- clock fitted on strong meter receptions
(never on TX events, which can borrow their original's burst), then
event-correlated FSK spectral excess against non-TX controls. Immune to
compression and observer drift; classifies strong/weak/not_observed.