“The WiFi is slow”
1. Pick the customer's site, then use Find client in the header — type the caller's device name, MAC, or IP and open it.
2. Read the “What to tell the caller” line at the top of the client modal — it is written to be read out loud, including the healthy case (“WiFi is unlikely to be the cause right now”), which tells you to look beyond WiFi.
3. Weak signal (amber/red RSSI)? Ask where the device is. If moving closer to an AP fixes it, it's coverage — note the location in the ticket. If the device is stuck to a distant AP (see Sticky Client Status in the modal), have the caller toggle WiFi off/on.
4. Signal fine but satisfaction poor? Open AP Health and check the client's AP for high channel utilisation — congestion, not coverage.
5. Click Copy ticket summary and paste it into the ticket before escalating.
“I can't connect at all”
1. Find the device with Find client. Not listed? It isn't associated — confirm the caller sees the right SSID and has WiFi on. Check Config Audit for the SSID's state.
2. If the client modal shows an Association issues callout, the network is rejecting its join attempts — that is WiFi-side. The worst-RSSI figure tells you if it's failing because it's too far away.
3. Many clients affected on one AP? Check AP Health for an offline AP (red OFFLINE badge — power/uplink first).
“Calls and video keep dropping”
1. Open the client from Find client — the verdict line calls out roaming instability with the roam rate and gap length.
2. Check Roaming & Reconnects: clients under Call impact are the ones whose reconnect gaps are long enough to drop VoIP frames.
3. If the same client drops in the same physical spot, run the WiFi Walkthrough Tracer from its modal and walk that path — the charts show exactly where signal collapses and whether the roam happened too late.
4. The durable fixes are configuration: the Action Plan ranks them (802.11r, Min RSSI layering) with the exact UniFi settings path on each card.
“The whole site looks offline”
1. Open Fleet — it shows gateway status for every site from the cloud, independent of this site's controller. An offline row with a duration is a real outage; a chronic tag means it has been down past the chronic threshold (usually decommissioned — check before dispatching anyone).
2. On the site itself, the header mode chip tells you what the dashboard can see: Offline = controller unreachable (the site may still be up — only our view is dark), Syslog = controller unreachable but live events still arriving, which usually means the site is UP and only the management path is down.
3. Cross-check the Fleet row before calling it a customer outage: gateway online + controller unreachable = a monitoring problem, not a customer problem.
What is Spectra IQ?
Spectra IQ is a real-time Wi-Fi diagnostic dashboard for UniFi networks. It connects to your UniFi Network controller (or runs in Demo mode) and continuously analyzes client behaviour, AP health, roaming quality, and RF environment — surfacing issues before they become user complaints.
Use the site selector in the header to switch between managed sites — click it and type to filter the list by site name or cloud account (↑/↓ to move, Enter to open, Esc to close). Up to four icon chips sit at the right of the header (mode, storage, cloud-key, self-hosted controller) — hover any of them for the full state, click for details. A Find client search sits beside the site picker once a site is loaded.
The controller badge (broadcast icon) reports the controller link: green = live and connected, amber = Demo mode on synthetic data, red = the controller is unreachable and you're seeing last-known data.
The storage badge (database icon) reports how the server is keeping history: green “DISK” when connection/event history is being written to the durable store (PostgreSQL in Docker/production, SQLite in local development — either way it survives restarts), red “RAM” when the server fell back to an in-memory database (for example because its data/ volume isn't writable) — in which case history won't survive a restart. Click either badge for connection and storage details.
Navigating the Dashboard
The tab bar across the top organises data by analysis type. Coloured badges on each tab indicate active issues:
Overview
Roaming 3
Sticky Clients 2
AP Health ✓
Red badge = critical issues requiring attention
Amber badge = warnings to investigate
Header Controls
Left to right across the header:
Site pickerClick to open, then type to filter — terms match the site name, its cloud-account label, and its link hints (cloud only, no WiFi), and every term must match. Matches are highlighted and a counter shows how many of the total are visible. ↑/↓ moves, Enter opens, Esc closes. Sites named with the (INACTIVE), (migrated to testing) or (QUIT) prefixes are grouped under a collapsed Retired sites row at the end of the list (searching always includes them). Sites you never want to see can be hidden by name under Settings → Display → Hide sites matching; the counter then reports how many are hidden, and the site you currently have open is never hidden.
Controller badgeBroadcast icon. Green = live, amber = Demo mode, red = controller unreachable. Click for connection details.
Storage badgeDatabase icon, Live mode only. Green = history is being saved to disk; amber = in-memory fallback, so history won't survive a restart.
Clock iconToggles auto-refresh. Teal clock = on (clients and APs refresh every 3 s, full data every 30 s); dimmed and crossed out = paused.
Circular arrowForces an immediate full data reload for the selected site, without waiting for the 30 s interval.
? HelpYou're looking at it. Opens this reference guide.
⚙ SettingsOpens the settings panel — detection thresholds, theme, timezone, gateway-monitor alerting, and (for admins) user accounts.
Sign outOnly present when authentication is enabled. Ends your session and returns to the login screen.
Both status badges open the Controller Connection modal, which is where syslog parse statistics, the raw event feed, and the full site inventory live.
Hover over almost any element in the dashboard — values, graphs, badges, and buttons — to see a contextual tooltip with additional detail.
Glossary
Every term below appears as a chip or tag somewhere in the app, with this same definition as its tooltip — rendered from one shared dictionary so a term can never mean two things.
Overview Tab
The Overview is your landing page and live health summary. It synthesises data from all other tabs into a single narrative + metrics view.
Stat cards — click any card to jump to the relevant tab
The Narrative Panel (when present) provides a plain-English summary of the current network state, generated from the analysis results.
Activity Pulse — Reading the Sparklines
The Activity section shows event frequency over time using four bar chart sparklines. Each bar represents one time bucket (5 min to 1 hr depending on the selected window).
← oldernewer →
Red bar = burst activity (≥70% of peak)
Amber = moderate (40–70% of peak)
Teal = normal activity level
Empty/flat = no events in that window
Hover over any bar to see the event count and a list of which client hostnames were involved in that time bucket. Use the window dropdown to zoom in (1 h) or out (all data) depending on your investigation.
The four sparklines track: All Events (heat-coloured by intensity), Connects, Roam Events, and Disconnects. Trend arrows (▲/▼) compare the current window to the previous equal-length window.
Key Insights Cards
Below the activity pulse, insight cards surface derived metrics — Wi-Fi 6 adoption, band steering effectiveness, coverage quality, and roam efficiency. The mini bar at the bottom of each card is a percentage indicator.
Incidents & Anomalies
Active Incidents are cross-tab events that need attention (e.g. an AP offline, a sticky client on a DFS channel). Click any incident to jump to the relevant detail view.
Active Anomalies are statistical outliers derived from event history — clients roaming more than 3× their peers, reconnect loops, etc.
Pipeline Health
A behind-the-scenes view of the data feeding the dashboard — something the native UniFi console never shows. Two sparklines track the syslog message rate and API call rate over the last two hours, alongside parse-success %, the buffered-event count, and the syslog socket state.
If events ever stop arriving — a controller reboot, a syslog mis-config — you'll see the rate drop and the socket state change here first. This history is persisted to disk, so it survives a server restart.
Fleet Tab
Every other tab analyses one selected site. The Fleet tab is the exception: it reports gateway/router uptime across your whole managed fleet, regardless of which site is selected. It's the helpdesk view — "is any customer's internet down right now?" — and it reads from the Gateway Offline Monitor, so it needs that monitor enabled (Settings → Gateway Monitor). With the monitor off, the tab says so instead of showing an empty board.
Summary counts sit above a table of every watched gateway: site, cloud account (when more than one is configured), gateway model, current status, and how long it has been offline. Every column sorts, the search box filters by site or model, and the offline only toggle narrows to what needs attention.
Click any row for a site detail panel — gateway model and MAC, WAN/ISP information, device counts, and a per-device list where the cloud exposes one. Per-device data is only available for cloud-managed consoles; a site whose devices live behind a self-hosted controller shows the site-level counts only.
⛶ Wall board (in the filter row) opens a full-screen, high-contrast NOC view made for a wall display: big fleet counters, a tile per gateway that isn't verified online, and an all-clear banner when nothing needs attention. It refreshes itself every minute and auto-cycles pages when the problem list overflows one screen. Deliberately read-only — acknowledging, silencing, and site detail stay on this tab. Esc (or ✕) closes it.
A gateway offline here means UniFi's own cloud classifies it offline. A failed or rate-limited API call is never counted as an outage — see the Gateway Monitor section of the Settings Guide.
Controller Connection Modal
Opened from either header status badge or the connectivity banner. Four tabs:
OverviewThe selected site's controller reachability, polling state, and live event-stream status.
DiagnosticsSyslog parse statistics (parsed vs ignored), socket state, and recent API calls. Start here when the Activity Pulse looks flat — a high ignored count with few parsed events means Wi-Fi events aren't reaching the server.
Raw EventsThe unprocessed event feed, for confirming exactly what the controller is sending.
SitesThe full discovered site inventory (below).
Sites Inventory
The Sites tab summarises the fleet — total sites, LAN-connected, access points, offline APs — above a row per discovered site with its link type, AP count, and client count.
SearchFilters by site name or link type.
LAN-connectedHides cloud-only sites, leaving the ones with a reachable controller URL — where live client, AP-health, RF-neighbor and mesh data exist.
With offline APsKeeps only sites with at least one AP down. Combines with the LAN-connected toggle rather than replacing it.
SortingEvery column sorts; the site name stays the tie-break so equal counts keep a stable order.
EditAdmins (or any operator when auth is off) can set a site's display name, LAN URL, and LAN API key here, and add or remove cloud API keys below the table. Changes are validated, written to config.json atomically with a backup, and applied live — no restart.
A cloud only site has no local syslog/LAN access, so its live client, AP-health, RF-neighbor and mesh data are unavailable — only aggregate cloud statistics. A “—” count marks a LAN site with no successful controller contact this session: stale cloud numbers are hidden rather than shown as if they were live.
History Tab
The dashboard's live view holds a rolling window of recent events. The History tab reads the durable store instead (PostgreSQL in Docker/production, SQLite in local development), which keeps accumulating across restarts and outages — so you can answer "was this happening last week too?"
RangeLast 24 h, 7 days, 30 days, or 90 days.
Event typeAll events, or just roams / disconnects / connects / DFS switches.
Client MACNarrow to a single device when you're chasing one user's complaint.
Events / StickySwitch between the compact event log (client name, then the roam / connect / disconnect detail) and recorded sticky sessions.
If the storage badge in the header is amber, the server is running on an in-memory database and this tab will reset on every restart. Fix the data/ directory permissions to make history durable.
Action Plan Tab
Every recommendation the dashboard produces — from Config Audit, Tuning, RSSI Thresholds, RF Neighbors and the rest — collected into one de-duplicated list, ordered by impact. Each entry describes the fix and the outcome to expect, and links back to the tab where you can act on it.
It is also a triage queue, shared across everyone signed in to this dashboard: Acknowledge an item to mark it known/being-worked — it stays listed (with who acknowledged it, and when) but leaves the tab badge, which counts only items still needing a decision. Spectra IQ never changes your controller; instead, when a later analysis pass no longer detects a finding (for example after you enable 802.11r in UniFi), the item moves to Recently resolved — “no longer detected”. That is the app observing your fix land, which is as close as a read-only tool can honestly get to “done”.
Use this as the start and end of a session: acknowledge what you're taking on, make the change in UniFi, and watch it resolve here on the next pass.
Roaming & Reconnects Tab
This tab identifies clients with problematic roaming behaviour. A healthy roam takes under 50 ms with 802.11r; without it, roams can take 500 ms–3 s, causing call drops and stream buffering.
Roaming Anomalies flags clients exceeding your configured roam rate thresholds (default: 3/hr warn, 5/hr crit). The table shows roam count, three reconnect-gap statistics, and call impact flag.
p50 GapMedian reconnect time across all disconnect/reconnect pairs. Represents typical behaviour. Below 3 s is generally transparent to users.
p95 GapNear-worst-case — 95% of roams were faster than this. The key call-quality indicator. Above 5 s means 1-in-20 roams will drop a Teams or Zoom call.
Max GapLongest single observed gap. Compare with p95: if max is much higher than p95 it's likely an outlier (DFS switch, brief AP restart). If both are elevated, reconnects are systematically poor.
Rapid Reconnects catches clients that disconnect and reconnect within a short window repeatedly — a sign of driver issues, poor coverage overlap, or a failing AP.
A client that roams often between the same two APs is a "roam ping-pong" — usually caused by near-equal signal strength and no sticky or min-RSSI threshold set on the SSID.
Sticky Clients Tab
A sticky client remains associated to an AP despite having a weak signal, when a closer AP would offer much better performance. Common causes: 802.11r not enabled, SSID has no Min RSSI configured, or the client's roaming aggressiveness is set too low.
A no impact tag next to the severity means the client still reports ≥80% satisfaction despite the weak signal — usually a stationary device at the edge of coverage rather than a user with a problem. The controller exposes no per-client neighbour measurements, so Spectra IQ does not guess which AP a sticky client should roam to; to answer that with real evidence, open the client and run the WiFi Walkthrough Tracer.
RSSI
−55 dBm Excellent
−65 dBm Good
−72 dBm ⚠ Warn
−82 dBm ✕ Crit
Sticky warning and critical thresholds are configurable in Settings → Client Sensitivity. Clients below warning are flagged in the table; clients at critical are highlighted in red.
RSSI Thresholds Tab
A dedicated view of the three-tier enforcement stack — Roaming Assist (802.11v transition request), Min RSSI (deauth weak existing clients), and Interference Blocker (refuse weak new associations) — across every AP radio and every SSID. The "5 GHz Alignment" column flags inverted setups, where Roam Assist fires after Min RSSI, defeating the whole point of layered enforcement.
A well-tuned config has Roam Assist at −72 dBm, Min RSSI at −80 dBm, and Interference Blocker enabled — and the same values across every AP so clients don't bounce at zone boundaries.
The RSSI Thresholds tab shows a badge: a green ✓ when every AP radio has Min RSSI enabled and correctly layered, or a yellow ! when any radio has Min RSSI disabled, partial, or inverted. Each coverage-summary widget also carries a status-coloured top stripe.
AP Health Tab
Each AP is shown as a card with a composite health score (0–100, graded A–F). The score is deducted for: high channel utilization, low client satisfaction, sticky/struggling clients, and roaming instability.
AP cards show channel, client count, utilization bars (2.4 GHz / 5 GHz), and any active alerts. Purple border = DFS channel in use (risk of radar-triggered outage). Red border = AP offline.
Utilization bars show green (normal), amber (elevated), or red (congested). High channel utilization means clients are competing for airtime — consider changing channels or reducing neighbour interference.
Reading Per-Radio TX Power
Each radio row on an AP card surfaces the channel, current transmit power, and utilization on a single line:
5 GHz — Ch 36
DFS
·
17 dBm
MEDIUM
23% util
TX power is shown as the absolute value (e.g. 17 dBm) followed by the UniFi controller's relative-mode preset as a chip:
AUTO
UniFi adjusts power dynamically based on observed conditions. Sensible default for most home and small-office deployments. Typically lands between 6–23 dBm, respecting any min_txpower / max_txpower bounds you've configured.
LOW
Typically 3–6 dBm. Use in dense multi-AP environments where two APs cover the same area — smaller cell size forces clients to roam earlier to the nearest AP.
MEDIUM
Typically 14–17 dBm. Balanced setting for room- or floor-scale coverage. Most mixed environments land here.
HIGH
Typically 20–23 dBm (radio max). Use for large rooms, single-AP coverage, or outdoor APs. Watch out: a too-loud AP causes clients to cling at the cell edge instead of roaming to a closer AP — a common cause of sticky clients.
CUSTOM
Manually set in the UniFi controller — read the absolute dBm value next to the chip for the exact figure. Click the AP card to open the detail modal for full per-radio configuration.
DISABLED
Radio turned off entirely. The radio row still appears so you can confirm the intended state.
If clients are flagged on the Sticky Clients tab with the same AP showing HIGH on its 5 GHz radio, lowering that radio to MEDIUM is often the fix — the AP is over-projecting and clients stay attached past the point where they should hand off.
Config Audit Tab
The Config Audit checks each SSID against a set of best-practice rules for roaming, call quality, and security. Each SSID gets a score (0–100), a colour-coded top stripe, and a list of specific findings. Click any check to open a detail modal showing the recommendation, the setting's location in the UniFi Network app (with a search term), and a link to the relevant UniFi help article.
47
71
94
Score rings: red (<70) = critical gaps, amber (70–84) = warnings, green (≥85) = healthy. Each finding includes a specific remediation recommendation.
Common audit findings include: 802.11r (Fast BSS Transition) not enabled, PMF not configured, minimum data rate not set, band steering not active, and MCS rate tables not optimised for the deployment environment.
Click into any finding to expand the full remediation guidance, including the exact UniFi controller path to make the change.
Customising the score — not every check matters on every network. Open Settings → Network & AP → Config Audit Scoring and switch off any metric (e.g. UAPSD, or 2.4 GHz data-rate floors on an IoT network). Deselected checks still appear on the card greyed out as “not scored”, but no longer raise or lower the percentage — so the score reflects what you care about.
Wireless Clients Tab
A sortable, filterable table of all currently associated wireless clients. Each row shows: hostname, IP, AP association, signal strength (RSSI), data rates, uptime, and capability flags.
RSSIReceived signal strength in dBm. Below −72 dBm is flagged; below −82 dBm is critical. Click a row to see the full event history for that client.
SatisfactionUniFi's 0–100 score calculated from SNR and data rates. Below your configured threshold (default 50%) is flagged in amber.
Capability badgesAX = Wi-Fi 6, AC = Wi-Fi 5, r = 802.11r Fast Roaming capable.
Row colourRed-tinted rows have critical issues; amber-tinted rows have warnings. A red left border indicates the most severe clients.
Click any client row to expand its event timeline — a chronological log of connects, roams, disconnects, and auth events for that specific device over the last 24 hours.
Hover any row to reveal the Trace button — click it to open the WiFi Walkthrough Tracer for that device.
See the Walkthrough Tracer tab for a full guide to the on-site coverage and roaming survey tool.
What the Walkthrough Tracer Does
The Walkthrough Tracer turns a single client device into a live site-survey probe. While it runs, Spectra IQ polls the UniFi controller for that one device several times per second and plots how its signal, AP association, data rates, and satisfaction change as you physically carry the device around the building.
It answers the questions a static dashboard can't: Where does coverage drop off? Does the device roam to the right AP at the right time, or cling to a distant one? Where do calls break up?
Starting a Trace
1 · Pick a deviceOpen the device you'll walk with (ideally the phone or laptop you're testing calls on): use Find client in the header, or click its row on the Wireless Clients tab. In the client modal, press Start WiFi Walkthrough Trace.
2 · Press ▶ StartSampling begins immediately and the charts start filling in. Leave the dashboard device stationary and walk the traced device through the space.
3 · Walk a routeMove at a normal pace through every area users occupy — desks, conference rooms, stairwells, and the dead zones people complain about.
4 · ⏸ Stop & reviewStop when finished. The charts and guidance remain on screen for review. Clear resets the session; ↓ Export saves it.
Live Stats Bar
Across the top of the tracer, a row of live readouts updates with every sample:
SignalCurrent RSSI in dBm, colour-coded against your sticky-client thresholds.
Last AP / Current APWhich access point the device was on and which it is on now — the pair changes the instant a roam happens.
Suggested APA heuristic hint for the AP with the best average signal seen this session. It is a suggestion only — UniFi's REST API does not expose real-time 802.11v roaming-candidate data.
SatisfactionUniFi's live 0–100 experience score for the device.
SamplesTotal samples collected this session, with elapsed time. This is the running total — it keeps climbing for the whole walk.
Reading the Charts
Signal StrengthRSSI over time with −72 dBm (warning) and −82 dBm (critical) reference lines. Amber dashed markers flag each AP transition, annotated with the AP name.
Data RatesTX (solid) and RX (dashed) PHY rates together. A throughput collapse at the edge of coverage shows up here before the connection actually drops.
SatisfactionThe 0–100 score over time with a 50% warning line. Sustained dips below 50% correlate strongly with user-visible degradation (choppy calls, buffering).
AP Association TimelineA colour-coded bar showing which AP held the device and for how long. The roam count and sample count appear beneath it.
Guidance Panel
Below the charts, the guidance panel interprets the data in real time so you don't have to. It classifies current signal quality, detects improving or declining trends, judges whether each roam was healthy (signal improved) or a downgrade (signal dropped), and flags sticky behaviour when the device sits on a weak AP for 15+ samples without roaming — the signature of a missing minimum-RSSI threshold.
Sampling Rate & Session Length
By default the tracer samples twice per second (every 500 ms). You can change the sample rate (10 Hz down to 0.2 Hz) under Settings → Client Sensitivity → WiFi Walkthrough Tracer. Faster sampling captures brief roam glitches; slower sampling stretches a session over a larger area.
The charts retain roughly the last 42 minutes of full-resolution history at the default rate; beyond that the oldest points scroll off the graphs, but the Samples counter keeps counting the full session so you always know how much data you've gathered.
Exporting Results
Use ↓ Export to download every collected sample as a CSV — ideal for documenting a site survey or sharing with a client. Each row includes timestamp, elapsed seconds, RSSI, AP name, TX/RX rates, satisfaction, channel, and SSID.
For best results, pause briefly at each AP location and at the midpoints between APs. Those transition zones are where you'll see whether roaming triggers (minimum RSSI, 802.11r, 802.11v) are tuned correctly — if the device clings to a distant AP across a midpoint, that's a sticky-client problem to fix in Config Audit.
RF Neighbors Tab
Shows all Wi-Fi networks detected by your APs in their RF environment — other APs broadcasting in range. High neighbor density on the same channel causes co-channel interference (CCI), which degrades throughput for all devices on that channel.
Channel cells are colour-coded: teal = your channel, red = conflict (same channel, strong signal), amber = adjacent channel. Empty cells are unoccupied.
RSSI values for neighbours are shown in the table. Strong neighbours (above −70 dBm) on the same channel cause the most interference. The tab also shows a per-AP channel breakdown with occupancy counts to help you choose the cleanest channel.
Tuning Tab
The Tuning tab provides a Wi-Fi census of your client population, quick-win recommendations, and channel planning tools.
Census bars show the distribution of your clients by: Wi-Fi generation (6/5/4/legacy), frequency band (5 GHz vs 2.4 GHz), and protocol capabilities (802.11r, PMF). Hover over any bar to see the individual device names in that category. Use this to understand whether your SSID configuration is appropriate for your actual client mix.
The Channel Planner shows all channels as colour-coded cells (teal = yours, amber = neighbours only, red = conflict). Below it, the Channel Coherence panel flags own-AP co-channel collisions (multiple of your APs on the same channel) and non-standard 2.4 GHz channels (anything other than 1, 6, or 11).
Quick Wins at the top surface the highest-impact actionable changes: missing 802.11r, unconfigured Min RSSI, DFS exposure, SSID proliferation. Clicking a quick win card jumps directly to the relevant config or opens the relevant modal.
DFS Analyzer Tab
DFS channels (52–144) roughly double your usable 5 GHz spectrum — but they're shared with weather and military radar. If radar is detected, the AP must legally vacate within seconds, dropping every client for 1–10 minutes. The DFS Analyzer answers the question the native UniFi UI can't: is it actually safe to use them here?
It blends three signals into a per-channel verdict: radar-detection history from your logs, neighbour congestion on each 80 MHz block, and live channel utilisation (from an RF scan when on LAN). The result is a colour-coded matrix:
Safe = no radar history, low congestion · Caution = weather-radar band or busy · Avoid = radar detected recently.
The readiness banner at the top gives an overall Go / Caution / No-go call and recommends the single cleanest channel to deploy. A radar-history list shows every DFS channel-change event in the observation window.
On cloud-only sites (no LAN reachability) the analyzer still works from radar history and neighbour data — it just shows a “heuristic” badge instead of “live RF scan”.
DFS Channel Exposure (Config Audit Tab)
When any of your APs are operating on DFS (Dynamic Frequency Selection) channels, the DFS Channel Exposure section appears below the SSID audit cards in the Config Audit tab. It lists each DFS band in use (UNII-2A, UNII-2C), radar event counts, and the SSIDs affected. DFS channels can cause sudden outages when radar is detected — the AP is required by law to vacate the channel immediately, which disconnects all clients until it reassigns to a clear channel.
If DFS is intentional, enable Known DFS deployment in Settings → Network & AP to suppress warnings. If it is not intentional, the section includes recommended non-DFS channel alternatives.
Mesh Tab
Shows the uplink topology of your UniFi APs — which APs are wired (ethernet uplink) and which are wirelessly meshed to another AP. Each link shows signal strength, throughput, and hop distance. The Mesh tab is hidden automatically when no wireless uplinks are detected.
Mesh links with RSSI below −70 dBm or throughput below 100 Mbps can become bottlenecks. Consider adding a wired ethernet backhaul or repositioning the meshed AP closer to its parent.
Debug Tab
Admin-only diagnostics for the alerting stack — it answers "will we actually be told when a site goes down?" by proving it rather than assuming it. The Gateway Outage Simulator picks any watched site and forces it to be seen as offline, so the real offline threshold, the real dispatcher and the real Teams/SMTP/Mailgun channels all run. Page now backdates the outage past the threshold so it alerts within seconds; Full timing runs the real clock and verifies the threshold itself. Click Verify receipts to see exactly what each channel recorded, then Stop to release the site and fire the recovery notification.
The same panel can force the once-a-day device digest to build immediately (the only practical way to read one while it is in log-only mode), rebuild the watch-list, force a poll, probe each cloud API key for expiry, inspect the persisted alert state, and preview which sites a siteNameExclude term would stop alerting on before you save it.
Simulated alerts are real sends to your real channels, marked [SIMULATED] in the subject and card title so nobody treats a drill as an outage. Tick Dry run to render each channel's exact message without sending anything. A simulation releases its site automatically after 30 minutes, and a Settings save restarts the monitor and ends any simulation in progress.
Display Tab — Themes
Choose from 18 colour themes via the theme dropdown — 9 dark (Spectra Dark, Rosé Pine, Rosé Moon, Nord, Tokyo Night, Emerald, Sapphire, Garnet, Amethyst) and 9 light (Spectra Light, Rosé Dawn, Catppuccin Latte, Nord Light, Solarized, Ocean, Amber High, Forest, Crimson). The selected theme applies live as you browse the list, so you can preview each in real time. To adjust text size, use your browser's built-in zoom (Cmd +/- on Mac, Ctrl +/- on Windows).
Display Tab — Card Trend Graphs
When Card trend graphs is on, each Overview stat and Key Insights card shows a mini sparkline at the top tracking that metric over time. History accumulates in your browser as the dashboard polls (so graphs start sparse and fill in over the session) and is kept across reloads. Toggle it off for a flatter, number-only layout.
Display Tab — Banners
Hide connectivity banner suppresses the amber "Connectivity issue detected" banner at the top of the dashboard entirely. Without the setting, dismissing the banner with its ✕ now sticks across page reloads — it returns only when the server restarts or the issue list actually changes (a new failing site, or one recovering), so a dismissal can never hide a new problem.
Display Tab — Tooltips
Disable tooltips turns off all hover tooltips throughout the dashboard. The Hide tooltips below width slider suppresses tooltips only when the browser viewport is narrower than the chosen width — handy on phones and tablets where hover tooltips overlap the layout. Set it to 0 to always show them; it works independently of the on/off toggle.
Display Tab — Activity Chart Style
Controls how the Activity Pulse sparklines on the Overview tab are drawn. Bars (default) show discrete per-bucket counts and use heat coloring on the All-Events sparkline. Line emphasises trend without bar-by-bar noise. Area adds a soft fill below the line. All three modes share the same hover-tooltip data — only the visual style changes.
Display Tab — Time & Dates
Relative timestamps throughout the dashboard (e.g. "5m ago") display the absolute time on hover. You can configure the timezone and 24-hour clock format to match your location. The header date can be set to Friendly, Full, ISO, or hidden.
Client Sensitivity Tab
Sticky RSSI warnClients below this signal level are flagged as sticky (default −72 dBm). Lower = fewer flags; raise to catch more marginal clients.
Sticky RSSI critCritical threshold (default −82 dBm). Clients at this level are experiencing severe degradation.
Satisfaction warnUniFi satisfaction score below which a client is flagged (default 50%). Strongly correlated with RSSI below −70 dBm.
Rapid reconnectWindow (seconds) and minimum count to flag a reconnect loop. Default: 2 reconnects within 30 s.
The live health gauge at the top of the Client Sensitivity tab shows how your current settings affect the overall health score in real time as you adjust sliders. The impact chips next to each slider show how many clients are currently affected.
Network & AP Tab
Utilization warnAPs with average channel utilization above this are flagged (default 70%). Lower = stricter; useful for high-density deployments.
AP satisfactionAverage client satisfaction across an AP. Below this level the AP is flagged (default 65%).
Roam rateClients roaming above the critical rate (default 5/hr) or warning rate (default 3/hr) are flagged in the Roaming tab.
Reconnect windowRoam reconnect time above the critical window (default 30 s) or warning window (default 15 s) is flagged as a slow roam.
Known DFS deploymentToggle on if your APs intentionally use DFS channels and the occasional radar-triggered channel hop is acceptable. Suppresses DFS warnings and the AP health score penalty — DFS channel indicators are still shown on AP cards.
Include DFS channels in channel recommendationsOff by default. When off, the RF Neighbors channel planner only recommends non-DFS channels (UNII-1: 36–48 and UNII-3: 149–161), avoiding radar-sensitive bands. Enable to also evaluate UNII-2A/2C DFS channels (52–144) as candidates.
Gateway Monitor Tab
Controls the optional background service that watches gateway/router uptime across every configured cloud account and feeds the Fleet tab. It is read-only — the monitor only issues GET requests to UniFi's Site Manager API — and disabled by default. Saving here applies the change and restarts the monitor without a server restart. Admin-only when authentication is enabled.
EnabledMaster switch. When off, no timers run and no API calls are made.
Offline thresholdHow long a gateway must be continuously offline before an alert fires (default 5 min).
Poll intervalHow often gateway status is checked (default 300 s).
Watch-list refreshHow often the set of watched sites/gateways is rebuilt, picking up newly added sites (default 24 h).
Site name filter / excludeInclude only sites whose name contains a substring, and/or skip sites matching any entry in the exclude list — the usual way to drop decommissioned sites, e.g. (INACTIVE).
Alert on startup-offlineTurn off to record gateways that are already down at first poll as known-offline without paging — prevents an alert burst on first run across a large fleet.
Repeat alerts / Send recoveryOptionally re-alert while a gateway is still offline, and/or notify when one comes back.
Debug loggingVerbose per-cycle logging to the server console, narrowable by category. State transitions and alerts always log regardless.
A failed, timed-out, or rate-limited API call is never treated as a device going offline — only an explicit offline signal in a successful response advances an outage. A cloud hiccup can't page you about the whole fleet at once. Alert state is persisted, so a restart doesn't lose an in-progress outage timer or re-fire an alert already sent.
Notifications Tab
Where the gateway monitor's alerts are delivered. Three independent channels — Microsoft Teams, email over SMTP, and email over the Mailgun API — and every enabled one fires for the same alert. Enabling both email channels sends two emails; pick one. A field set stays collapsed until you enable its channel.
Secrets (Teams webhook URL, SMTP password, Mailgun API key) come from environment variables on the server, never from the settings form or config.json. A value supplied by the environment is flagged in the form.
TeamsIncoming webhook. Choose the webhook type to match your URL: workflows (Power Automate — sends an Adaptive Card) or connector (legacy Office 365 — sends a MessageCard). The wrong type renders nothing.
SMTPHost, port, from and to. Useful for opening a helpdesk/PSA ticket alongside the Teams card.
MailgunThe same email over Mailgun's HTTP API — for hosts where outbound SMTP is blocked. Set the region to eu if the account was created there, or a valid key is rejected with a 401.
Save & send testSaves the panel, delivers one real notification through that channel, and reports the outcome inline — including the provider's own error text. Clearly marked as a test, so it won't read as an outage.
The live monitor deliberately swallows per-channel delivery errors so one bad sink can't suppress the others — which means a misconfigured channel is invisible until an outage. Send test is how you find out before then.
Backups Tab
Admin-only. Takes compressed snapshots of the history store on a schedule, using the engine's own consistent-snapshot tooling — pg_dump under PostgreSQL, SQLite's online backup API under the local-dev fallback — so an archive is a consistent image even if it is taken while the app is writing. Copying the database file instead is one of the ways a torn, unusable image gets made.
Every archive is opened and integrity-checked before it is stored, and again before a restore is applied. The row counts that check produces are recorded in the archive, so the restore prompt can tell you what is actually in it rather than just a filename.
ScheduleRuns on a timer while the server is up. A window missed because the host was down is caught up shortly after the next boot rather than skipped.
Keep at mostThe same ceiling mechanism as the history store cap — oldest archives are dropped first, 0 means unlimited. The newest archive is never deleted, even if it alone exceeds the cap.
DestinationDefaults to <data dir>/backups. Its writability and free space are shown live. Archives beside the database protect against a corrupt store, not against losing the volume — point this at a mounted share for that.
RestoreVerifies the archive, then stages it and applies it on the next restart. The swap happens when nothing holds the database open, which is the only moment it is safe. The outgoing database is kept, so a restore can be undone.
Archives contain the durable settings mirror — including the controller session cookie — and the scrypt password hashes in the database. They are written 0600 and should be treated as credentials wherever they are copied.
Tab Order Tab
Drag the tab rows to reorder the main navigation tabs across the top of the dashboard. Toggle the ● / ○ eye on any row to show or hide that tab — hidden tabs disappear from the nav (Overview always stays visible, and hiding the tab you're currently on drops you back to Overview). The order and visibility are saved to your browser and applied immediately.
Users Tab
Only present for admin accounts when authentication is enabled (otherwise the tab explains how to turn auth on). It manages user accounts: create a user, set their role, reset a password, disable or re-enable, or delete.
adminSees every site, and can manage users, controller connections, and monitor/alerting config.
viewerSigns in with their own credentials and sees only the sites an admin assigns. Requests for other sites are refused by the server, not just hidden in the UI.
The last active admin can't be demoted, disabled, or deleted — so you can't lock yourself out. Controller keys and per-site LAN settings are edited separately, in Controller Connection → Sites.
Version History Tab
Shows the git commit log grouped by date, so you can see what changed between deployments. Only available when the server is running inside a git repository.
About Tab
Shows the application name and a link to the GitHub repository.
All display preferences and thresholds are saved per-browser. Use Reset to defaults at the bottom of any settings tab to restore the recommended values.
Authentication
Spectra IQ supports optional password protection. Authentication is disabled by default — no change in behaviour unless you opt in by adding an auth block to config.json:
{
"auth": {
"enabled": true,
"password": "your-password-here"
}
}
After adding this and restarting the server, visitors see a login screen before any dashboard data loads. Sessions last 24 hours and slide on activity — active users stay logged in automatically. A sign-out button appears in the header when auth is active.
The password in config.json is the bootstrap admin credential, meant to get you in far enough to create real accounts — see Multi-user access below.
Session storageSessions are persisted in the durable store (PostgreSQL in Docker/production, SQLite in local development), so a server restart no longer signs everyone out. The cookie is httpOnly and SameSite=Strict — not readable by JavaScript and never sent cross-site — and gains the Secure attribute automatically over HTTPS (including behind a reverse proxy that sets X-Forwarded-Proto).
Password storageAccount passwords are hashed with scrypt (salted, memory-hard) and verified in constant time; they are never stored or returned in plaintext. A legacy plaintext config.json password is still accepted for backward compatibility and treated as the bootstrap admin — keep config.json out of version control either way.
What is protectedSite-specific data routes are gated, admin endpoints are admin-only, and config writes require an admin. The health endpoint, site list, changelog, and the login endpoint itself stay reachable so the dashboard can self-discover and present the login screen with no valid session.
Brute forceRepeated failed logins from one IP are rate-limited with a temporary lockout.
Multi-user access
Beyond the single shared password, Spectra IQ supports per-user accounts with roles, managed in Settings → Users — no need to run separate instances per audience. Admins see everything; viewers sign in with their own credentials and see only the sites you assign them.
To set it up: enable auth with a bootstrap password, restart, sign in as admin, then create accounts in the Users tab.
Once the first account exists, login switches to username + password and the shared bootstrap password stops working — so create at least one admin account before you rely on it.