Matter Cluster 96 — Operational State Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 96 values in the device shadow use this format:

endpoint_id / 96 / attribute_id

Example:

{
  "1/96/1": 1
}

Data Types

ErrorStateEnum

This type defines the set of known operational error values, and is derived from enum8. The following table defines the applicable ranges for values that are defined within this type.

OperationalStateEnum

This type defines the set of known operational state values, and is derived from enum8. The following table defines the applicable ranges for values that are defined within this type.

ErrorStateStruct (struct)

OperationalStateStruct (struct)

The OperationalStateStruct is used to indicate a possible state of the device.

Cluster 96 Attributes

Cluster 96 defines 6 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 — PhaseList

Path example:

1/96/0

Indicates a list of names of different phases that the device can go through for the selected function or mode. The list may not be in sequence order. For example in a washing machine this could include items such as "pre-soak", "rinse", and "spin". These phases are manufacturer specific and may change when a different function or mode is selected.

Example:

{
  "1/96/0": []
}

Attribute 1 / 0x0001 — CurrentPhase

Path example:

1/96/1

This attribute represents the current phase of operation being performed by the server. This is the positional index representing the value from the set provided in the PhaseList Attribute, where the first item in that list is an index of 0. Thus, this attribute has a maximum value that is "length(PhaseList) - 1". Null if the PhaseList attribute is null or if the PhaseList attribute is an empty list.

Example:

{
  "1/96/1": 1
}

Attribute 2 / 0x0002 — CountdownTime

Path example:

1/96/2

Indicates the estimated time left before the operation is completed, in seconds. A value of 0 (zero) means that the operation has completed. A value of null represents that there is no time currently defined until operation completion. This may happen, for example, because no operation is in progress or because the completion time is unknown.

Example:

{
  "1/96/2": 0
}

Attribute 3 / 0x0003 — OperationalStateList

Path example:

1/96/3

This attribute describes the set of possible operational states that the device exposes. An operational state is a fundamental device state such as Running or Error. Details of the phase of a device when, for example, in a state of Running are provided by the CurrentPhase attribute. All devices must, at a minimum, expose the set of states matching the commands that are also supported by the cluster instance, in addition to Error.

Each entry is a OperationalStateStruct (see Data Types).

Example:

{
  "1/96/3": []
}

Attribute 4 / 0x0004 — OperationalState

Path example:

1/96/4

This attribute specifies the current operational state of a device. This is populated with a valid OperationalStateID from the set of values in the OperationalStateList Attribute.

Values (OperationalStateEnum):

Example:

{
  "1/96/4": 0
}

Attribute 5 / 0x0005 — OperationalError

Path example:

1/96/5

When there is no error detected, this has an ErrorStateID of NoError.

Value is a ErrorStateStruct struct (see Data Types).

Example:

{
  "1/96/5": {
    "errorStateID": 0,
    "errorStateLabel": "example",
    "errorStateDetails": "example"
  }
}

Cluster 96 Commands

Cluster 96 has 4 client-to-server commands and 1 response.

AcceptedCommandList

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

endpoint_id / 96 / 65529

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

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 96,
    "command_name": "Pause",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 96, always use "cluster_id": 96. 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: Pause

Purpose

This command is supported if the device supports remotely pausing the operation. If this command is supported, the Resume command must also be supported. On receipt of this command, the device must pause its operation if it is possible based on the current function of the server. For example, if it is at a point where it is safe to do so and/or permitted, but can be restarted from the point at which pause occurred.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 96,
    "command_name": "Pause",
    "payload": {}
  }
}

The device answers with OperationalCommandResponse (see below).

Command: Stop

Purpose

This command is supported if the device supports remotely stopping the operation. On receipt of this command, the device must stop its operation if it is at a position where it is safe to do so and/or permitted. Restart of the device following the receipt of the Stop command must require attended operation unless remote start is allowed by the device type and any jurisdiction governing remote operation of the device. If this command is received when already in the Stopped state the device must respond with an OperationalCommandResponse command with an ErrorStateID of NoError but take no further action.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 96,
    "command_name": "Stop",
    "payload": {}
  }
}

The device answers with OperationalCommandResponse (see below).

Command: Start

Purpose

This command is supported if the device supports remotely starting the operation. If this command is supported, the 'Stop command must also be supported. On receipt of this command, the device must start its operation if it is safe to do so and the device is in an operational state from which it can be started. There may be either regulatory or manufacturer-imposed safety and security requirements that first necessitate some specific action at the device before a Start command can be honored.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 96,
    "command_name": "Start",
    "payload": {}
  }
}

The device answers with OperationalCommandResponse (see below).

Command: Resume

Purpose

This command is supported if the device supports remotely resuming the operation. If this command is supported, the Pause command must also be supported. On receipt of this command, the device must resume its operation from the point it was at when it received the Pause command, or from the point when it was paused by means outside of this cluster (for example by manual button press). If this command is received when already in the Running state the device must respond with an OperationalCommandResponse command with an ErrorStateID of NoError but take no further action.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 96,
    "command_name": "Resume",
    "payload": {}
  }
}

The device answers with OperationalCommandResponse (see below).

Command: OperationalCommandResponse

Purpose

This command is supported by an implementation if any of the other commands defined by this cluster are supported (i.e. listed in the AcceptedCommandList global attribute). This command must also be supported by an implementation of a derived cluster as a response to any commands that may be additionally defined therein. This command is generated in response to any of the Start, Stop, Pause, or Resume commands.

Command Identity

Response Fields

Cluster 96 Events

Event 0 — OperationalError

This event is generated when a reportable error condition is detected. A device that generates this event must also set the OperationalState attribute to Error, indicating an error condition. This event contains the following fields:

Event 1 — OperationCompletion

This event should be generated when the overall operation ends, successfully or otherwise. For example, the completion of a cleaning operation in a Robot Vacuum Cleaner, or the completion of a wash cycle in a Washing Machine. It is highly recommended that appliances device types employing the Operational State cluster support this event, even if it is optional.

SmartphoneKey Notes

• Cluster 96 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/96/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.