WiFi 网络诊断 Cluster（WiFiNetworkDiagnostics）

Cluster ID: 0x0036  |  所在 Endpoint: Endpoint 0（Root / Network Endpoint）

WiFiNetworkDiagnostics 提供设备 WiFi 连接的实时健康信息 —— 包括信号强度（RSSI）、当前接入点（BSSID）、安全类型、信道、WiFi 协议版本， 以及可选的数据包计数和错误统计。 它是排查设备「离线」「响应慢」「不稳定」等网络问题的第一站。

Feature 位图

通过 FeatureMap（0xFFFC）声明设备支持哪些诊断能力：

命令（Commands）

WiFiNetworkDiagnostics Cluster 仅有 1 个命令，用于重置统计计数器。 此命令需要设备启用 PKTCNT 或 ERRCNT 特性才有意义。

ResetCounts —— 重置计数器（0x00）

将设备维护的数据包计数器和错误计数器全部归零。 不需要任何参数。执行后，BeaconLostCount、BeaconRxCount、 各类收发包计数、OverrunCount 等统计值都会重置为 0。

↑ 返回命令列表

属性详解

WiFiNetworkDiagnostics Cluster 共有 14 个应用属性，按功能分为三组。 点击属性 ID 可跳转到对应的详细说明。

连接信息（0x0000 ~ 0x0004）

描述设备当前 WiFi 连接的基本信息。这些属性是基础属性，不需要任何 Feature。 当设备未连接 WiFi 时，所有 Nullable 属性返回 null。

↑ 返回属性列表

数据包计数（0x0005 ~ 0x000A）

详细的收发包统计信息，用于分析网络质量。 这组属性需要设备启用 PKTCNT（PacketCounts） 特性。 可通过 ResetCounts 命令将所有计数器归零。

↑ 返回属性列表

错误与速率（0x000B ~ 0x000C）

当前连接的最大传输速率和缓冲区溢出统计。注意：关联失败原因不是属性，而是随 AssociationFailure 事件（0x01）上报。

↑ 返回属性列表

枚举速查

SecurityTypeEnum（安全类型）

WiFiVersionEnum（WiFi 版本）

AssociationFailureCauseEnum（关联失败原因）

ConnectionStatusEnum（连接状态）

事件（Events）

WiFiNetworkDiagnostics 定义了 3 个事件，覆盖断连、关联失败、连接状态变化三种情况。 订阅这些事件是实时监控设备网络健康的推荐方式。

Disconnection —— 断连事件（0x00）

设备与当前接入点断开连接时触发。事件数据中携带 802.11 标准的断连原因码（ReasonCode）， 可用于诊断断连的具体原因。

↑ 返回事件列表

AssociationFailure —— 关联失败事件（0x01）

设备尝试连接 WiFi 但关联或认证失败时触发。 携带失败原因和 802.11 状态码，是排查「设备连不上 WiFi」问题的关键信息来源。

↑ 返回事件列表

ConnectionStatus —— 连接状态变更事件（0x02）

设备的 WiFi 连接状态发生变化时触发（连接成功或断开）。 相比 Disconnection 事件，这个事件同时覆盖了「连上」和「断开」两个方向。

↑ 返回事件列表

示例数据

一个已连接 WiFi 的 Matter 设备（支持 PKTCNT + ERRCNT）读取 WiFiNetworkDiagnostics Cluster 的完整结果：

{
  // --- 连接信息 ---
  "0x0000": "A4:CF:12:XX:XX:XX",  // BSSID（当前关联的 AP MAC 地址）
  "0x0001": 4,                     // SecurityType = WPA2
  "0x0002": 4,                     // WiFiVersion = ac (802.11ac)
  "0x0003": 6,                     // ChannelNumber = 6
  "0x0004": -45,                   // RSSI = -45 dBm（信号良好）

  // --- 数据包计数（需要 PKTCNT 特性）---
  "0x0005": 12,                    // BeaconLostCount = 12
  "0x0006": 98432,                 // BeaconRxCount = 98432
  "0x0007": 1024,                  // PacketMulticastRxCount
  "0x0008": 256,                   // PacketMulticastTxCount
  "0x0009": 502310,                // PacketUnicastRxCount
  "0x000A": 389120,                // PacketUnicastTxCount

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

  // --- 错误计数（需要 ERRCNT 特性）---
  "0x000C": 0                      // OverrunCount = 0
}

常见场景