claudetools/.claude/skills/unifi-wifi/references/ROADMAP.md

unifi-wifi — roadmap

Status as of 2026-06-16. The skill is fleet-generic (every script takes <site>; works on any of the ~49 UOS sites) and WiFi data-gathering is complete. Remaining work is the apply/action side, multi-client enablement, and non-WiFi scope. Build/validate new apply actions against zero-client radios (6 GHz is ~0-client fleetwide) — change → verify → revert, no disruption.

Done (WiFi monitoring + analysis)

• audit-site.sh — config + foreign-interference flags (Plane 1, Mongo).
• live-stats.sh — live per-AP utilization/satisfaction/retry% + per-client RSSI/retry%/reason (Plane 2).
• model-rank.sh / optimize-radios.sh — airtime-reduction + coverage-safe plan. optimize-radios consumes the SNR matrix (NEIGHBOR_JSON) for data-backed disables (roam graph fallback).
• neighbor-collect.sh — AP-to-AP SNR matrix from /proc/ui_neighbor (+ NBR_JSON adjacency emit).
• survey-collect.sh — measured per-channel busy%/noise → cleanest-channel input.
• dfs-check.sh — empirical DFS radar history (dmesg) → is DFS safe at this site.
• watch-ap.sh — live per-AP RF stream (mca-dump + iw survey).
• apply-radio.sh — gated config apply. Currently: power, width (ht), channel, min-RSSI (all radio_table PUTs). DRY-RUN default; --apply needs infrastructure/uos-server-network-api-rw.

A. Apply side — make WiFi changes fully executable

• apply-radio: power (tx_power_mode/tx_power)
• apply-radio: width (ht 20/40/80/160)
• apply-radio: channel (manual channel assignment)
• apply-radio: min-RSSI (min_rssi_enabled + min_rssi)
• apply-radio: disable/enable a radio — DONE. Disable = tx_power_mode:"disabled" (confirmed 2026-06-16 via UI-toggle + device-JSON diff); enable = auto. Validated full cycle on a 0-client 6 GHz radio. Use --ap <name> to target one AP (the right scope for disables). Still highest-risk (coverage holes) — gate + validate per AP with watch-ap; pair with optimize-radios' disable list.
• min data rates (kill 1–11 Mbps; 2.4 floor 12/24) — DONE in apply-wlan.sh (minrate ng|na auto|off|<Mbps>). Requires minrate_setting_preference=manual (handled). Validated on a 0-client WLAN. band-steering: DONE — modern UniFi has no bandsteering_mode; located its replacements (2026-06-16) and wired all into apply-wlan: bandsteer (no2ghz_oui), bands (wlan_bands — 5g/5g6e forces clients up), steer (roaming_assistant_na), bsstm (bss_transition, 802.11v). Validated on a 0-client WLAN. (fast_roaming_enabled/802.11r left out — risky for IoT.)
• full wlanconf knob set — apply-wlan now also does wlan (enable/disable), dtim, mcast, bcfilter, rrm (802.11k), ftroam (802.11r, warns), isolation, hidessid. dtim apply-validated; rest via the proven gated REST path.
• device-level lock / control — apply-wlan aps <ap-list> (broadcasting_aps = restrict SSID to APs, the "lock to AP" lever) + apply-wlan macfilter off|allow|deny <macs>; new client-control.sh block|unblock|kick a MAC (validated on a dummy MAC). UniFi has NO native per-client AP pin — these are the real mechanisms.
• channel-plan apply — feed survey-collect cleanest-channel output into a per-AP channel set.

B. Multi-client enablement (use on any client we manage)

• Per-client AP device-auth cred: vault clients/<x>/unifi-ap-ssh, pass as the script arg (only Cascades exists today). Keys vaulted per-client as needed.
• Per-client L3 reach to APs (site VPN / route) for the AP-side collectors (Cascades split-tunnel done).
• Controller-only mode documented + discoverable — scripts/sites.sh lists all sites + AP-cred readiness; controller-side scripts validated on other clients (Glabman, Sonoran Glass). AP-side scripts print the exact vault command when a client's cred is missing (and note controller-side works).

C. Non-WiFi UniFi (currently WIP / out of scope)

• Switch/PoE collector — port up/down, PoE budget + per-port draw, errors, uplink negotiated speed (the FastEthernet-uplink issue is still not scriptable).
• Gateway/WAN/firewall + adoption — WAN health/failover, pending-adoption devices.
• The access layer already reaches these (uos-mongo.sh = whole ace DB; controller API + device SSH); they just need dedicated scripts. Consider a sibling unifi skill if scope grows.

D. Robustness / ops

• VPN-flap resilience in the AP-side loops (resume/retry so a mid-run tunnel drop doesn't waste a 4-min sweep). Background runs can't spawn the SSH_ASKPASS helper — must run foreground.
• Scheduling — periodic dfs-check + neighbor/survey refresh (DFS is time-varying).
• Vault read-only infrastructure/uos-server-network-api (least-privilege; RW does double duty now).

Cross-platform notes (baked into the scripts; keep for any new ones)

• Pass temp paths to python via ARGV (MSYS translates POSIX→Windows for python.exe); $TMP inside a python -c string is NOT translated → fails on Windows.
• Do NOT inject large data as a JS object literal into the mongo shell (~21 KB crashes SpiderMonkey); precompute + inject a compact flat string.
• AP-side SSH: sshpass or SSH_ASKPASS fallback; </dev/null in while read loops; foreground.
• Windows text-mode file writes add CRLF → strip \r after bash read.