The rules¶

Every rule the engine judges with, in the order it runs them, with what each observes, the outcome it gives, why it sits where it does, the setting in the Mist portal that addresses it, and the recordings that confirm it. Reading the verdict explains the same in plain words.

HintEngine picks an outcome from the fixed set: AP side, client side, RF environment, upstream / not Wi-Fi, measurement limit, undecided. Each hint shows its metrics, thresholds and sources. The thresholds live in HintConfiguration; the initial values are assumptions, to be calibrated on the testlab sessions and the cases from the field.

• Checks. Each rule is a function that finds a hint, passes, or says why it could not run: "too little traffic", "no login captured", "the client's ACKs not in the capture", "AP not heard" ("client not seen" while the client has no BSS yet, its AP's beacons in or not), "client not seen", "no other AP of the network heard", "no 5 or 6 GHz of the network heard", "bands of the client unknown", "client away from the sensor", "no Mist", "no DHCP or DNS from Mist", "no roam", "not seen by the sensor" (a roam between the radios), "reason encrypted (PMF)" (of a disconnect), "retries and rates not measurable", "no capture statistics". A rule that does not apply passes: the RADIUS server with a pre-shared key, the asymmetric link with the AP weaker than −60 dBm at the sensor. A found hint goes before a missing input: a stalled 4-way is a login captured. In a window across a search of the live session for the client (SessionAnalyzer.searches) the three loss rules say "client not seen": the losses as it left and came back do not judge the link, and the scan finds none there. Per reason the step at the desk that lets its rule run, or why there is none, is in HintEngine.remedies (Hints/Steps.swift), which the Overview's Next and the report's "What the recording lacks" read (the app): presentation, not a verdict.
• The decision. The rules run in order of priority: the measurement, then what ends or blocks a connection, then the causes of a poor link (roaming, coverage, the channel), then the losses they cause. The first hint with a side decides; the others follow as found as well, and one with another side is marked as pointing elsewhere. An observation without a side (outcome undecided) does not decide: losses with nothing to compare, losses towards the AP without Mist or without interference in Mist, losses the reference client does not have, a login that fails for the reference client too (the losses below the table). It names in its text the side it points to where it points to one, "it points towards the AP, unconfirmed", or the candidates where they lie on more than one side. A finding that points elsewhere never overrides the deciding one, however severe: otherwise the order no longer predicts the verdict (the column "Why here" of the table). With only observations the outcome is undecided and the first one is the reason; without any hint the reason is "Nothing abnormal found." with the questions that stayed untested, or "Too little data." when all did. A note (Hint.note) is seen and worth knowing, not abnormal: it neither decides nor makes its question poor, follows the findings, and its question's readout names it (a note of frames sent again by its number, "17% sent again", the note in full in the readout's help); with only notes the reason is "Nothing abnormal found.".
• A verdict per question. Connection (association, login, disconnects), AP to client, client to AP, coverage, roaming and channel. A question is poor when one of its rules found something, not when it only noted something. Otherwise it takes its grade from its number where it has one (Block Ack success; the AP at the sensor; the channel's QBSS load once congestion ran, Fair from qbssHigh (60 %), Good below it or without one, so a desk on a loaded campus channel never reads Good, and Poor from the finding alone), or is good when a rule that judges it ran: any rule of the connection, the roam rules or the sticky client for roaming (not the probe storm or the band choice alone: neither judges a roam). Without that it is untested. Block Ack success grades delivery: what reached the recipient, an A-MPDU lost whole and delivered on a retry among it, as no Block Ack reports that loss. The share sent again is the airtime the delivery cost: it stands beside the grade and moves it only as a loss rule's finding, since one grade for two measures would hide which of them is poor (the AP45 sent each A-MPDU to the phone three times at 98.6 % BA success). The AP at the sensor stands for the client's coverage only with the client near the sensor: below clientNearSensor the coverage question is untested, as its two rules are, and Mist's client RSSI at the AP, the other direction at another receiver, stays beside it and grades nothing. The delivery readouts name what their grade judges ("99.1% delivered"), the share sent again over the same span under it, in Fair's color from retransmitHigh. Each question lists what its rules could not check. Without a finding the outcome is undecided, and the reason is "nothing abnormal found" only while no question is poor; a question poor by its number names itself, poor without a finding, with the text of its note where it has one.
• Windows. HintFacts covers the whole session or a TimeWindow of it: the metrics from the per-second buckets that start in the window (BA success, capture share, retry bit, rates, airtime, the client's signal), the AP's and the neighbors' signal from the beacons heard in it (the AP's from minimumBeacons (20) beacons and probe responses on, in the window or the session, so its coverage question and readout are untested below that once the client's BSS is known, with "too few beacons of the AP" where its BSS was heard and "AP not heard" where not; a neighbor or co-channel radio not heard in it, as in focus, with its signal over the session), the channel utilization the AP reports in its BSS Load (QBSS) as the mean of its beacons in it, the events, handshakes, EAP exchanges, roams and anomalies within it, and the serving BSS, profile and AKM as of its end: without a (re)association before the end, the BSS of the client's data at the end, not that of the session's end. The client's signal at the sensor is the session's in a window without its frames, and "roamed" counts every roam attempt at or after the window's start, completed or not. The drops of the capture are the session's, whatever the window. HintEngine.report judges the whole session and sliding windows of windowLength (20 s) every windowStep (5 s); per rule the window with the largest Hint.severity (the loss, the dB past the threshold, the load of a busy channel) is the one shown, the whole session on a tie, so a problem of twenty seconds in ten minutes is not averaged away. The hint also lists every stretch where its rule found it (Hint.windows, its windows merged where they overlap: a finding's findings, a note's notes), which the time axis draws; a rule that counts events lists the moment of each event instead (Hint.times, each window's first, Hint.time the first of all). The windows lie on the grid within the session, plus, once the session no longer grows, one more on the grid that takes in the last interval: live and in a replay before its end a window is judged once it is full, so a finding's window never moves back. Rules that exclude each other within one set of facts (the three loss rules; sticky client and weak coverage; the two SAE rules) can each find a hint in another window: the report keeps one per group, the most severe loss, else the first in priority. A finding of a rule takes the place of its note from another window, however severe the note; a note excludes nothing. A hint found in a window names it (Hint.window) and makes its question poor; a hint about an event (a login, a disconnect, a refusal, a roam, a channel switch, a probe storm) names its moment (Hint.time); what a rule could not check, it checks over the whole session. A report over a chosen window judges that window only.
• Disconnects. Who ended a connection comes from the order of the frames, which PMF and the 4-way fix whatever the vendor: the client's own frame is the client's; the AP's within 1 s after the client's EAPOL-Logoff (encrypted after the keys, known by its size) or after its own disconnect is the client's; the AP's protected one while a radio listened on the link through the second before, and nothing of the client leaving in it, is the AP's own; the AP's in the clear on a connection with keys and PMF says only that the AP dropped the keys first. The client's own disconnect within 1 s after an AP's disconnect the client began is the rest of its leaving (restOfLeaving): the phone's protected disassociation after its SA Query to the AP45's reason 36 in the clear went unanswered; its encrypted reason leaves no question untested. A reason code is a label: the standard defines what each code means (IEEE 802.11-2020, 9.4.1.7), not which one an AP sends when. After the frames it decides a side only where the standard ties it to one event and its class gives one (the sender's 3 and 8, the AP's 5, 6 and 7), and then where a vendor's use of it was measured (Mist's 2 for the portal's Reconnect, 23 and 36 after the client's logoff; UniFi's 1 for a kick). With a vendor whose codes were not measured, a reason alone gives no side: undecided, with the order of the frames shown. The rules read the class of a code, not its number; the table, the classes, the measured uses and how the vendor is known are on reason codes. The hint's text and its evidence ("who began") name what decided: the frames, the standard or the vendor's measured use, or "reason codes not measured for this vendor".
• The measurement limit comes first: drops of at least 1 % of what linkside-cap received over the session, or at least 100 on one radio within a second, summed over every restart of the capture. Gaps in the sequence numbers are shown but are no measurement limit: UL OFDMA always produces them. So is a radio that heard the client on 5 or 6 GHz through a USB 2 port (SessionAnalyzer.slowPorts): a busy channel does not fit through it and the radio loses frames that no counter shows (sensor-link.md).
• The retry bit and the MCS of a direction count only with a capture share of at least 90 % in that direction (minimumCaptureShare): with the fast frames of five recordings dropped, the retry bit left the whole direction's by more than 2 points from 76 % up and from 93 % down, the median MCS fell by one from 75 % (eht-capture.md). And only with enough Block Acks for its BA success: without them a few null frames with the retry bit read as 100 % retries (testlab-co-channel, before the traffic).
• A session is recorded because a user has a complaint; the app does not ask whether it remains. With nothing found the verdict reads "Nothing abnormal found.", after Stop also the Overview's headline, not "No clear cause"; beside a note "No finding, only notes." and on the Overview "No finding", as a note can read a third of the frames sent again, which "nothing abnormal" would talk over. Either way a clean link, the cause beyond the Wi-Fi or at the client itself (a laptop at full CPU), which the sensor cannot tell apart. wifi-fine, which named upstream by elimination, was removed on 2026-10-26. An answer to the former "Problem still there" in an older session.json is ignored when read.
• The reason of an encrypted disconnect comes from a Mist client event of the same kind within 3 s, after the clock correction, on the same BSS where Mist names one; the evidence names Mist as its source.
• The report names under each finding the lever on the network side (HintEngine.levers, in Hints/Levers.swift, the table's column Lever): the setting in the Mist portal, by its label there (checked on the Mist test site, 2026-10-23). On the WLAN's page: Fast Roaming (Default, Opportunistic Key Caching (OKC), .11r), Band Steering, Radio Band, Minimum client RSSI per band under Geofence (with Block clients having RSSI below the minimum), Data Rates (Compatible, No Legacy, High Density, Custom Rates) and Security Type (WPA3 or OWE, Enterprise (802.1X) or Personal (SAE), Enable WPA3+WPA2 Transition). In the band's settings of the RF template (Site > Radio Management): Channel Width, Power (Automatic, or Set power with a min and max) and Channels (Automatic, or Set allowable channels, DFS marked dfs). On the AP's page, the band's Configuration (5 GHz Configuration, Dual Band Radio Config): Channel Width, Channel and Power instead of Use site setting. The portal has no limit on the number of clients (its Client Limit is the Per-Client Rate Limit) and no setting for BTM. The app does not show the lever: it is the remediation line of the ticket. A note names none, and neither does a rule that points at the client where the network does not steer its choice (a missing capability, its credentials, its own disconnect), the sensor or the upstream. A rule that points at the client's choice of AP or band names the setting that steers it: the sticky client, the band choice, the weaker roam, ping-pong. A lever can hold for some outcomes of a rule only: fast roaming for roam-full-login on the AP side, not for the client that skips the 802.11r the network offers. No lever, AP side or RF environment: slow-roam (its wait can be the client's, the AP's or the RADIUS server's), ap-disconnect (reason 2 after a completed login is a person's or a script's Reconnect, the other reasons the AP's decision, not one setting), ap-disconnect-all, beacon-loss and cached-key (the AP's state: a restart, a config push, a key cache it lost), join-unanswered (undecided), and the three loss rules (the channel, which congestion names where it is busy).
• Confirmed in a recording. Per rule the recordings in testdata/sessions that confirm it (HintEngine.confirmations, in Hints/Confirmations.swift, and the last column of the table below): a finding, not a note, with the side its expected.json gives, in a recording that expects a finding, and not of a rule its expected.json names, every finding of it in that recording wrong beside the right outcome (falseFindings); the synthetic sessions confirm nothing. A finding of a rule not listed (Hint.unconfirmed) decides as any other, and says what it rests on: "unconfirmed" beside its title on the Overview, with "Rule not yet confirmed in a recording." under its evidence, in the help of the readout that names it, and in the report under the finding. A note carries no mark. ConfirmationTests recomputes the list from verdict.json and expected.json and checks the table against it: a recording that confirms a rule adds it in the same commit.

In order of priority (HintEngine.rules):

The losses that stay observations, and why. The sensor hears the client's surroundings, not the AP's, so a loss takes a side only from a comparison: the other direction getting through, the reference client on the client's BSS, or Mist at the AP.

• uplink-loss without Mist, or with Mist seeing no interference at the AP (no low client SNR, no util_non_wifi): it points towards the AP, unconfirmed. With the downlink fair or without traffic it has nothing to compare and no side. The client's frames sent again with BA success not low are then a note, as the AP's are towards the client: the readout names the share, the grade stays that of BA success.
• two-way-loss on frames sent again alone, both ways, without the reference client beside it to compare on them: a note, as a phone in normal use sends 20 % again in every window. A jump both ways is a finding: the sender repeats what an oven takes, BA success stays at 99 %, and the share sent again leaves the level the client has without it.
  • The level (UsualLevel): the median of the session's windows on the client's BSS that do not overlap the window judged, from four of them on (levelWindows), of the share sent again and of BA success. A client's level differs per BSS, so a roam starts a level of its own, and a window across it counts for neither, as a window across a search does not. The median is unweighted: a client whose busy windows all sit below 90 % among quiet ones reads as a deep loss, which those windows are. Like against like: Mist's count against Mist's, the retry bit against the retry bit, as Mist's reads higher. Live those are the windows before it; after the end those after it count too, so a window at the start of a session has a level then. Frames sent again alone in a window without one stay a note. A window chosen to look at takes the level of the windows outside it. The figures: the oven.
  • One direction at its usual level is no loss both ways. BA success low the other way, at least 7.5 points under the client's own (levelJump) or with that level below 90 % itself, is a loss that way alone, for downlink-loss or uplink-loss; less is a dip, the note "Losses towards the client" or "Losses towards the AP", as a phone's bursts of wakes give. Over the whole session there is no level, so a loss that lasts is a finding there too. The recordings hold one such window, 89.6 % in a burst of wakes, 5.0 points under the level, and none of the deeper kind.
  • A session needs about a minute of usual traffic on each side of the problem: with 30 s the oven's windows raise the level, and in testlab-intermittent-loss-psk-iphone-moved the jump falls from 9.6 to 6.1 points.
  • An oven takes the sensor's capture of the downlink below 90 % as well, so the AP's side rests on Mist's count: without Mist there is no finding, and live it comes with the count of the oven's minute, 25 and 67 s after the oven's end in the two recordings. Right after wakes is not known of Mist's count, as in downlink-loss, so the condition does not hold it back there. Live, replayed with Mist's polls as they came, the finding followed the note 42 and 62 s later with Mist's count, and without Mist at the end of the oven's windows, and went away again in none of the three oven recordings; ap45-phone-reconnect kept its notes. The stretches of a rule's notes are every window it noted something in, under the title of the worst: a rule has one hint, and a stretch chosen says which note it is.
• two-way-loss and downlink-loss with the reference client getting through on a BSS not known to be the client's: it says nothing about this AP, and the loss points towards the client, unconfirmed.
• downlink-loss with the uplink fair or without traffic: nothing to compare. Losses mostly right after the client's wakes from power save: its power save, the AP's rate after the pause or interference near it, which one session cannot tell apart (testlab-client-leaves-eduroam). Without a reference client on the BSS, frames sent again with BA success not low, or losses after wakes, are a note, as a phone in normal use has them (testlab-long-quiet).
• two-way-loss and downlink-loss with the client weaker than −60 dBm at the sensor: its coverage or interference where it is, which the sensor does not hear (u7-phone-ft-roam).
• low-mcs without the reference client beside it: the client's receiver or power save, the AP's rate control, or interference near the client; with the reference client low too: the AP's rate control or interference here, not the client.

A window that holds the start of a connection judges it with the rest of it: the loss rules hold no seconds after a join back and ask for no more frames than BA success does, and their text and evidence say it ("the window ends 7 s after the reconnect", "the window starts 400 ms after the reconnect"; after the roam or the login; "after the last of its 2 joins"; HintEngine.afterJoin). A window holds it where the keys of a successful join (M4, or the accepted response with FT or without RSN) came at most 3 s before its start (joinStart) and at least a metrics interval before its end, so it holds seconds after them; a window longer than the scan's 20 s, one the user chose, holds none, the start weighing too little in it (HintFacts.Joins.holds). In the recordings the first three seconds after a join's keys carried a few dozen to two hundred of the AP's frames, 15 to 22 % of them sent again after three of five reconnects, where the same phone sends 13 to 34 % again over the rest of its session; leaving out 3 or 5 s moved a window by a few points either way, and would hide a loss right after a join. The window of ap45-phone-video-reconnect that ends 7 s after the reconnect, 29 of 89 frames sent again, most of them in the phone's wakes 5 and 6 s after its keys, is a fair note (power-save.md, 2026-10-31).