Cisco Catalyst 9800 WLC for Home Assistant

Custom Home Assistant integration for a Cisco Catalyst 9800-CL wireless LAN controller. It tries RESTCONF first and automatically falls back to read-only SSH show commands when RESTCONF is unavailable. It exposes controller and per-AP entities, and wireless client presence trackers.

Tested on 9800-CL version 17.9.4a with CAP-AIR2702I-E-K9.

What it exposes

• Controller sensors:
  • joined AP count
  • disconnected AP count
  • configuration issue count
  • total wireless client count
  • aggregate RX rate and throughput
• Per-AP sensors:
  • uptime
  • client count
  • RX rate and throughput
  • RX bytes and data usage
  • AP detail attributes, refreshed on the AP detail interval
• Client presence:
  • one device_tracker per wireless client MAC
  • AP name, WLAN ID, protocol, role, and last-seen attributes
• Binary sensors:
  • controller problem: any AP disconnected
  • controller problem: any configuration issue
  • per-AP connectivity
  • per-AP configuration status

When RESTCONF is available, directional RX/TX counters are exposed when the controller provides them. When SSH fallback is used, Data Usage from show ap summary sort ascending client-count is exposed in GB. Throughput is calculated from cumulative byte counters as a rolling 10-minute average, so it will be steadier than a single-poll spike. RX-only entities are skipped on SSH fallback because the CLI output does not include directional RX counters.

Install

HACS

Add this repository to HACS as a custom integration repository. For normal HACS installs, the repository must be public on GitHub:

https://github.com/IvanFogel/cisco_9800_wlc

Choose category Integration, download Cisco Catalyst 9800 WLC, restart Home Assistant, then add the integration from:

Settings -> Devices & services -> Add integration -> Cisco Catalyst 9800 WLC

Manual

Copy or symlink the repository contents into your Home Assistant configuration directory at:

<home-assistant-config>/custom_components/cisco_9800_wlc

Restart Home Assistant, then add the integration from Devices & services.

Controller prerequisites

The integration supports two read paths:

• RESTCONF over HTTPS with basic authentication.
• SSH CLI polling with read-only show commands. This is the tested path on the local WLC controller because its HTTPS server responds, but /restconf returns 404 Not Found.

For RESTCONF, a lab controller normally needs at least:

conf t
ip http secure-server
restconf
aaa new-model
aaa authentication login default local
aaa authorization exec default local
username <READ_ONLY_USERNAME> privilege 15 secret <PASSWORD>
end
write memory

Use a read-only TACACS/RADIUS or local user if your AAA setup supports the required operational data permissions. For a lab with a self-signed WLC certificate, leave SSL verification disabled in the config flow.

The SSH fallback uses these commands:

show ap summary
show ap uptime
show ap summary sort ascending client-count
show ap tag summary
show wireless client summary
show wireless stats ap join summary
show ap name <APNAME> config general

On the tested WLC, the <READ_ONLY_USERNAME> privilege-1 account can run these commands. The show ap name <APNAME> config general detail command is only run on the AP detail interval, which defaults to 3600 seconds.

Client Presence

When Track wireless clients is enabled, every client in show wireless client summary is exposed as a Home Assistant device_tracker. Clients stay home while the WLC reports them and become not_home when they disappear from the summary. The WLC may keep idle clients for a short timeout before dropping them, so presence follows the controller's view rather than direct Wi-Fi probe state.

Diagnostics and System Health

The integration supports Home Assistant diagnostics and system health. Diagnostics redact credentials and GitHub tokens, then include controller mode, polling intervals, AP counts, configuration issue counts, and tracked client counts. System health shows the active transport mode, last successful update, AP detail interval, joined AP count, and tracked client count.

Updates

When installed through HACS, use HACS to update the integration. Restart Home Assistant after HACS downloads an update so Home Assistant reloads the Python code.

For manual git clone installs, update from the integration directory with:

git pull --ff-only origin main

Disconnected AP warnings

Joined APs are discovered from RESTCONF capwap-data when RESTCONF is available, or from show ap summary when SSH fallback is used.

An AP that was seen by this integration and then disappears is kept as an entity and marked disconnected. After a Home Assistant restart, only APs that are currently joined, present in controller join stats, or listed in the integration option Expected AP MAC addresses can be marked disconnected.

For stable disconnected warnings, add your AP radio MACs or Ethernet MACs in the options flow. One per line is easiest:

0200.0000.1002
0200.0000.1001

Configuration Warnings

The integration flags APs with configuration issues when show ap tag summary reports Misconfigured as anything other than No. In RESTCONF mode it also checks AP audit, tag, sync, profile, and config-related fields for failure-like values such as failed, mismatch, out-of-sync, not found, invalid, or error.

Cisco exposes these details differently across IOS XE releases, so the binary sensor includes the matched reasons as attributes for troubleshooting.

Useful RESTCONF data paths

• Cisco-IOS-XE-wireless-access-point-oper:access-point-oper-data/capwap-data
• Cisco-IOS-XE-wireless-access-point-oper:access-point-oper-data/ap-name-mac-map
• Cisco-IOS-XE-wireless-access-point-oper:access-point-oper-data/ssid-counters
• Cisco-IOS-XE-wireless-access-point-oper:access-point-oper-data/ethernet-if-stats
• Cisco-IOS-XE-wireless-client-oper:client-oper-data/common-oper-data
• Cisco-IOS-XE-wireless-client-oper:client-oper-data/traffic-stats
• Cisco-IOS-XE-wireless-ap-global-oper:ap-global-oper-data/ap-join-stats