Add antenna-decorrelation measurement harness (spatial-diversity #129)

[josephnef]

Summary

Foundation tooling for the spatial-diversity roadmap (#127) — the effort to
exploit the RF chains a single-stream video link leaves idle (1 on a 2T2R part,
up to 3 on a 4T4R 8814) as diversity/robustness, the third axis alongside
frequency hopping (docs/frequency-hopping.md) and the fused FEC
(docs/fused-fec.md).

Closes the measurement half of #129. Every downstream diversity claim (RX MRC
#130, ANTSEL probe #131, STBC #132, spatial×FEC #133) rests on the chains'
antennas being decorrelated — on a small airframe they may not be. This adds
the harness that measures the decorrelation a given antenna layout actually
delivers, so gains are reported as measured rather than theoretical.

Changes

• demo/main.cpp — opt-in DEVOURER_RX_ALLPATHS=1 emits a
  <devourer-rxpath> line per canonical-SA frame carrying all four RX chains
  (A,B,C,D) of rssi/snr/evm. The library already populates paths C/D on the
  8814AU; the demo previously printed only A,B. On a distinct tag so the
  canonical <devourer-stream>/<devourer-body> two-path format (and its regex
  consumers) is untouched. Paths C/D read 0 on 2T2R parts.
• tests/antenna_decorrelation.py — parses the per-chain metrics and reports
  per-chain level stats, the pairwise envelope correlation matrix (Pearson on
  linear amplitude — the diversity-relevant correlation, not on dB), and a
  combining analysis: selection- and maximal-ratio-combining gain over the
  best single chain at the 10 % and 1 % outage points vs the theoretical
  10·log₁₀(N) array gain. Verdict is keyed off the worst pairwise |ρ| (ρ<0.7 =
  "diversity still useful"). A hardware-independent --self-test validates the
  estimator and combining math against synthesised correlated Rayleigh fading.
• tests/run_antenna_decorrelation.sh — build + capture + analyse runner
  (exact-comm cleanup trap, uv venv, sudo for the USB claim); optionally starts
  the beacon TX (TX_PID).
• CLAUDE.md — document DEVOURER_RX_ALLPATHS.

Why measure against the canonical beacon

The library only surfaces per-chain metrics for the canonical SA
57:42:75:05:d6:00, so the harness measures a steady, known source (the standard
two-adapter bench setup) — the right controlled condition for a correlation
estimate, rather than noisy ambient traffic.

Testing

• uv run python tests/antenna_decorrelation.py --self-test — green. Recovers a
  known envelope correlation to ±0.05 (synthesising with field-corr = √ρ_env,
  since ρ_env = |ρ_field|² for Rayleigh), confirms independent 4-chain MRC mean
  gain ≈ 10·log₁₀(4), and that correlated chains yield less low-outage gain than
  independent ones.
• WiFiDriverDemo builds with the new emission.
• Not yet run on hardware — the on-air 8814 capture across antenna
  spacings/polarisations is the field-validation step, tracked in Antenna-decorrelation measurement harness #129/RX-side in-chip MRC on an 8814 ground station #130.

🤖 Generated with Claude Code

[josephnef]

Hardware validation on two RTL8814AU dongles

Ran the harness on both plugged 8814s (CF-938AC, 2 external dipoles; CF-960AC,
4 on-PCB internal antennas) — which enumerate with an identical
VID:PID:serial, so this also validated the new DEVOURER_USB_BUS/PORT
topology selector. One controlled beacon TX (8812AU, ch6), each 8814 as RX,
~7.5k canonical-SA frames each.

What worked end-to-end: the selector targeted the two identical devices by
bus/port (distinct per-chain fingerprints confirm different hardware was
opened), the opt-in 4-path emission delivered all four chains, and the analyser
ran clean.

Two findings that hardened the tool:

1. A static bench beacon can't measure decorrelation. Per-chain std came out
   at ~0.15–1.8 units — the near-field beacon is a static channel with almost no
   fading, so envelope correlation just tracks quantisation noise. The harness
   now reports INCONCLUSIVE below MIN_FADING_STD instead of a bogus
   GOOD/MODERATE. A valid decorrelation number needs a fading stimulus:
   motion, varied multipath, or a mobile link. This is the key methodology note
   for the on-air validation step.
2. 8814 path-C RSSI rails at a constant 82.00 on both devices (std ~0.02) —
   a per-path reading (gain_trsw_cd) that carries no signal here; now flagged
   as railed. Relevant to RX-side in-chip MRC on an 8814 ground station #130 (MRC wants valid per-path level/SNR).

Per-chain level fingerprint still distinguishes the adapters (means, static
channel): CF-960AC A/B/D ≈ 74–78; CF-938AC shows a wider spread (B≈60, D≈68),
consistent with only 2 driven external antennas vs 4 internal.

Next: repeat with a fading stimulus (walk the beacon / rotate the adapter /
outdoor multipath) to get a real correlation figure per antenna layout — that's
the field step feeding #130.

Pushed as dad0469 on this branch.

[josephnef]

First valid decorrelation measurement: two 8814s compared (rotation stimulus)

Since a static bench beacon can't excite fading, the RX adapter was rotated /
tilted continuously through the capture window to sweep each antenna's pattern
against the fixed beacon TX (8812AU, ch6). This measures pattern/orientation
decorrelation under strong LOS — a proxy for (not identical to) multipath
envelope correlation, but the relative comparison between two adapters on the
same bench is robust.

Both dongles are the same RTL8814AU silicon, differing only in antenna
front-end:

Adapter	Antennas	frames	per-chain std	worst pairwise |ρ|	MRC gain @1% outage	Verdict
CF-960AC (round AP)	4 on-PCB internal	14348	~4.0–4.7	0.19 (all pairs <0.2)	~13.9 dB	GOOD
CF-938AC (stick)	2 external dipoles	6546	~3.2–4.2	0.64 (A↔C coupled)	~11.1 dB	MODERATE

Interpretation. The CF-938AC drives 4 RF chains from only 2 physical
antennas, so chains A and C are strongly coupled (ρ≈0.64) — effectively ~2
independent diversity branches out of 4. The CF-960AC's genuine 4-antenna array
decorrelates well on every pair (<0.2) — closer to 4 usable branches. So for the
RX-MRC goal (this issue), the 4-internal-antenna adapter is materially better
despite identical silicon; the 2-external-antenna stick gives roughly half the
effective diversity order.

Incidental finding. The 8814 path-C RSSI that railed at a constant 82.00
under the static beacon varies normally once the adapter moves — it was
AGC-pinned in strong static LOS, not dead hardware.

Caveat / next. Rotation-on-a-bench is angular/pattern decorrelation under
strong LOS. The gold-standard figure is a genuine NLOS multipath capture — the
plan is to relocate the beacon TX to another room/balcony (a separate host
running the beacon) and re-measure. The relative ordering (960AC > 938AC) is not
expected to change.

Tooling: tests/compare_8814_decorrelation.sh (auto-detects every 8814 by
bus/port, one beacon TX) + the ROTATE=1 mode of
tests/run_antenna_decorrelation.sh. Runner reliability fixes pushed (33f54a3).