Architecture & rig topology

What the codebase looks like #

Single mangowifi.exe binary that runs in one of two roles (Agent or Console). Both roles are the same binary; role is picked by the config file it reads on startup. Config location is chosen by the MANGOWIFI_DATA_DIR environment variable — no CLI flag. That's the trap that ate an hour of this session's verification claims and is now saved as memory.

Topology #

┌─────────────────────┐        Wi-Fi         ┌─────────────────────┐         wired LAN
│      Console        │◀──── over the AP ───▶│      Agent          │◀───────────────────▶  LAN receiver
│  (dev box, wired)   │      under test      │  (STA-side box)     │                       (iperf3 -s, ...)
│                     │                      │                     │
│  · UI (Tauri WebView)│      TCP 7745        │  · WS server        │
│  · orchestrates      │───── WS control ────▶│  · UDP 7746 echo    │
│  · runs probe        │◀──── UDP echoes ─────│  · runs iperf3      │
│    (Console-side)    │      port 7746       │    (Agent-side)     │
└─────────────────────┘                      └─────────────────────┘

Source layout — src-tauri/src/ #

The catalog model #

TestSection splits the whole suite into four buckets that the sidebar mirrors 1:1.

Every row is a BuiltinTest struct — the important fields:

BuiltinTest {
  id, name, description, section,
  wfa_program, wfa_ref, coverage,          // WFA section
  criteria_category, criteria_ref,          // Criteria section
  baseline_category, baseline_required,     // Baseline section
  wifi8_category, spec_ref,                 // Wifi8 section — spec_ref points at "802.11bn D2.0 §35.14" etc.
  setup, min_gen, duration_secs, tags,
}

The Wi-Fi 8 probe stack #

This is the piece we built from scratch in this arc.

latency_probe.rs — the instrument

pub struct ProbeSummary {
  p50_us, p95_us, p99_us, p99_9_us,
  mean_us, min_us, max_us,
  sent, received, lost, loss_ratio, count,
  duration_ms, rate_pps,
}

pub struct BucketedSummary {
  overall: ProbeSummary,
  bucket_ms,
  buckets: Vec<ProbeSummary>,
}

pub async fn run(target, rate_pps, duration)
     -> Result<ProbeSummary, String>
pub async fn run_bucketed(target, rate_pps, duration, bucket_dur)
     -> Result<BucketedSummary, String>

16-byte UDP probe packet: [u64 LE seq | u64 LE send_time_ns]. Sender loop and receiver task run concurrently; RTT recorded into an HdrHistogram (1 µs .. 60 s, 3 sig figs). run_bucketed uses a Vec of per-bucket histograms indexed by elapsed time.

probe.rs — the shared core

enum PercentileTarget { P95, P999 }
enum LoadPolicy      { None, Once(&'static str), Cycle(&'static str) }

struct ProbeThresholds {
  tail_pass_ms, tail_warn_ms,
  loss_pass_pct, loss_warn_pct,
  target, label,
}

async fn run_probe_core(
  state, test_id, defaults, thresholds,
  load_policy, bucket_ms, params,
) -> CriteriaResult

One implementation body, four Tauri commands lit up by different constants:

How concurrent load is scored — LoadOutcome

enum LoadOutcome {
  NotRequested,
  Completed { status: String, cycles: u32 },   // "load[6× pass]" for cycled runs
  Timeout,
  Error(String),
}

Load task spawns before the probe (iperf3 gets a beat to spool up). For Cycle, the load task loops until 5 s before the probe deadline; stops early on skip/not_configured/fail so we don't hammer a broken rig. Reap grace: 30 s (Once) / 60 s (Cycle).

Drift analysis (endurance-only)

• Baseline = first populated bucket's p95 (skips warm-up)
• Drift ratio = max_bucket_p95 / baseline
• Drifted = ratio ≥ 1.5
• A Pass aggregate that hides a climbing tail is downgraded to Warn — the whole point of endurance testing

Full BucketedSummary serialised into CriteriaResult.evidence as JSON, so the JS renders a sparkline without a second round-trip.

Wire flow — what happens when you click Run #

Path for wifi8_rel_p95_latency — the shortest of the three UHR runners.

Console UI: user clicks Run
  ├─ app.js  runWifi8One('wifi8_rel_p95_latency')
  │    └─ invoke('wifi8_rel_p95_latency_run')                              ← Tauri IPC
  │
  └─ probe.rs::wifi8_rel_p95_latency_run(state, params)
       └─ run_probe_core(P95 thresholds, LoadPolicy::Once("udp_high_load"), bucket_ms=None)
            │
            ├─ tokio::spawn(load_task):
            │    └─ console_client::call_with_timeout('criteria_run_one',
            │                                          {test_id:"udp_high_load"}, 120)
            │         └─ ── WS Request ──▶ Agent
            │                                └─ agent_server: dispatch "criteria_run_one"
            │                                     └─ criteria.rs::run_one("udp_high_load")
            │                                          └─ iperf3 -c <LAN receiver> -u -b 500M ...
            │         ◀── WS Response ── CriteriaResult{"status":"skip"|"pass"|...}
            │    → returns LoadOutcome
            │
            ├─ latency_probe::run(<agent-ip>:7746, 200 pps, 30 s)          ← Console-side probe
            │    ├─ sender loop: 16-byte timestamped UDP probes ──▶ Agent UDP 7746
            │    └─ receiver task: ◀── echoes ── record RTT into HdrHistogram
            │    → ProbeSummary
            │
            └─ marshal → CriteriaResult { metrics{p50/p95/p99/p99.9/loss/load_status_code},
                                          evidence(JSON), status(Pass/Warn/Fail) }
                 └─ store in criteria.results (server-side)
                 └─ return to UI
                      └─ refreshWifi8() re-renders the row:
                          · status chip
                          · p50/p95/p99/p99.9 row
                          · loss chip
                          · load chip ("load[pass]" / "load[skip]" / ...)
                          · drift chip + sparkline (endurance only)

The frontend — src/ #

• index.html — sidebar + view containers; data-view="wifi8" for the Wi-Fi 8 tab (electric-blue glyph)
• app.js —
  • callRig(method, args) router: Agent role → direct invoke, Console role → invoke('remote_' + method)
  • WIFI8_RUNNERS map (test_id → Tauri command) — grows as runners land
  • criteriaHeadline(res) — per-test metric row renderer (percentiles, load chip, drift chip)
  • renderEnduranceSparkline(res) — SVG bar chart from evidence JSON
  • refreshWifi8() — fetches catalog + criteria_results, groups by category, renders one card per category with Run buttons for runnable tests

Wi-Fi 8 progress #

Verified traps saved as memory #

• MANGOWIFI_DATA_DIR is the env var, not a --config-dir CLI flag — silently ignored otherwise, two instances clobber each other's config
• Windows tokio sleep floor is ~15 ms — sub-15 ms cadence loops silently run at ~66 Hz on Windows; budget test asserts accordingly
• Pre-existing: Tauri IPC blocks browser-preview verification (use Agent+Console launch, not the Browser pane)

What plugs into what #

Three topologies escalating from dev-loopback to production-lab. Each row of the sidebar (Baseline / Criteria / Wi-Fi 8) has different hardware appetite; here's what actually plugs in.

Topology A — dev loopback (one box, no AP) #

What we've been verifying in this session.

┌──────────────────────────────────────────────────┐
│           Windows dev PC (WINDEV-PC1)             │
│                                                   │
│   ┌────────────────┐         ┌────────────────┐  │
│   │  mangowifi.exe │         │  mangowifi.exe │  │
│   │   (Agent)      │  loop-  │   (Console)    │  │
│   │  MANGOWIFI_    │  back   │  MANGOWIFI_    │  │
│   │  DATA_DIR=     │◀───────▶│  DATA_DIR=     │  │
│   │  agent-data/   │         │  console-data/ │  │
│   └────────────────┘         └────────────────┘  │
│   TCP 7745, UDP 7746          → 127.0.0.1:7745    │
└──────────────────────────────────────────────────┘

What works: probe wire, WS pair, echo responder, catalog rendering, JS UI. Every commit in this arc was verified in this topology.

What doesn't: no radio, no AP, no Wi-Fi at all — Criteria/Baseline runners that call iw / iperf3 -c <LAN> all skip. basic_probe_latency measures sub-ms loopback RTT (not useful, but proves the wire). Agent's udp_high_load returns NotConfigured → the Wi-Fi 8 runners' load-status chip shows load[skip], probe runs unloaded.

Topology B — real lab (2 boxes + AP under test) — the target #

                          ┌──────────────────────┐
                          │  AP under test        │
                          │  (Wi-Fi 6/6E/7/…)     │
                          │                       │
                          │  ┌───┐         ┌───┐  │
                          │  │RF │         │LAN│  │
                          │  └─┬─┘         └─┬─┘  │
                          └────│─────────────│────┘
                               │             │
              over the air ────┘             └──── copper/fibre
                     │                                 │
                     ▼                                 ▼
    ┌───────────────────────────┐       ┌──────────────────────────────┐
    │  Agent box (STA-side)      │       │  LAN receiver                │
    │  Linux preferred           │       │  Linux/Windows box on the    │
    │                            │       │  AP's LAN side               │
    │  · mangowifi.exe (Agent)   │       │                              │
    │  · Wi-Fi NIC (real radio)  │       │  · iperf3 -s -p 5201         │
    │  · wpa_supplicant + iw     │       │  · (future: echo responder   │
    │  · iperf3 client           │       │     on 7749 for over-air     │
    │  · TCP 7745, UDP 7746      │       │     latency probe)           │
    │                            │       │                              │
    │  Optional 2nd Wi-Fi NIC:   │       │                              │
    │  · monitor / sniffer       │       │                              │
    └────────┬───────────────────┘       └──────────────────────────────┘
             │
             │ Ethernet (mgmt) to same LAN as the Console
             │
             ▼
    ┌───────────────────────────┐
    │  Console box (dev PC)      │
    │  · mangowifi.exe (Console) │
    │  · WebView UI              │
    │  · dials TCP 7745 → Agent  │
    │  · UDP probe → Agent:7746  │
    └────────────────────────────┘

What each box runs

How each test category exercises the rig

Setup mode field on each test

Every test in the catalog carries a SetupCompat:

• OtaOnly — needs the AP on the air (real radio, real Wi-Fi)
• WiredOnly — needs coax/programmable-attenuator into an RF chamber (for repeatable range/roaming testing)
• Both — works either way

No wired-RF driver has shipped yet — WiredOnly tests skip until an attenuator driver lands.

Topology C — not yet built #

Three hardware additions unlock the still-inventory Wi-Fi 8 categories.

C.1 — Programmable attenuator (Seamless Roaming) #

    STA antenna port ── coax ── [Vaunix/Mini-Circuits USB attenuator] ── coax ── AP antenna port
                                           ▲
                                           │ USB
                                     Console orchestrates
                                     RSSI decay schedule

• Vendor: Vaunix LDA-602Q or Mini-Circuits RCDAT-6000-90 (~$1–2k each)
• Enables wifi8_roam_boundary_mpdu_loss, wifi8_roam_sticky_prevention, wifi8_rel_throughput_at_range, and the pre-existing range_* Criteria tests
• Software: new attenuator.rs module wrapping the vendor's USB CDC protocol; a boot-time detection like the existing radio probing

C.2 — Multi-Agent cluster (MAPC — 4 tests) #

   ┌──────────┐        ┌──────────┐        ┌──────────┐        ┌──────────┐
   │  Console │──WS──▶│ Agent 1  │──Wi-Fi▶│ AP A     │◀Wi-Fi──│ Agent 2  │
   │          │──WS──▶│ (STA A)  │        │          │        │ (STA B)  │
   └──────────┘        └──────────┘        │◀ coord ─│        └──────────┘
                                            │  cable/ │
                                            │  wireless        ┌──────────┐
                                            └──▶ AP B  ◀────── │ Agent 3  │
                                                                │ (STA C)  │
                                                                └──────────┘

• 2+ coordinated APs sharing a channel — MAPC is the whole point of Wi-Fi 8, and it requires multiple APs to test
• MangoWifi's Agent/Console architecture already handles this shape: Console pairs to N Agents, orchestrates their probes in a MAPC cluster test
• Software gap: a MapcCluster orchestrator on Console-side that fans probe+load calls out to multiple Agents simultaneously; result-aggregation across Agents

C.3 — MLO-capable STA driver (Enhanced MLO — 4 tests) #

• Needs a real Wi-Fi 7/8 client radio with MLO support (Qualcomm FastConnect 7800/8800, MediaTek Filogic 880/8000, Broadcom BCM6725/4918)
• Software gap: wifi_sta.rs extensions for iw MLO commands — iw dev <sta> link mlo add, mlo remove, etc.
• Needs iw ≥ 6.9 and Linux kernel ≥ 6.10 for the nl80211 attributes

C.4 — RF chamber (optional) #

• Faraday-cage isolation eliminates ambient interference — required for cert-grade / regulatory measurements
• Not strictly needed for MangoWifi's target buyer (OEM regression / interop) but standard equipment at authorised test labs
• Vendors: Octobox, ETS-Lindgren

Software dependencies by platform #

Agent box (Linux — the intended production path)

$ ip link                    # link mgmt
$ iw dev                     # radio + STA operations (>= 6.9 for full Wi-Fi 8)
$ wpa_supplicant -v          # >= 2.10 (SAE / MLO)
$ iperf3 -v                  # >= 3.9
$ ping -c ...                # iputils standard
$ dhclient / dhcpcd          # for real STA DHCP

Linux kernel: ≥ 6.10 for Wi-Fi 8 nl80211 attributes. 6.6 LTS is fine for Wi-Fi 6/7.

Agent box (Windows — dev / partial)

The Windows Agent works for control-plane testing (WS server, UDP echo, catalog rendering) but can't run a virtual STA — the wifi_sta.rs primitives are Linux-only. Windows can still do: Baseline environment checks, ICMP ping tests (via ping.exe), iperf3 against a LAN receiver (using the built-in Windows adapter). For the Wi-Fi 8 UHR runners, Windows is fine as an Agent because the probe just needs the UDP echo responder and the concurrent load can be iperf3 on the AP-facing adapter.

Console box

• Windows / macOS / Linux — the app is Tauri, so anywhere a WebView2/WebKit runs
• No radio requirements; just Ethernet to Agent

LAN receiver

• Any Linux/Windows box with iperf3 -s running
• Optional (future): a small mangowifi-echo binary on port 7749 for Agent→LAN UDP echoes, so criteria tests can capture their own p95 without pairing back to Console

Wire-level summary #

Honest scope statement — what's shippable today #

The 12-commit arc #

Everything shipped in this session lives on MangoWifi’s main branch.