Matter Cluster 51 — General Diagnostics Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 51 values in the device shadow use this format:

endpoint_id / 51 / attribute_id

Example:

{
  "0/51/1": 1
}

Cluster 51 Features

The FeatureMap attribute (0/51/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 1 means every feature listed above is enabled.

Data Types

BootReasonEnum

HardwareFaultEnum

InterfaceTypeEnum

NetworkFaultEnum

RadioFaultEnum

DeviceLoadStruct (struct)

This structure describes some important resource utilization metrics for the Node, as provided in the DeviceLoadStatus attribute. For all the fields, the value must remain at the maximum representable (clamp to max) if the maximum value is reached.

NetworkInterface (struct)

This structure describes a network interface supported by the Node, as provided in the NetworkInterfaces attribute.

Cluster 51 Attributes

Cluster 51 defines 11 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — NetworkInterfaces

Path example:

0/51/0

The NetworkInterfaces attribute is a list of NetworkInterface structs. Each logical network interface on the Node is represented by a single entry within the NetworkInterfaces attribute.

Each entry is a NetworkInterface (see Data Types).

Example:

{
  "0/51/0": []
}

Attribute 1 / 0x0001 — RebootCount

Path example:

0/51/1

The RebootCount attribute indicates a best-effort count of the number of times the Node has rebooted. The RebootCount attribute should be incremented each time the Node reboots. The RebootCount attribute must NOT be incremented when a Node wakes from a low-power or sleep state. The RebootCount attribute only be reset to 0 upon a factory reset of the Node.

Example:

{
  "0/51/1": 1
}

Attribute 2 / 0x0002 — UpTime

Path example:

0/51/2

The UpTime attribute indicates a best-effort assessment of the length of time, in seconds, since the Node's last reboot. This attribute should be incremented to account for the periods of time that a Node is in a low-power or sleep state. This attribute only be reset upon a device reboot. This attribute is based on the same System Time source as those used to fulfill any usage of the systime-us and systime-ms data types within the server.

Example:

{
  "0/51/2": 0
}

Attribute 3 / 0x0003 — TotalOperationalHours

Path example:

0/51/3

The TotalOperationalHours attribute indicates a best-effort attempt at tracking the length of time, in hours, that the Node has been operational. The TotalOperationalHours attribute should be incremented to account for the periods of time that a Node is in a low-power or sleep state. The TotalOperationalHours attribute only be reset upon a factory reset of the Node.

Example:

{
  "0/51/3": 1
}

Attribute 4 / 0x0004 — BootReason

Path example:

0/51/4

The BootReason attribute indicates the reason for the Node's most recent boot.

Values (BootReasonEnum):

Example:

{
  "0/51/4": 1
}

Attribute 5 / 0x0005 — ActiveHardwareFaults

Path example:

0/51/5

The ActiveHardwareFaults attribute indicates the set of faults currently detected by the Node. When the Node detects a fault has been raised, the appropriate HardwareFaultEnum value is added to this list. This list must NOT contain more than one instance of a specific HardwareFaultEnum value. When the Node detects that all conditions contributing to a fault has been cleared, the corresponding HardwareFaultEnum value is removed from this list.

Example:

{
  "0/51/5": []
}

Attribute 6 / 0x0006 — ActiveRadioFaults

Path example:

0/51/6

The ActiveRadioFaults attribute indicates the set of faults currently detected by the Node. When the Node detects a fault has been raised, the appropriate RadioFaultEnum value is added to this list. This list must NOT contain more than one instance of a specific RadioFaultEnum value. When the Node detects that all conditions contributing to a fault has been cleared, the corresponding RadioFaultEnum value is removed from this list.

Example:

{
  "0/51/6": []
}

Attribute 7 / 0x0007 — ActiveNetworkFaults

Path example:

0/51/7

The ActiveNetworkFaults attribute indicates the set of faults currently detected by the Node. When the Node detects a fault has been raised, the appropriate NetworkFaultEnum value is added to this list. This list must NOT contain more than one instance of a specific NetworkFaultEnum value. When the Node detects that all conditions contributing to a fault has been cleared, the corresponding NetworkFaultEnum value is removed from this list.

Example:

{
  "0/51/7": []
}

Attribute 8 / 0x0008 — TestEventTriggersEnabled

Path example:

0/51/8

The TestEventTriggersEnabled attribute indicates whether the Node has any TestEventTrigger configured. When this attribute is true, the Node has been configured with one or more test event triggers by virtue of the internally programmed EnableKey value being set to a non-zero value. This attribute can be used by Administrators to detect if a device was inadvertently commissioned with test event trigger mode enabled, and take appropriate action (e.g. warn the user and/or offer to remove all fabrics on the Node).

Example:

{
  "0/51/8": true
}

Attribute 9 / 0x0009 — DoNotUse

Path example:

0/51/9

No condensed specification text is available for DoNotUse; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/51/9": 0
}

Attribute 10 / 0x000A — DeviceLoadStatus

Path example:

0/51/10

Indicates the status of various resources used.

Value is a DeviceLoadStruct struct (see Data Types).

Example:

{
  "0/51/10": {
    "currentSubscriptions": 1,
    "currentSubscriptionsForFabric": 1,
    "totalSubscriptionsEstablished": 1,
    "totalInteractionModelMessagesSent": 1
  }
}

Cluster 51 Commands

Cluster 51 has 3 client-to-server commands and 2 responses.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 51 / 65529

{
  "0/51/65529": [
    0,
    1,
    3
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 51,
    "command_name": "TestEventTrigger",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 51, always use "cluster_id": 51. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: TestEventTrigger

Purpose

This command is supported to provide a means for certification tests to trigger some test-plan-specific events, necessary to assist in automation of device interactions for some certification test cases. This command must NOT cause any changes to the state of the device that persist after the last fabric is removed. The fields for the TestEventTrigger command are as follows:

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 51,
    "command_name": "TestEventTrigger",
    "payload": {
      "enableKey": "AQID",
      "eventTrigger": 1
    }
  }
}

Command: TimeSnapshot

Purpose

This command may be used by a client to obtain a correlated view of both System Time, and, if currently synchronized and supported, "wall clock time" of the server. This can help clients establish time correlation between their concept of time and the server's concept of time. This is especially useful when processing event histories where some events only contain System Time. Upon command invocation, the server must respond with a TimeSnapshotResponse.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 51,
    "command_name": "TimeSnapshot",
    "payload": {}
  }
}

The device answers with TimeSnapshotResponse (see below).

Command: TimeSnapshotResponse

Purpose

This command is generated in response to a TimeSnapshot command. When generating this response, all fields is gathered as close together in time as possible, so that the time jitter between the values is minimized. If the Time Synchronization cluster is supported by the node, the PosixTimeMs field must NOT be null unless the UTCTime attribute in the Time Synchronization cluster is also null.

Command Identity

Response Fields

Command: PayloadTestRequest

Purpose

This command provides a means for certification tests or manufacturer's internal tests to validate particular command handling and encoding constraints by generating a response of a given size. This command must use the same EnableKey behavior as the TestEventTrigger command, whereby processing of the command is only enabled when the TestEventTriggersEnabled field is true, which must NOT be true outside of certification testing or manufacturer's internal tests. The fields for the PayloadTestRequest command are as follows:

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 51,
    "command_name": "PayloadTestRequest",
    "payload": {
      "enableKey": "AQID",
      "value": 1,
      "count": 1
    }
  }
}

The device answers with PayloadTestResponse (see below).

Command: PayloadTestResponse

Purpose

This command is sent by the server on receipt of the PayloadTestRequest command.

Command Identity

Response Fields

Cluster 51 Events

Event 0 — HardwareFaultChange

The HardwareFaultChange Event indicates a change in the set of hardware faults currently detected by the Node.

Event 1 — RadioFaultChange

The RadioFaultChange Event indicates a change in the set of radio faults currently detected by the Node.

Event 2 — NetworkFaultChange

The NetworkFaultChange Event indicates a change in the set of network faults currently detected by the Node.

Event 3 — BootReason

The BootReason Event indicates the reason that caused the device to start-up.

SmartphoneKey Notes

• NetworkInterfaces (attribute 0) is where a device's Thread or Wi-Fi interface and its IPv6 addresses are listed.
• Shadow paths follow endpoint/51/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.