claudetools/.claude/skills/unifi-wifi/references/interference-model.md

AP interference / airtime-reduction model — design + data

Goal (per Mike): a fleet/site-level model that decides which AP radios to disable, and where to reduce power, to cut total airtime contention while preserving client coverage. Per AP per radio, all bands (not 2.4-only, not per-client). Inputs: each AP's neighbor/overlap relationships

• historical client connections + airtime.

Data — it's ALL in the controller (corrected 2026-06-15)

First pass only checked the ace DB (config/current state) and wrongly concluded the history "isn't there." It is — in ace_stat (1.5 GB of accumulated time-series) and the wifi_connectivity_event collection. No external collector is needed; the controller already retains it. Three databases on the UOS Mongo (port 27117):

DB	Holds	Use
ace	config + current state	radio_table (channel/band/width/power/min_rssi), rogue (FOREIGN interference), channelplan, device/floorplan
ace_stat	time-series history	the model's airtime + client history (below)
ace_audit	audit log	—

ace_stat.stat_hourly / stat_daily (o:'ap') — per-AP per-band airtime history

Flat per-band fields (ng=2.4, na=5, 6e=6): <band>-cu_total (channel utilization %), <band>-cu_interf (airtime lost to interference %), <band>-cu_self_rx/tx, <band>-num_sta, <band>-satisfaction, <band>-tx_retries. Plus ap (AP mac), site_id, time (ms epoch). This is the historical airtime/interference/load profile per AP per band — the core "who's contending" signal. (Also o:'user' per-client retries/anomalies; o:'site' rollups.)

ace_stat.wifi_connectivity_event — the roam graph (empirical AP adjacency)

Each doc: from_endpoint{mac(AP), channel, channel_width, band, rssi}, to_endpoint{mac(AP), ...}, client_mac, successful, time, _class:WIFI_ROAMING. Every roam is an edge between two APs a real client handed off between → empirical coverage overlap/adjacency, weighted by volume, with the handoff RSSI (coverage quality). This is the "historical connections → which APs cover the same space" signal, and it's better than a raw RF scan because it reflects where clients actually move.

Still useful from ace / setup

• rogue aggregate = FOREIGN co-channel interference per channel (Plane-1 audit).
• Floorplan coords: not set today (0/77 APs placed). Mike is willing to use the floorplan feature → once APs are placed, device x/y gives true physical distance for adjacency edges (complements the roam graph, esp. for APs that rarely roam-share).
• Live Network API (stat/device/stat/sta) still adds current utilization + the AP's live RF-neighbor table; nice-to-have for before/after validation, not required to build the model.

Model

Per band b, over a history window (default 7d):

• Per-radio airtime: avg cu_total, avg cu_interf, avg num_sta from stat_hourly.
• Overlap/redundancy: roam volume per AP and per AP-pair from wifi_connectivity_event (high roam-share to neighbors ⇒ a client leaving this radio has somewhere to land ⇒ redundant).
• Score (v1, model-rank.sh): (cu_total + cu_interf) * log(1+roams) / (clients+1) — high = this radio burns airtime in a contended band AND its clients are mobile/redundant ⇒ shrink or disable. Hint: DISABLE when high roam + near-zero clients; POWER-DOWN when busy but holds some unique load.
• v2 (greedy, coverage-safe): iteratively disable the top candidate, recompute overlap so we never open a hole (stop when a radio's clients would lose their only good-RSSI neighbor), and add floorplan-distance edges once APs are placed. Output = ranked per-AP-per-radio actions with the metric that justified each, applied per zone with before/after validation.

v1 result (Cascades 2.4GHz, 7d) — the smoking gun

model-rank.sh cascades 7 ng: 2.4 radios run cu_total 74–94%, cu_interf 61–81%, ~0.3–2.6 clients each across 75 APs. Translation: 2.4 is saturated and mostly interference, serving almost no one — a textbook case to disable 2.4 on most APs and power down the rest. Run na/6e for the 5/6GHz picture (expected: keep, with 6GHz the clean capacity band).

Status

• scripts/audit-site.sh — config + foreign-interference audit (Plane 1).
• scripts/model-rank.sh — v1 airtime-reduction ranker from real history (this doc). Works now.
• Next: v2 greedy coverage-safe optimizer + floorplan-distance edges (after APs are placed on the floorplan) + optional live-API before/after validation.