Querying UniFi channel utilisation

I recently needed to do some optimisation work on a Ubiquiti UniFi setup. Some workloads were causing the capacity of a single AP to be exceeded, or more precisely, the channel was getting so fully occupied that connections were beginning to drop. I was trying to evaluate whether a particular configuration would fix the problem and it was slightly annoying. The UniFi web console does report channel utilisation but it makes it hard to see the actual numbers (mouse hover) and it updates extremely lackadaisically. I wanted hard data, dangit.

Happily for me, this information can be had with a little effort. First we must enable SSH access to the AP under site options. This lets me shell in and run commands directly on the device.

The AP has a number of custom utilities starting with the prefix mca-. The one that’s relevant to us today is called mca-dump. This outputs an enormous blob of JSON containing all the metrics for the device including all the radios and connected stations, in the order of 600 kB in my case.

After combing through this data it was clear that each WiFi radio had its own block of statistics, identifiable by the channel information. I was interested in the 5 GHz channel which turned out to be keyed under the interface name wifi1. Harder to find were the utilisation statistics; they use the acronym cu which makes sense in hindsight but didn’t stick out while reading the JSON.

Putting this together, we can process it with a tool like jq to get the information we want.

$ ssh $AP mca-dump | jq '.radio_table[] | select(.name == "wifi1") | .athstats | {cu_self_rx,cu_self_tx,cu_total}'
{
  "cu_self_rx": 0,
  "cu_self_tx": 1,
  "cu_total": 1
}

Although this data is not documented anywhere that I could find, my understanding is that these values represent the percentage of time the AP spends receiving and transmitting respectively, plus the total utilisation of the channel including interference.