The roam matrix
The roam matrix counts how Wi-Fi clients move between your access points. Every time a client roams from one AP to another, RUCKUS One sends a roam event. R1-MCP adds each one to a running tally per AP pair (from one AP to another), so thousands of roams become one row per pair that you can read.
Ask for it in plain words, for example “how do clients roam between the APs on
the second floor?”, or call roam_matrix directly.
Where does the roam matrix data come from?
Section titled “Where does the roam matrix data come from?”From the Webhooks feature, not from a RUCKUS One API call. The matrix is
built from the UserConnectedToAnotherAP (209) events your
webhook receiver stores, as they
arrive.
- No receiver, no matrix. Until webhooks are set up and events have arrived,
there is nothing to read. A floor map reports
no_roam_datarather than a quiet floor. - A pair’s tally runs until the pair goes quiet. It is dropped only after 90 days with no roam between those two APs (and the oldest go first past 40,000 pairs). It is built as each event arrives, so it outlasts the raw event cache.
- Counts are approximate. Webhook deliveries are stored as received and never de-duplicated.
How to read a roam matrix pair
Section titled “How to read a roam matrix pair”roam_matrix returns the pairs busiest first, each going from one AP to
another:
| Field | What it tells you |
|---|---|
count | Roams from the first AP to the second, in total since the pair was first seen |
avg_rssi_delta | Average signal change across the roam. Negative means clients landed on a weaker AP |
neg_delta_ratio | Share of roams that did not improve signal |
pmk_ratio / full_auth_count | Share of roams that used PMK fast roaming, and how many re-authenticated in full |
fst_ratio / fst_count | Share of roams whose client context came through FST rather than the session manager |
band_steer | The two ends are the same AP: a client moving between its radios, not between APs |
placement_concern | More than half of at least 20 roams between two different APs lost signal |
The signal change is in RUCKUS relative units, where higher is stronger. It is not dB. Never compare it with a client’s dBm reading.
Arguments: apMac narrows the matrix to roams to or from one AP. limit sets
how many pairs come back (default 100, maximum 500). window (1h, 6h,
24h, 7d or 30d) chooses which pairs come back: those with a roam in
that period. It does not narrow the counts. With window: "24h", a pair
active today still shows every roam since it was first seen, so read count as
a running total, not a daily rate.
What a placement concern means
Section titled “What a placement concern means”A placement concern flags two APs where clients roam often and mostly end up with a weaker signal. That points at a coverage gap or two cells overlapping between those APs. A band steer is never a placement concern, because it involves only one AP.
The roam matrix on a floor map
Section titled “The roam matrix on a floor map”With the Floorplan feature on, the roams
layer draws the matrix as arrows between
the APs on a floor, with the distance between each pair in metres.
“Clients cross between these two APs often” becomes “…and they are 44.7 m
apart”. roamWindow picks which pairs are drawn, as window does above; the
counts on them are still running totals. The Map roaming on a floor prompt walks through it.
- Arrows point the way clients moved. By default (
roamMode: "signal") they are green when roams gain signal, grey when there is no meaningful change, orange when they lose it, and red for a placement concern. roamMode: "fastroam"colours by fast-roam share instead: blue at 80% or more PMK, grey from 50%, magenta below 50%. The findings are the same in both modes.- A band steer is a ring on one AP, never an arrow.
- Up to 80 arrows are drawn, busiest first. The rest are counted and reported, and roams to APs on other floors are counted, not dropped.
Findings the map calls out:
- A busy pair far apart. Clients roaming directly between two APs more than 35 m apart probably cross a spot with no usable coverage.
- A ping-pong pair. Both directions busy, and neither improving signal.
find_ping_pong_clientsnames the devices doing it. - Full re-authentication. A busy pair where fewer than half the roams used PMK. Each full 802.1X exchange is a gap of roughly half a second or more, audible on a call. Check the WLAN’s 802.11r/OKC setting first.
What the roam matrix cannot tell you
Section titled “What the roam matrix cannot tell you”- Sticky clients. A client that clings to a distant AP never roams, so it never appears here.
- Which device is roaming. The matrix counts pairs. For one client, use
get_client_roams, or theroamTraillayer withroamClientset. - Exact counts, or counts for a period. Deliveries are not de-duplicated, and a pair’s count is a running total whatever the window.