SoftwareDiagnostics Cluster

Cluster ID: 0x0034  |  Endpoint: Endpoint 0 (Root / Node level)  |  Role: Server (read-only + one reset command)

SoftwareDiagnostics exposes the runtime health status of device firmware — including thread stack usage, heap memory allocation, and software fault records. This is a diagnostics cluster in Matter designed for developers and operations personnel, helping understand the internal state of embedded devices without connecting a debugger.

Feature Bitmap

The SoftwareDiagnostics Cluster declares optional device capabilities through FeatureMap (0xFFFC):

Attributes

All attributes are read-only. Heap memory attributes are optional, and ThreadMetrics is also optional. Click an attribute ID to jump to its detailed description.

ThreadMetrics (Thread Metrics List)

Returns stack usage information for all currently running threads on the device. Each entry is a ThreadMetricsStruct containing thread ID, name, and stack usage statistics. This is a key data source for troubleshooting stack overflows.

ThreadMetricsStruct Structure

↑ Back to Attributes

CurrentHeapFree (Free Heap Bytes)

Number of bytes currently available for allocation in the device heap. On resource-constrained embedded devices (e.g., ESP32 series), a continuously decreasing value may indicate a memory leak.

↑ Back to Attributes

CurrentHeapUsed (Used Heap Bytes)

Number of bytes currently allocated in the device heap. Complementary to CurrentHeapFree — their sum approximates the total heap size (with possible differences due to fragmentation and management overhead).

↑ Back to Attributes

CurrentHeapHighWatermark (Heap Usage High Watermark)

The maximum value CurrentHeapUsed has reached since the last ResetWatermarks command or device startup. This attribute requires WTRMRK Feature support.

The high watermark is an important indicator for assessing device memory headroom — it reflects "how much memory was used in the worst case," not a snapshot at a single moment. Even if the current CurrentHeapUsed looks normal, the watermark may reveal intermittent memory spikes.

↑ Back to Attributes

Commands

SoftwareDiagnostics has only one command, requiring WTRMRK Feature support.

ResetWatermarks — Reset Watermarks (0x00)

Resets CurrentHeapHighWatermark to the current CurrentHeapUsed value, and simultaneously resets all threads' StackFreeMinimum to their current StackFreeCurrent values. This command does not accept any parameters.

Request example:

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0034",
      "commandId": "0x00"       // ResetWatermarks
    },
    "commandFields": {}         // No parameters
  }]
}

↑ Back to Commands

Events

When a software fault is detected during device operation, a SoftwareFault event is reported. This event is optionally supported.

SoftwareFault — Software Fault Event (0x00)

This event is reported when device firmware detects a software anomaly (such as unhandled exceptions, assertion failures, watchdog triggers, etc.). The event data carries fault thread information and optional fault scene records.

Event report example:

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 0,
        "clusterId": "0x0034",
        "eventId": "0x00"       // SoftwareFault
      },
      "eventNumber": 7,
      "priority": "INFO",
      "data": {
        "0": 42,                // Id = 42 (fault thread ID)
        "1": "BLE",             // Name = "BLE" (fault thread name)
        "2": "RkVUQ0g6IDB4..."  // FaultRecording (Base64-encoded fault scene data)
      }
    }
  }]
}

↑ Back to Events

Example Data

Reading a SoftwareDiagnostics Cluster's attributes from an ESP32 device:

{
  // --- Attributes ---
  "0x0": [                       // ThreadMetrics (thread metrics list)
    {
      "0": 1,                    // Id = 1
      "1": "Main",               // Name = "Main"
      "2": 2048,                 // StackFreeCurrent = 2048 bytes
      "3": 1024,                 // StackFreeMinimum = 1024 bytes
      "4": 8192                  // StackSize = 8192 bytes
    },
    {
      "0": 2,                    // Id = 2
      "1": "BLE",                // Name = "BLE"
      "2": 4096,                 // StackFreeCurrent = 4096 bytes
      "3": 2048,                 // StackFreeMinimum = 2048 bytes
      "4": 8192                  // StackSize = 8192 bytes
    }
  ],
  "0x1": 65536,                  // CurrentHeapFree = 64 KB
  "0x2": 131072,                 // CurrentHeapUsed = 128 KB
  "0x3": 196608                  // CurrentHeapHighWatermark = 192 KB (requires WTRMRK Feature)
}

Common Scenarios