GeneralDiagnostics Cluster

Cluster ID: 0x0033  |  Endpoint: Fixed on Endpoint 0 (Root Endpoint)

GeneralDiagnostics provides device health status and operational diagnostics — including network interface details, reboot count, uptime, boot reason, and real-time tracking of hardware, radio, and network faults. All Matter devices must implement this Cluster; it is the primary entry point for device operations and troubleshooting.

Commands

GeneralDiagnostics has only two commands. TestEventTrigger is used for certification testing and is typically disabled in production; TimeSnapshot is used to get the device's current time snapshot. Click on a command ID in the table below to jump to its detailed description.

TestEventTrigger — Test Event Trigger (0x00)

Triggers a preset test event on the device. This command is primarily used during Matter certification testing, allowing test tools to simulate specific device behaviors without disassembly (e.g., simulating sensor alarms, triggering fault states, etc.).

↑ Back to Commands

TimeSnapshot — Time Snapshot (0x01)

Requests the device to return its current system time. No parameters required. The device returns a TimeSnapshotResponse containing the milliseconds since boot and a POSIX timestamp (if the device has a reliable clock).

TimeSnapshotResponse Response Fields

↑ Back to Commands

Attributes

GeneralDiagnostics attributes are divided into four groups by function. Click on an attribute ID in the summary table below to jump to its detailed description.

Network Interface (0x0000)

Detailed information list of all currently available network interfaces on the device.

↑ Back to Attributes

Runtime Statistics (0x0001-0x0004)

Device uptime statistics and boot reason — key indicators for assessing device stability.

↑ Back to Attributes

Fault Tracking (0x0005-0x0007)

Three list attributes track currently active faults at the hardware, radio, and network levels respectively. On a normally operating device, all three lists should be empty. A non-empty value indicates the device has detected a fault of the corresponding type.

↑ Back to Attributes

Test Configuration (0x0008)

Configuration attributes related to certification testing.

↑ Back to Attributes

Enum Quick Reference

GeneralDiagnostics involves multiple enum types, all listed below with their values.

BootReasonEnum — Boot Reason

Describes the reason for the device's most recent boot, corresponding to the BootReason (0x0004) attribute and the BootReason event.

HardwareFaultEnum — Hardware Fault

Describes hardware-level faults the device may encounter, corresponding to the ActiveHardwareFaults (0x0005) attribute.

RadioFaultEnum — Radio Fault

Describes fault types for the device's wireless communication modules, corresponding to the ActiveRadioFaults (0x0006) attribute.

NetworkFaultEnum — Network Fault

Describes network-level fault types for the device, corresponding to the ActiveNetworkFaults (0x0007) attribute.

InterfaceTypeEnum — Network Interface Type

Describes the physical type of a network interface, corresponding to the Type field in the NetworkInterface struct.

Data Structures

NetworkInterface Struct

Describes the complete information of a network interface, representing the structure of each list element in the NetworkInterfaces (0x0000) attribute.

NetworkInterface data example:

{
  "Name": "wlan0",                              // Interface name
  "IsOperational": true,                        // Interface is running
  "OffPremiseServicesReachableIPv4": true,       // IPv4 can reach external services
  "OffPremiseServicesReachableIPv6": null,       // IPv6 reachability unknown
  "HardwareAddress": "AA:BB:CC:DD:EE:FF",       // MAC address
  "IPv4Addresses": ["192.168.1.100"],            // IPv4 address list
  "IPv6Addresses": ["fe80::1", "2001:db8::1"],  // IPv6 address list
  "Type": 1                                     // WiFi interface
}

↑ Back to Attributes

Events

GeneralDiagnostics defines 4 events, all with Critical priority. The first three correspond to change notifications for hardware/radio/network fault states respectively; the fourth is a device boot reason notification. Subscribing to these events enables real-time awareness of changes in device health status.

HardwareFaultChange — Hardware Fault Change (0x00)

Triggered when the device's hardware fault state changes — whether a new fault occurs or a fault is recovered. The event data includes complete fault lists before and after the change for comparison analysis.

↑ Back to Events

RadioFaultChange — Radio Fault Change (0x01)

Triggered when the device's radio fault state changes. Structure is the same as HardwareFaultChange.

↑ Back to Events

NetworkFaultChange — Network Fault Change (0x02)

Triggered when the device's network fault state changes. Structure is the same as HardwareFaultChange.

↑ Back to Events

BootReason — Boot Reason Event (0x03)

This event is emitted every time the device boots, reporting the boot reason. This is the primary clue for troubleshooting abnormal device reboots — most effective when used with the RebootCount attribute.

↑ Back to Events

Example Data

Attribute read results from a normally running WiFi smart device's GeneralDiagnostics Cluster:

{
  // --- Network Interfaces ---
  "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
    }
  ],

  // --- Runtime Statistics ---
  "0x0001": 12,                 // RebootCount = 12 (12 total reboots)
  "0x0002": 86400,              // UpTime = 86400 seconds (running for 24 hours)
  "0x0003": 720,                // TotalOperationalHours = 720 (30 days total)
  "0x0004": 1,                  // BootReason = PowerOnReboot (normal power-on boot)

  // --- Fault Status ---
  "0x0005": [],                 // ActiveHardwareFaults = [] (no hardware faults)
  "0x0006": [],                 // ActiveRadioFaults = [] (no radio faults)
  "0x0007": [],                 // ActiveNetworkFaults = [] (no network faults)

  // --- Test Configuration ---
  "0x0008": false               // TestEventTriggersEnabled = false (test triggers not enabled)
}

Common Scenarios