“The WiFi is slow”
1. Pick the site, then open the device from Find client (name, MAC, IP or SSID).
2. Read What to tell the caller aloud. Under it: the signal gauge (hatched = no reading) and the AP the device is on.
3. Weak signal? Ask where they are. Better near an AP = coverage; note the spot. Stuck on a distant AP (Sticky Client Status) = have them toggle WiFi.
4. Good signal, poor satisfaction? Check that AP's utilisation on AP Health — congestion, not coverage.
5. Paste Copy ticket summary into the ticket before escalating.
“I can't connect at all”
1. Not in Find client? It isn't associated. Confirm the SSID and that WiFi is on; check the SSID in Config Audit.
2. An Association issues callout in the client window means the network is rejecting it. Its worst-RSSI figure shows whether distance is why.
3. Several clients on one AP? Look for an offline AP on AP Health — check power and uplink first.
“Calls and video keep dropping”
1. Open the client — the verdict line flags unstable roaming.
2. Roaming & Reconnects → Call impact marks clients whose reconnect gaps drop calls.
3. Same spot every time? Run the Walkthrough Tracer along that path.
4. The lasting fix is configuration: the Action Plan ranks it (802.11r, Min RSSI) with the UniFi setting path.
“The whole site looks offline”
1. Check Fleet. It reads gateway status from the UniFi cloud, independent of this site's controller. chronic = down so long it is probably decommissioned.
2. The header mode chip shows what this dashboard can reach: Offline = the controller didn't answer; Syslog = controller down but events still arriving, so the site is probably up.
3. Gateway online in Fleet + controller unreachable = a monitoring problem, not a customer outage.
What Spectra IQ does
A read-only Wi-Fi diagnostic dashboard for UniFi. It analyses one site at a time (clients, APs, roaming, RF) and watches gateways across the whole fleet. It never changes controller settings; it tells you what to change and where.
Header
Site pickerType to filter by site name, account or link hint (cloud only, no WiFi). Retired sites collapse at the end.
Find clientSearch this site's clients by name, MAC, IP or SSID.
Clock · ↻Pause auto-refresh · refresh now. Intervals are in Settings → Display.
💬Report a bug or a confusing screen.
Status chips
Hover a chip for detail; click it for more.
ModeLive; Syslog = controller unreachable, events still live; Demo = sample data; red Offline = no data, so the panels are empty, not idle.
StorageDISK = history survives restarts. Red RAM = it won't; the server can't write its data volume.
Cloud keysShown only when a UniFi cloud API key is rejected.
ControllerSelf-hosted controller only. Amber = unreachable or checking, retrying on its own. Red = session expired; click to paste a new one.
Tab badges
A red count is problems, amber is warnings, and a green check is all clear.
On a phone
The site name is the picker and the magnifier is Find client. The status dot takes the worst chip's colour and opens every chip's detail; ⋯ holds the header buttons. Tabs sit at the bottom: Overview · Clients · Actions · Fleet · More.
Hover almost anything for a tooltip, or tap it on a touch screen.
Glossary
The same definitions the chips and tags show as tooltips.
Overview
Answers “what's wrong right now?” From the top:
Network StatusA plain-English summary, with the Syslog chip beside it.
Key numbersHealth score with its deductions, call interruptions, clients and APs online. Click one to jump to its tab.
Needs attentionOne line per finding: Now (observed) before Warn (advice). Acknowledged items drop off.
BelowClient Distribution per AP, Client signal, Activity, and More analysis (metrics, insights, incidents, anomalies).
A hatched grey “—” means unknown, never zero or fine. Customize reorders or hides sections.
Client signal and Activity
Client signal puts every client on one dBm axis over the tracer's zones: one dot in the red zone is a device problem, a crowd is a coverage problem. Click a zone to list its clients.
Activity stacks disconnects, roams and connects per time bucket on one scale. Red marks a disconnect spike; ▲/▼ compare with the previous window. Hover a bar for the clients.
Syslog chip
flowing = a message in the last 10 min. quiet = none lately, so roaming, incidents and history stop updating. not set up = never received; events come from the controller alone. The full ingest view is on the Debug tab.
History
Reads the durable store, so it survives restarts and reaches back 90 days. Connections draws one lane per client (1, 4 or 24 h), coloured by AP with a red tick at each drop: sleep/wake cycles, clean roams and drop loops show as shapes. Hatched = the log can't say. Below it, filter the event log by range, type or client MAC, or switch to sticky sessions.
Action Plan
Every recommendation from the other tabs, de-duplicated and ranked: Happening now, then Recommended changes, each with the fix and a link to its evidence. Acknowledge tells everyone you're on it and removes it from the badge. When a fix lands in UniFi, the item moves to Recently resolved on the next pass.
Wireless Clients
Every associated client with signal, AP, rates, satisfaction and capability (Wi-Fi 6/5, 11r). Tinted rows have issues. Click a row to open the client; 📡 starts a walkthrough trace.
Config Audit
Each SSID scores the share of applicable best-practice checks it passes (green ≥ 80%, amber ≥ 60%). Click a check for the fix and its UniFi setting path. Turn off checks you don't care about in Settings → Network & AP → Config Audit Scoring. DFS Channel Exposure appears below when an AP uses a DFS channel.
Roaming & Reconnects
Roaming Anomalies lists clients over the roam-rate thresholds (Settings → Network & AP) with their reconnect gaps: p50 is typical, p95 is the one that drops calls, Max is the single worst. Call impact marks gaps long enough to drop a call. Rapid Reconnects catches drop-and-rejoin loops: driver, coverage or a failing AP.
Bouncing between the same two APs is roam ping-pong: near-equal signal and no Min RSSI.
Sticky Clients
Clients holding a weak signal when a nearer AP should take them, usually because of no 802.11r, no Min RSSI, or an AP set too loud. Thresholds are in Settings → Client Sensitivity. no impact = still ≥ 80% satisfaction, typically a stationary edge device. To see which AP it should use, run the Walkthrough Tracer; the controller doesn't say.
RSSI Thresholds
Every AP radio and SSID's roaming enforcement: Roaming Assist (802.11v nudge, per SSID), Min RSSI (disconnects weak clients, per radio) and the optional Interference Blocker. 5 GHz Alignment flags Min RSSI firing before Roam Assist. The tab badge counts APs that aren't correctly layered.
Baseline: Roam Assist −72 dBm, Min RSSI −80 dBm, the same on every AP.
AP Health
One card per AP, outlined by status: green healthy, amber warning, purple DFS channel, red offline. Each radio shows channel, width, utilisation (ticks at 50% busy and 80% full) and TX power with its mode chip (see the Glossary). Click a card for the AP's detail.
Sticky clients on an AP whose 5 GHz radio is HIGH? Try MEDIUM: a too-loud AP holds clients past the handoff point.
RF Neighbors
Other networks your APs hear, with signal and an interference rating. The summary counts co-channel conflicts: neighbours on your channel or 80 MHz block. Needs LAN access and AP firmware that reports RF scans.
Tuning
Quick Wins (highest-impact changes), a client census by Wi-Fi generation, band and 11r/PMF support (hover a bar for the devices), and the Channel Planner: teal = yours, amber = neighbours only, red = conflict. Channel Coherence flags your own APs sharing a channel and 2.4 GHz channels other than 1, 6 or 11.
DFS Analyzer
DFS channels (52–144) add 5 GHz spectrum but must be vacated on radar, dropping clients for 1–10 min. The analyzer combines radar history, neighbour congestion and utilisation into safe / caution / avoid per channel, plus an overall verdict and a recommended channel. heuristic = no live RF scan.
Using DFS on purpose? Turn on Known DFS deployment in Settings → Network & AP.
Mesh
Which APs uplink wirelessly, and to whom, with each link's rate and quality. Quality comes from signal: Fair below −65 dBm and Poor below −75 dBm; a weak link throttles every client behind it. Hidden when no AP meshes.
Fleet
Gateway status for every watched site, read from the UniFi cloud whichever site is selected. It needs the Gateway Monitor (Settings → Gateway Monitor). The table opens on Needs attention (offline, unverified or flapping); turn it off to list everything. It refreshes after every monitor poll, and ↻ refreshes it now.
Tags: chronic = down past the chronic threshold, probably decommissioned; flapping = repeated drops; unverified = not confirmed in recent polls; silenced = paging paused.
A failed or rate-limited cloud call is never counted as an outage. Only UniFi reporting the gateway offline is.
Coverage waffle
One square per site, problems first. Red = outage, amber = pending, ringed = flapping, pale = chronic or silenced, green = online, hatched = unverified, grey = excluded, outline = no cloud-visible gateway (it can't alert). Click a legend entry to hide that group.
Site detail
Click a row for the gateway, WAN, devices and clients, 7 days of up/down transitions, and every alert sent on each channel. Maintenance silence (1, 4 or 24 h) stops paging but keeps the site watched; it pages again if the site is still down when the silence ends.
Playbooks and Caller script toggles
These two Fleet filter-row toggles hide the Help Playbooks tab and the client window's “What to tell the caller” line, for teams that don't take customer calls. Saved in this browser; click again to bring them back.
Wall board
⛶ Wall board is a full-screen, read-only NOC view that refreshes itself and cycles pages. Esc closes it.
Controller Connection
Opens from a status chip or the connectivity banner.
OverviewThis site's controller link and event stream.
DiagnosticsSyslog parsed vs ignored, socket state, recent API calls. Start here when Activity looks flat.
Raw EventsExactly what the controller is sending.
SitesEvery discovered site, its link type and counts. Admins edit names, LAN URLs and keys here.
SessionsAdmins: every sign-in, cloud key, console and controller connection the server holds. Secrets are never shown.
A cloud only site has no local access, so it has no client, AP-health, RF or mesh detail.
Debug
Admins only. Proves the alerting works instead of assuming it.
Ingest PipelineSyslog and API rates, parse success, socket state.
Outage SimulatorForces one watched site offline so the real threshold, dispatcher and channels run. Page now alerts in seconds; Full timing uses the real clock; Dry run sends nothing.
Device DigestBuild the AP/switch digest now.
Monitor PlumbingWatch list, cloud keys, alert state, site filters.
Tester FeedbackReports sent with 💬.
Simulated alerts really send, marked [SIMULATED], and release the site after 30 minutes.
What the Walkthrough Tracer does
It turns one device into a survey probe. Carry the device around and it plots signal, AP, rate and satisfaction over time, showing where coverage drops and whether the device roams on time.
UniFi reports a device's signal in batches, roughly once a minute (about 78 s on the controller we measured). Checking more often doesn't create readings, so treat a walk as a series of stops.
Running a trace
Start📡 on a Wireless Clients row, or Start walkthrough trace in the client window. Then ▶ Start trace.
At each spotStand still until the freshness ring resets. 📍 Mark spot pins the next reading.
Finish■ Stop, then ▶ Resume, Clear or ↓ Export.
Stop at each AP and at the midpoints between them. That's where late roams show up.
Walk and Chart views
Walk (the phone default): one big zone-coloured reading, what to do next, and Mark spot / Stop within thumb reach. The screen stays awake while recording. Chart (the desktop default): the full timeline beside a live rail.
Reading the trace
SignalOne dot per reading over tinted weak zones (Settings → Client Sensitivity). The dashed tail is not yet re-confirmed.
RoamsDashed lines naming the new AP. An amber bracket marks a late roam.
AP laneWhich AP held the device. Hatched = the controller wasn't listing it.
Freshness ringThe reading's age against this controller's usual refresh; amber = overdue.
SuggestedA heuristic: the best other AP seen this session. UniFi exposes no real roam candidates.
Hover or drag across the chart to read every lane at one moment.
Summary and export
Guidance judges each roam (healthy, late or downgrade) and flags sticky behaviour. The summary gives the worst reading, time below each floor and every roam. ↓ Export: CSV (every reading and spot), or PNG / SVG (timeline plus summary, ready for a ticket).
Display, Client Sensitivity, Network & AP and Tab Order are saved in this browser; Reset to defaults restores them. Gateway Monitor, Notifications, Backups, Users and Audit Log are server-wide and admin-only. Each field explains itself in Settings; this page says what each tab is for.
Display
Theme, card trend graphs, RSSI settings on AP cards, the Config Audit failing label, sites to hide from the picker, the connectivity banner, tooltips, date and timezone, refresh intervals and animations. A dismissed connectivity banner stays dismissed until its issues change.
Client Sensitivity
When a client counts as sticky (−72 / −82 dBm), unsatisfied (50%) or reconnect-looping (2 in 30 s), plus the tracer's check interval (500 ms). The gauge at the top shows the effect on the health score as you move a slider.
Network & AP
AP utilisation (70%) and satisfaction (65%) warnings, roam-rate (3 / 5 per hour) and reconnect-time (15 / 30 s) thresholds, flapping, incident auto-dismiss, DFS handling, and Config Audit Scoring: which checks count toward the score.
Gateway Monitor
The cloud gateway monitor behind Fleet. It only reads UniFi's Site Manager API. It sets the offline threshold (default 5 min), poll interval (300 s), which sites to watch, repeat and recovery alerts, grouping for outage storms and the chronic threshold. Device digest batches AP and switch outages into one periodic email; it stays log-only until you turn that off. Saving restarts the monitor.
Notifications
Teams, SMTP and Mailgun. Every enabled channel gets every alert, so enabling both email channels sends two. Email channels take recipients and a subject prefix or full subject template for ticket parsers; test and drill markers always stay in front. Save & send test proves a channel works before an outage does. Secrets are saved in config.json; environment variables override them.
Receipt links (off by default) add a link the recipient clicks to confirm the message reached a person. A click only records receipt; it never acknowledges or silences an outage.
Backups
Scheduled, integrity-checked snapshots of the history store. Set how often, a size cap (oldest go first; the newest is always kept) and a destination; use a mounted share to survive losing the volume. Restore applies on the next restart and keeps the old database. Archives contain credentials, so handle them that way.
Tab Order
Drag to reorder the main tabs; the eye shows or hides one. Overview always stays.
Users
Create accounts, set roles, reset passwords, disable or delete. An admin sees everything and manages configuration. A viewer sees only assigned sites, enforced by the server. The last active admin can't be removed.
Audit Log
Every sign-in, failure, lockout, account change and admin action: who, from where, and whether it worked. Filter by category, account or failures. Kept 365 days. Passwords, keys and cookies are never recorded.
Version History & About
Changes by date; the app's version and build date.
Sign-in and accounts
Off by default. Add an auth block to config.json and restart:
{ "auth": { "enabled": true, "password": "bootstrap-password" } }
Sign in with that password and create accounts under Users. Once one exists, sign-in takes a username and password and the shared password stops working. A session lasts a fixed 24 h (auth.sessionHours); 8 failed sign-ins lock an IP out for 15 min.