ThreadNetworkDiagnostics Cluster

Cluster ID: 0x0035  |  Endpoint: Endpoint 0 (Root Endpoint)

ThreadNetworkDiagnostics is the network diagnostics cluster for Thread devices, providing the complete operational status of the Thread Mesh network. It contains 60+ attributes covering network identification, topology routing, packet statistics, and error counts — the core tool for troubleshooting Thread device connectivity and analyzing network quality.

Feature Bitmap

ThreadNetworkDiagnostics declares which counter categories the device supports through FeatureMap (0xFFFC). Different features control the availability of different groups of counter attributes.

Commands

ThreadNetworkDiagnostics has only one command, used to reset all counters.

ResetCounts — Reset Counters (0x00)

Resets all counters corresponding to enabled features (including OverrunCount) to zero on the device. No parameters required. After execution, all statistics restart from 0.

Attributes

ThreadNetworkDiagnostics has 60+ attributes, organized into the following groups by function. Basic network information is supported by all Thread devices; counter attributes are grouped by feature.

Network Identity (0x0000 - 0x0005)

Basic identity information for the Thread network, identifying which Thread network the device belongs to.

↑ Back to Attributes

Topology & Routing (0x0007 - 0x000D)

Topology structure and routing information of the Thread Mesh network, including neighbor table, route table, and partition data.

NeighborTableStruct Structure

Each entry in the neighbor table describes a directly communicating neighbor node. Signal quality (LQI/RSSI) and error rate are key fields for assessing link health.

RouteTableStruct Structure

Each entry in the route table describes routing information to a target Router.

↑ Back to Attributes

Dataset Parameters (0x0006, 0x0038 - 0x003E)

Parameters related to the Thread Operational Dataset, including timestamps, security policy, and network fault information.

SecurityPolicy Structure

OperationalDatasetComponents Structure

Each field is a bool indicating whether the corresponding component is present in the operational dataset.

↑ Back to Attributes

TX Counters (0x0016 - 0x0026) PKTCNT / MACCNT

Statistics for various types of transmitted packets. All fields are uint32, requiring PKTCNT or MACCNT Feature.

↑ Back to Attributes

RX Counters (0x0027 - 0x0031) PKTCNT / MACCNT

Statistics for various types of received packets. All fields are uint32, requiring PKTCNT or MACCNT Feature.

↑ Back to Attributes

RX Error Counters (0x0032 - 0x0037) ERRCNT

Statistics for various receive errors. All fields are uint32, requiring ERRCNT Feature.

↑ Back to Attributes

MLE Counters (0x000E - 0x0015) MLECNT

MLE (Mesh Link Establishment) layer event counts, reflecting device role changes and attach behavior in the Thread network. All fields are uint16, requiring MLECNT Feature.

↑ Back to Attributes

Enum Quick Reference

RoutingRoleEnum — Routing Role

Describes the role the device serves in the Thread Mesh network.

ConnectionStatusEnum — Connection Status

NetworkFaultEnum — Network Fault Type

Events

ThreadNetworkDiagnostics defines 2 events for notifying network connection status changes and fault occurrences.

Example Data

Typical read results from a Thread Router device's ThreadNetworkDiagnostics Cluster (key attributes selected):

{
  // --- Network Identity ---
  "0x0000": 15,              // Channel = 15 (Thread channel)
  "0x0001": 5,               // RoutingRole = Router
  "0x0002": "MyThreadNet",   // NetworkName
  "0x0003": 4660,            // PanId = 0x1234
  "0x0004": "1111111122222222", // ExtendedPanId
  "0x0005": "fd11:2233:4455::/64", // MeshLocalPrefix

  // --- Topology Info ---
  "0x0009": 12345678,        // PartitionId (network partition identifier)
  "0x000A": 64,              // Weighting (partition weight)
  "0x000D": 42,              // LeaderRouterId (Leader router ID)

  // --- TX Counters (PKTCNT) ---
  "0x0016": 158432,          // TxTotalCount (total transmitted)
  "0x0017": 120050,          // TxUnicastCount (unicast transmitted)
  "0x0018": 38382,           // TxBroadcastCount (broadcast transmitted)
  "0x0021": 1024,            // TxRetryCount (retry count)

  // --- RX Counters (PKTCNT) ---
  "0x0027": 203841,          // RxTotalCount (total received)
  "0x0028": 185200,          // RxUnicastCount (unicast received)
  "0x0029": 18641,           // RxBroadcastCount (broadcast received)

  // --- Error Counters (ERRCNT) ---
  "0x0006": 0,               // OverrunCount (buffer overrun count)
  "0x0036": 3,               // RxErrFcsCount (FCS check errors)

  // --- Active Network Faults ---
  "0x003E": []               // ActiveNetworkFaultsList = empty (no current faults)
}

Common Scenarios

Scenario 1: Troubleshooting Thread Device Offline

1. Read RoutingRole (0x0001) — if null or Unassigned, the device has not successfully joined the network
2. Read ActiveNetworkFaultsList (0x003E) — check for LinkDown or HardwareFailure
3. Read NeighborTable (0x0007) — check LQI and RSSI in the neighbor list to assess signal quality
4. Subscribe to ConnectionStatus events for real-time awareness of connection status changes

Scenario 2: Assessing Network Communication Quality

1. Call ResetCounts (0x00) to reset all counters
2. Wait for a period (e.g., 10 minutes), then read the counters
3. Calculate retry rate: TxRetryCount / TxTotalCount, above 10% indicates poor link quality
4. Check RxErrFcsCount — non-zero indicates radio interference
5. Check TxErrCcaCount — continuous growth indicates channel congestion, consider switching channels

Scenario 3: Understanding Network Topology

1. Read RoutingRole (0x0001) — confirm the device's network role
2. Read LeaderRouterId (0x000D) — find the current Leader
3. Read NeighborTable (0x0007) — get neighbor node list and link quality
4. Read RouteTable (0x0008) — view routing topology and path costs
5. Read PartitionId (0x0009) — confirm if all devices are in the same partition

Scenario 4: Monitoring Network Stability

1. Read MLE counters (requires MLECNT Feature):
   • DetachedRoleCount (0x000E) — frequent detachment indicates unstable connection
   • ParentChangeCount (0x0015) — frequent parent changes indicate unstable nearby routers
   • PartitionIdChangeCount (0x0013) — non-zero means the network has split
2. Subscribe to NetworkFaultChange events for timely awareness of fault occurrences and recoveries
3. Periodically compare counter increments to establish a network quality baseline