通用诊断 Cluster（GeneralDiagnostics）

Cluster ID: 0x0033  |  所在 Endpoint: 固定在 Endpoint 0（根端点）

GeneralDiagnostics 提供设备的健康状态和运行诊断信息 —— 包括网络接口详情、重启次数、运行时长、启动原因， 以及硬件/射频/网络三类故障的实时追踪。所有 Matter 设备都必须实现这个 Cluster，是设备运维和问题排查的第一入口。

命令（Commands）

GeneralDiagnostics 只有两个命令。TestEventTrigger 用于测试认证，生产环境通常禁用； TimeSnapshot 用于获取设备当前的时间快照。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

TestEventTrigger —— 测试事件触发（0x00）

触发设备预置的测试事件。这个命令主要用于 Matter 认证测试期间，允许测试工具在不拆机的情况下模拟特定的设备行为 （如模拟传感器告警、触发故障状态等）。

↑ 返回命令列表

TimeSnapshot —— 时间快照（0x01）

请求设备返回当前的系统时间。不需要参数。 设备会返回一个 TimeSnapshotResponse，包含系统启动后的毫秒计时和 POSIX 时间戳（如果设备有可靠时钟）。

TimeSnapshotResponse 响应字段

↑ 返回命令列表

属性详解

GeneralDiagnostics 的属性按功能分为四组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

网络接口（0x0000）

设备当前可用的所有网络接口的详细信息列表。

↑ 返回属性列表

运行统计（0x0001-0x0004）

设备的运行时间统计和启动原因，是判断设备稳定性的关键指标。

↑ 返回属性列表

故障追踪（0x0005-0x0007）

三个列表属性分别追踪硬件、射频和网络层面的当前活跃故障。 正常运行的设备这三个列表都应该为空。一旦出现非空值，说明设备检测到了对应类型的故障。

↑ 返回属性列表

测试配置（0x0008）

与认证测试相关的配置属性。

↑ 返回属性列表

枚举速查

GeneralDiagnostics 涉及多个枚举类型，下面逐一列出所有枚举值。

BootReasonEnum —— 启动原因

描述设备最近一次启动的原因，对应 BootReason (0x0004) 属性和 BootReason 事件。

HardwareFaultEnum —— 硬件故障

描述设备可能遇到的硬件层故障，对应 ActiveHardwareFaults (0x0005) 属性。

RadioFaultEnum —— 射频故障

描述设备无线通信模块的故障类型，对应 ActiveRadioFaults (0x0006) 属性。

NetworkFaultEnum —— 网络故障

描述设备网络层面的故障类型，对应 ActiveNetworkFaults (0x0007) 属性。

InterfaceTypeEnum —— 网络接口类型

描述网络接口的物理类型，对应 NetworkInterface 结构体中的 Type 字段。

数据结构

NetworkInterface 结构体

描述一个网络接口的完整信息，是 NetworkInterfaces (0x0000) 属性中每个列表元素的结构。

NetworkInterface 数据示例：

{
  "Name": "wlan0",                              // 接口名称
  "IsOperational": true,                        // 接口正在运行
  "OffPremiseServicesReachableIPv4": true,       // IPv4 可达外部服务
  "OffPremiseServicesReachableIPv6": null,       // IPv6 可达性未知
  "HardwareAddress": "AA:BB:CC:DD:EE:FF",       // MAC 地址
  "IPv4Addresses": ["192.168.1.100"],            // IPv4 地址列表
  "IPv6Addresses": ["fe80::1", "2001:db8::1"],  // IPv6 地址列表
  "Type": 1                                     // WiFi 接口
}

↑ 返回属性列表

事件（Events）

GeneralDiagnostics 定义了 4 个事件，均为 Critical 优先级。 前三个分别对应硬件/射频/网络故障状态的变更通知，第四个是设备启动原因通知。 订阅这些事件可以实时感知设备健康状态的变化。

HardwareFaultChange —— 硬件故障变更（0x00）

当设备的硬件故障状态发生变化时触发 —— 无论是新增故障还是故障恢复。 事件数据中同时包含变化前后的完整故障列表，方便对比分析。

↑ 返回事件列表

RadioFaultChange —— 射频故障变更（0x01）

当设备的射频故障状态发生变化时触发。结构与 HardwareFaultChange 相同。

↑ 返回事件列表

NetworkFaultChange —— 网络故障变更（0x02）

当设备的网络故障状态发生变化时触发。结构与 HardwareFaultChange 相同。

↑ 返回事件列表

BootReason —— 启动原因事件（0x03）

设备每次启动时都会发出此事件，上报启动的原因。 这是排查设备异常重启的第一手线索 —— 配合 RebootCount 属性使用效果更佳。

↑ 返回事件列表

示例数据

一个正常运行中的 WiFi 智能设备的 GeneralDiagnostics Cluster 读取结果：

{
  // --- 网络接口 ---
  "0x0000": [                   // NetworkInterfaces
    {
      "Name": "wlan0",
      "IsOperational": true,
      "OffPremiseServicesReachableIPv4": true,
      "OffPremiseServicesReachableIPv6": null,
      "HardwareAddress": "AA:BB:CC:DD:EE:FF",
      "IPv4Addresses": ["192.168.1.100"],
      "IPv6Addresses": ["fe80::1"],
      "Type": 1                 // WiFi
    }
  ],

  // --- 运行统计 ---
  "0x0001": 12,                 // RebootCount = 12（累计重启 12 次）
  "0x0002": 86400,              // UpTime = 86400 秒（已运行 24 小时）
  "0x0003": 720,                // TotalOperationalHours = 720（累计运行 30 天）
  "0x0004": 1,                  // BootReason = PowerOnReboot（正常上电启动）

  // --- 故障状态 ---
  "0x0005": [],                 // ActiveHardwareFaults = []（无硬件故障）
  "0x0006": [],                 // ActiveRadioFaults = []（无射频故障）
  "0x0007": [],                 // ActiveNetworkFaults = []（无网络故障）

  // --- 测试配置 ---
  "0x0008": false               // TestEventTriggersEnabled = false（测试触发器未启用）
}

常见场景