软件诊断 Cluster（SoftwareDiagnostics）

Cluster ID: 0x0034  |  所在 Endpoint: Endpoint 0（Root / Node 级别） |  角色: Server（只读 + 一个重置命令）

SoftwareDiagnostics 用于暴露设备固件的运行时健康状态 —— 包括线程栈使用情况、堆内存分配和软件故障记录。 这是 Matter 中面向开发者和运维人员的诊断 Cluster，帮助在不连接调试器的情况下了解嵌入式设备的内部状态。

Feature 位图

SoftwareDiagnostics Cluster 通过 FeatureMap（0xFFFC）声明设备支持的可选能力：

属性

所有属性均为只读。堆内存相关属性为可选，ThreadMetrics 也为可选。点击属性 ID 可跳转到详细说明。

ThreadMetrics（线程指标列表）

返回设备当前所有运行线程的栈使用信息。每个条目是一个 ThreadMetricsStruct，包含线程 ID、名称和栈使用统计。 这是排查栈溢出的关键数据来源。

ThreadMetricsStruct 结构

↑ 返回属性列表

CurrentHeapFree（堆空闲字节数）

设备堆内存中当前可用于分配的字节数。在资源受限的嵌入式设备上（如 ESP32 系列）， 这个值持续下降可能意味着内存泄漏。

↑ 返回属性列表

CurrentHeapUsed（堆已用字节数）

设备堆内存中当前已被分配使用的字节数。与 CurrentHeapFree 互补 —— 两者之和近似等于堆总大小（可能有碎片和管理开销的差异）。

↑ 返回属性列表

CurrentHeapHighWatermark（堆使用高水位线）

自上次 ResetWatermarks 命令或设备启动以来，CurrentHeapUsed 达到过的最大值。 这个属性需要 WTRMRK Feature 支持。

高水位线是评估设备内存裕度的重要指标 —— 它反映的是「最坏情况下用了多少内存」， 而不是某一时刻的快照。即使当前 CurrentHeapUsed 看起来正常，高水位线也可能揭示间歇性的内存尖峰。

↑ 返回属性列表

命令（Commands）

SoftwareDiagnostics 只有一个命令，需要 WTRMRK Feature 支持。

ResetWatermarks —— 重置水位线（0x00）

将 CurrentHeapHighWatermark 重置为当前的 CurrentHeapUsed 值， 同时将所有线程的 StackFreeMinimum 重置为当前的 StackFreeCurrent 值。 该命令不接受任何参数。

请求示例：

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0034",
      "commandId": "0x00"       // ResetWatermarks
    },
    "commandFields": {}         // 无参数
  }]
}

↑ 返回命令列表

事件（Events）

设备运行过程中检测到软件故障时，会上报 SoftwareFault 事件。该事件为可选支持。

SoftwareFault —— 软件故障事件（0x00）

当设备固件检测到软件异常（如未处理的异常、断言失败、看门狗触发等）时上报此事件。 事件数据携带故障线程信息和可选的故障现场记录。

事件上报示例：

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 0,
        "clusterId": "0x0034",
        "eventId": "0x00"       // SoftwareFault
      },
      "eventNumber": 7,
      "priority": "INFO",
      "data": {
        "0": 42,                // Id = 42（故障线程 ID）
        "1": "BLE",             // Name = "BLE"（故障线程名）
        "2": "RkVUQ0g6IDB4..."  // FaultRecording（Base64 编码的故障现场数据）
      }
    }
  }]
}

↑ 返回事件列表

示例数据

读取一个 ESP32 设备的 SoftwareDiagnostics Cluster 属性：

{
  // --- 属性 ---
  "0x0": [                       // ThreadMetrics（线程指标列表）
    {
      "0": 1,                    // Id = 1
      "1": "Main",               // Name = "Main"
      "2": 2048,                 // StackFreeCurrent = 2048 字节
      "3": 1024,                 // StackFreeMinimum = 1024 字节
      "4": 8192                  // StackSize = 8192 字节
    },
    {
      "0": 2,                    // Id = 2
      "1": "BLE",                // Name = "BLE"
      "2": 4096,                 // StackFreeCurrent = 4096 字节
      "3": 2048,                 // StackFreeMinimum = 2048 字节
      "4": 8192                  // StackSize = 8192 字节
    }
  ],
  "0x1": 65536,                  // CurrentHeapFree = 64 KB
  "0x2": 131072,                 // CurrentHeapUsed = 128 KB
  "0x3": 196608                  // CurrentHeapHighWatermark = 192 KB（需 WTRMRK Feature）
}

常见场景