WiFiNetworkDiagnostics Cluster

Cluster ID: 0x0036 | Endpoint: Endpoint 0 (Root / Network Endpoint)

WiFiNetworkDiagnostics provides real-time health information for the device's WiFi connection — including signal strength (RSSI), current access point (BSSID), security type, channel, WiFi protocol version, as well as optional packet counts and error statistics. It is the first stop for troubleshooting network issues like "offline," "slow response," or "unstable" devices.

Feature Dependencies

This cluster defines two optional features: PKTCNT (Packet Counts) and ERRCNT (Error Counts). When enabled, they provide packet TX/RX statistics and overrun/association failure counts respectively. Basic connection info (BSSID, RSSI, channel, etc.) can be read without any feature.

Feature Bitmap

Declares which diagnostic capabilities the device supports through FeatureMap (0xFFFC):

Bit 0

PKTCNT（PacketCounts） Packet counts — when enabled, provides Beacon, multicast, and unicast TX/RX packet statistics

Bit 1

ERRCNT（ErrorCounts） Error counts — when enabled, provides OverrunCount (buffer overflow) statistics

Commands

WiFiNetworkDiagnostics Cluster has only 1 command, used to reset statistical counters. This command is only meaningful when the device has PKTCNT or ERRCNT features enabled.

ID	Name	Description	Required Feature
`0x00`	ResetCounts	Reset packet and error counters	PKTCNT \| ERRCNT

ResetCounts — Reset Counters (0x00)

Resets all packet counters and error counters maintained by the device to zero. No parameters required. After execution, BeaconLostCount, BeaconRxCount, all TX/RX packet counts, OverrunCount, and other statistics are reset to 0.

Usage Scenarios

When troubleshooting network issues, first call ResetCounts to clear all counters, then observe counter growth over a period to determine packet loss rate and error frequency. Also useful after moving a device to a new location, starting a new round of network quality baseline measurement.

↑ Back to Commands

Attributes

WiFiNetworkDiagnostics Cluster has 14 application attributes, organized into three groups by function. Click an attribute ID to jump to its detailed description.

ID	Name	Type	Group	Description
`0x0000`	BSSID	octstr / null	Connection Info	MAC address of the currently associated AP
`0x0001`	SecurityType	enum / null	Connection Info	WiFi security authentication type
`0x0002`	WiFiVersion	enum / null	Connection Info	Current 802.11 protocol version in use
`0x0003`	ChannelNumber	uint16 / null	Connection Info	Current WiFi channel number in use
`0x0004`	RSSI	int8 / null	Connection Info	Received signal strength (dBm)
`0x0005`	BeaconLostCount	uint32 / null	Packet Counts	Lost Beacon frame count
`0x0006`	BeaconRxCount	uint32 / null	Packet Counts	Successfully received Beacon frame count
`0x0007`	PacketMulticastRxCount	uint32 / null	Packet Counts	Multicast packets received
`0x0008`	PacketMulticastTxCount	uint32 / null	Packet Counts	Multicast packets transmitted
`0x0009`	PacketUnicastRxCount	uint32 / null	Packet Counts	Unicast packets received
`0x000A`	PacketUnicastTxCount	uint32 / null	Packet Counts	Unicast packets transmitted
`0x000B`	CurrentMaxRate	uint64 / null	Errors & Rate	Current maximum transmission rate (bps)
`0x000C`	OverrunCount	uint64 / null	Errors & Rate	Buffer overrun count

Connection Info (0x0000 ~ 0x0004)

Describes basic information about the device's current WiFi connection. These are base attributes and do not require any Feature. When the device is not connected to WiFi, all Nullable attributes return null.

ID	Name	Type	Description
`0x0000`	BSSID	octstr / null	MAC address of the currently associated access point (AP), 6 bytes. `null` when not connected. Useful for determining which AP the device is connected to (especially useful in multi-AP environments)
`0x0001`	SecurityType (Security Type)	SecurityTypeEnum / null	Security authentication method used by the current WiFi connection. `null` when not connected. See SecurityTypeEnum below
`0x0002`	WiFiVersion (WiFi Version)	WiFiVersionEnum / null	Current 802.11 protocol version used by the connection. `null` when not connected. See WiFiVersionEnum below
`0x0003`	ChannelNumber (Channel Number)	uint16 / null	Current WiFi channel number in use. 2.4 GHz is typically 1-13, 5 GHz is 36-165. `null` when not connected
`0x0004`	RSSI (Signal Strength)	int8 / null	Received Signal Strength Indicator in dBm, range -120 to 0. Higher values (closer to 0) mean stronger signal. `null` when not connected

RSSI Signal Strength Reference

-30 to -50 dBm: Excellent, device is right next to the router
-50 to -60 dBm: Good, no issues for daily use
-60 to -70 dBm: Fair, occasional latency possible
-70 to -80 dBm: Poor, recommend moving closer to router or adding a range extender
Below -80 dBm: Very poor, device may frequently drop offline

↑ Back to Attributes

Packet Counts (0x0005 ~ 0x000A)

Detailed TX/RX packet statistics for analyzing network quality. This group of attributes requires the device to have the PKTCNT (PacketCounts) feature enabled. All counters can be reset to zero via the ResetCounts command.

Beacon Loss Ratio

BeaconLostCount / (BeaconLostCount + BeaconRxCount) is a key indicator of WiFi stability. Under normal conditions, Beacon loss rate should be below 1%. Above 5% indicates very unstable signal — check the distance and obstructions between the device and router.

ID	Name	Type	Description
`0x0005`	BeaconLostCount	uint32 / null	Number of Beacon frames the device expected but did not receive since last reset. Continuously growing values indicate unstable signal. Requires PKTCNT
`0x0006`	BeaconRxCount	uint32 / null	Number of Beacon frames successfully received since last reset. Requires PKTCNT
`0x0007`	PacketMulticastRxCount	uint32 / null	Multicast packets received. Requires PKTCNT
`0x0008`	PacketMulticastTxCount	uint32 / null	Multicast packets transmitted. Requires PKTCNT
`0x0009`	PacketUnicastRxCount	uint32 / null	Unicast packets received. Unicast is one-to-one communication between device and router, the primary traffic. Requires PKTCNT
`0x000A`	PacketUnicastTxCount	uint32 / null	Unicast packets transmitted. Requires PKTCNT

↑ Back to Attributes

Errors & Rate (0x000B ~ 0x000C)

Current connection maximum transmission rate and buffer overrun statistics. Note: the association failure cause is not an attribute; it is reported in the AssociationFailure event (0x01).

ID	Name	Type	Description
`0x000B`	CurrentMaxRate	uint64 / null	Maximum transmission rate negotiated for the current connection, in bps (bits per second). For example, 866700000 = 866.7 Mbps (typical 802.11ac rate). `null` when not connected
`0x000C`	OverrunCount	uint64 / null	Packets dropped by the receiver due to full buffers. Continuous growth indicates the device's processing capacity cannot keep up with network traffic. Requires ERRCNT

↑ Back to Attributes

Enum Quick Reference

SecurityTypeEnum (Security Type)

Unspecified Unspecified

None No encryption (open network)

WEP WEP encryption (deprecated, highly insecure)

WPA WPA-Personal

WPA2 WPA2-Personal (most common)

WPA3 WPA3-Personal (latest standard)

WiFiVersionEnum (WiFi Version)

a 802.11a（5 GHz，54 Mbps）

b 802.11b（2.4 GHz，11 Mbps）

g 802.11g（2.4 GHz，54 Mbps）

n 802.11n / WiFi 4 (dual-band, 600 Mbps)

ac 802.11ac / WiFi 5（5 GHz，6.9 Gbps）

ax 802.11ax / WiFi 6 (dual-band, 9.6 Gbps)

ah 802.11ah / WiFi HaLow (Sub-1GHz, IoT-specific)

AssociationFailureCauseEnum (Association Failure Cause)

Unknown Unknown cause

AssociationFailed Association failed — AP rejected the device's association request

AuthenticationFailed Authentication failed — typically incorrect password

SsidNotFound SSID not found — target network is out of range or has been turned off

ConnectionStatusEnum (Connection Status)

Connected Connected

NotConnected Not connected

Events

WiFiNetworkDiagnostics defines 3 events, covering disconnection, association failure, and connection status change. Subscribing to these events is the recommended way to monitor device network health in real time.

ID	Name	Priority	Description
`0x00`	Disconnection	Info	Triggered when the device disconnects from the AP
`0x01`	AssociationFailure	Info	Triggered when WiFi association or authentication fails
`0x02`	ConnectionStatus	Info	Triggered when the connection status changes

Disconnection — Disconnection Event (0x00)

Triggered when the device disconnects from the current access point. The event data carries the 802.11 standard disconnection reason code (ReasonCode), which can be used to diagnose the specific cause of disconnection.

Field	ID	Type	Description
ReasonCode	`0x00`	uint16	802.11 disconnection reason code. Common values: 1 = Unspecified, 4 = Disassociated due to inactivity, 8 = Deauthenticated because sending station is leaving

↑ Back to Events

AssociationFailure — Association Failure Event (0x01)

Triggered when the device attempts to connect to WiFi but association or authentication fails. Carries failure cause and 802.11 status code, a key information source for troubleshooting "device can't connect to WiFi" issues.

Field	ID	Type	Description
AssociationFailureCause	`0x00`	AssociationFailureCauseEnum	Failure cause category, see enum above
Status	`0x01`	uint16	802.11 association/authentication status code, providing more granular failure information

↑ Back to Events

ConnectionStatus — Connection Status Change Event (0x02)

Triggered when the device's WiFi connection status changes (connected or disconnected). Compared to the Disconnection event, this event covers both "connected" and "disconnected" directions.

Field	ID	Type	Description
ConnectionStatus	`0x00`	ConnectionStatusEnum	New connection status. See ConnectionStatusEnum above

↑ Back to Events

Example Data

Complete read results from a WiFi-connected Matter device (with PKTCNT + ERRCNT support) for the WiFiNetworkDiagnostics Cluster:

{
  // --- Connection Info ---
  "0x0000": "A4:CF:12:XX:XX:XX",  // BSSID (currently associated AP MAC address)
  "0x0001": 4,                     // SecurityType = WPA2
  "0x0002": 4,                     // WiFiVersion = ac (802.11ac)
  "0x0003": 6,                     // ChannelNumber = 6
  "0x0004": -45,                   // RSSI = -45 dBm (good signal)

  // --- Packet Counts (requires PKTCNT feature) ---
  "0x0005": 12,                    // BeaconLostCount = 12
  "0x0006": 98432,                 // BeaconRxCount = 98432
  "0x0007": 1024,                  // PacketMulticastRxCount
  "0x0008": 256,                   // PacketMulticastTxCount
  "0x0009": 502310,                // PacketUnicastRxCount
  "0x000A": 389120,                // PacketUnicastTxCount

  // --- Rate ---
  "0x000B": 866700000,             // CurrentMaxRate = 866.7 Mbps

  // --- Error Counts (requires ERRCNT feature) ---
  "0x000C": 0                      // OverrunCount = 0
}

Developer Tip

Not all devices support PKTCNT and ERRCNT features. Check FeatureMap (0xFFFC) before reading. For simple scenarios that only need to determine "is the device WiFi working," reading just RSSI (0x0004) and SecurityType (0x0001) is sufficient.

Common Scenarios

Scenario 1: WiFi Health Monitoring

Continuously monitor the device's WiFi connection quality, alerting before issues occur.

Subscribe to RSSI (0x0004) attribute changes with a reasonable reporting interval (e.g., every 60 seconds or when change exceeds 5 dBm)
Subscribe to Disconnection and ConnectionStatus events for real-time disconnection awareness
Periodically read BeaconLostCount and BeaconRxCount to calculate Beacon loss rate
When RSSI is below -75 dBm or Beacon loss rate exceeds 5%, the app should prompt the user "Device signal is weak, recommend moving closer to router"
Combined with ChannelNumber info, advise the user whether to switch router channels to avoid congestion

Scenario 2: Signal Strength Troubleshooting

User reports device "responds slowly" or "frequently goes offline," locate the issue through diagnostic data.

Read RSSI (0x0004) to determine if signal strength is sufficient
Read WiFiVersion (0x0002) to confirm the protocol version in use (still using 802.11b/g indicates limited device capability)
Read CurrentMaxRate (0x000B) to confirm if the negotiated rate is normal
Call ResetCounts (0x00) to reset counters, wait 5-10 minutes, then read packet counts
Calculate packet loss rate: if BeaconLostCount grows rapidly, the problem is the wireless environment (distance/interference); if OverrunCount grows rapidly, the problem is device processing capacity

Scenario 3: Roaming Analysis (Multi-AP Environment)

In Mesh or multi-AP networks, track device switching behavior between different access points.

Periodically read BSSID (0x0000) to record changes in the AP MAC address the device connects to
Subscribe to Disconnection and ConnectionStatus events to capture each roaming event
Each time BSSID changes, simultaneously read RSSI and ChannelNumber to record the new AP's signal quality
Analyze roaming frequency: frequent roaming (e.g., switching every minute) indicates the device is at the signal boundary between two APs, with neither signal being strong
If AssociationFailure events accompany roaming, the handoff process is not smooth and AP configuration may need adjustment