Thread 网络诊断 Cluster（ThreadNetworkDiagnostics）

Cluster ID: 0x0035  |  所在 Endpoint: Endpoint 0（根端点）

ThreadNetworkDiagnostics 是 Thread 设备的网络诊断 Cluster，提供 Thread Mesh 网络的完整运行状态。 它包含网络标识、拓扑路由、收发包统计、错误计数等 60+ 个属性，是排查 Thread 设备连接问题和分析网络质量的核心工具。

Feature 位图

ThreadNetworkDiagnostics 通过 FeatureMap（0xFFFC）声明设备支持哪些计数器类别。 不同 Feature 控制不同分组的计数器属性是否可用。

命令（Commands）

ThreadNetworkDiagnostics 只有一个命令，用于重置所有计数器。

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

将设备上所有已启用 Feature 对应的计数器（包括 OverrunCount）归零。 不需要参数。执行后所有统计从 0 开始重新累计。

属性详解

ThreadNetworkDiagnostics 有 60+ 个属性，按功能分为以下几组。 基础网络信息所有 Thread 设备都支持，计数器属性按 Feature 分组。

网络标识（0x0000 - 0x0005）

Thread 网络的基本身份信息，标识设备所在的 Thread 网络。

↑ 返回属性概览

拓扑与路由（0x0007 - 0x000D）

Thread Mesh 网络的拓扑结构和路由信息，包括邻居表、路由表和分区数据。

NeighborTableStruct 结构体

邻居表中每个条目描述一个直接通信的邻居节点。信号质量（LQI/RSSI）和错误率是判断链路健康的关键字段。

RouteTableStruct 结构体

路由表中每个条目描述一条到目标 Router 的路由信息。

↑ 返回属性概览

数据集参数（0x0006, 0x0038 - 0x003E）

Thread 操作数据集（Operational Dataset）相关的参数，包括时间戳、安全策略和网络故障信息。

SecurityPolicy 结构体

OperationalDatasetComponents 结构体

每个字段为 bool，标识操作数据集中对应组件是否存在。

↑ 返回属性概览

发送计数器 — TX Counters（0x0016 - 0x0026）PKTCNT / MACCNT

统计设备发送数据包的各类计数。所有字段均为 uint32 类型，需要 PKTCNT 或 MACCNT Feature。

↑ 返回属性概览

接收计数器 — RX Counters（0x0027 - 0x0031）PKTCNT / MACCNT

统计设备接收数据包的各类计数。所有字段均为 uint32 类型，需要 PKTCNT 或 MACCNT Feature。

↑ 返回属性概览

接收错误计数器（0x0032 - 0x0037）ERRCNT

统计各类接收错误。所有字段均为 uint32 类型，需要 ERRCNT Feature。

↑ 返回属性概览

MLE 计数器（0x000E - 0x0015）MLECNT

MLE（Mesh Link Establishment）层事件计数，反映设备在 Thread 网络中的角色变化和附着行为。 所有字段均为 uint16 类型，需要 MLECNT Feature。

↑ 返回属性概览

枚举值速查

RoutingRoleEnum —— 路由角色

描述设备在 Thread Mesh 网络中担任的角色。

ConnectionStatusEnum —— 连接状态

NetworkFaultEnum —— 网络故障类型

事件（Events）

ThreadNetworkDiagnostics 定义了 2 个事件，用于通知网络连接状态变化和故障发生。

示例数据

一个 Thread Router 设备的 ThreadNetworkDiagnostics Cluster 典型读取结果（选取关键属性）：

{
  // --- 网络标识 ---
  "0x0000": 15,              // Channel = 15（Thread 信道）
  "0x0001": 5,               // RoutingRole = Router
  "0x0002": "MyThreadNet",   // NetworkName
  "0x0003": 4660,            // PanId = 0x1234
  "0x0004": "1111111122222222", // ExtendedPanId
  "0x0005": "fd11:2233:4455::/64", // MeshLocalPrefix

  // --- 拓扑信息 ---
  "0x0009": 12345678,        // PartitionId（网络分区标识）
  "0x000A": 64,              // Weighting（分区权重）
  "0x000D": 42,              // LeaderRouterId（Leader 路由 ID）

  // --- 发送计数器（PKTCNT）---
  "0x0016": 158432,          // TxTotalCount（累计发送总数）
  "0x0017": 120050,          // TxUnicastCount（单播发送）
  "0x0018": 38382,           // TxBroadcastCount（广播发送）
  "0x0021": 1024,            // TxRetryCount（重试次数）

  // --- 接收计数器（PKTCNT）---
  "0x0027": 203841,          // RxTotalCount（累计接收总数）
  "0x0028": 185200,          // RxUnicastCount（单播接收）
  "0x0029": 18641,           // RxBroadcastCount（广播接收）

  // --- 错误计数器（ERRCNT）---
  "0x0006": 0,               // OverrunCount（缓冲区溢出次数）
  "0x0036": 3,               // RxErrFcsCount（FCS 校验错误）

  // --- 活跃网络故障 ---
  "0x003E": []               // ActiveNetworkFaultsList = 空（当前无故障）
}

常见场景

场景 1：排查 Thread 设备离线

1. 读取 RoutingRole (0x0001) —— 如果为 null 或 Unassigned，设备未成功加入网络
2. 读取 ActiveNetworkFaultsList (0x003E) —— 检查是否有 LinkDown 或 HardwareFailure
3. 读取 NeighborTable (0x0007) —— 查看邻居列表中的 LQI 和 RSSI，判断信号质量
4. 订阅 ConnectionStatus 事件，实时感知连接状态变化

场景 2：评估网络通信质量

1. 调用 ResetCounts (0x00) 清零所有计数器
2. 等待一段时间（如 10 分钟），然后读取计数器
3. 计算重试率：TxRetryCount / TxTotalCount，超过 10% 说明链路差
4. 检查 RxErrFcsCount —— 非零说明有射频干扰
5. 检查 TxErrCcaCount —— 持续增长说明信道拥挤，考虑换信道

场景 3：了解网络拓扑

1. 读取 RoutingRole (0x0001) —— 确认设备的网络角色
2. 读取 LeaderRouterId (0x000D) —— 找到当前 Leader
3. 读取 NeighborTable (0x0007) —— 获取邻居节点列表和链路质量
4. 读取 RouteTable (0x0008) —— 查看路由拓扑和路径开销
5. 读取 PartitionId (0x0009) —— 确认所有设备是否在同一分区

场景 4：监控网络稳定性

1. 读取 MLE 计数器（需 MLECNT Feature）：
   • DetachedRoleCount (0x000E) —— 频繁脱离说明连接不稳定
   • ParentChangeCount (0x0015) —— 频繁换父节点说明周围路由器不稳定
   • PartitionIdChangeCount (0x0013) —— 非零说明网络曾分裂
2. 订阅 NetworkFaultChange 事件，及时感知故障发生和恢复
3. 定期对比计数器增量，建立网络质量基线