Matter Cluster 97 — RVC Operational State Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 97 values in the device shadow use this format:

endpoint_id / 97 / attribute_id

Example:

{
  "1/97/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 97 Attributes

Cluster 97 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/97/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/97/0": []
}

Attribute 1 / 0x0001 — CurrentPhase

Path example:

1/97/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/97/1": 1
}

Attribute 2 / 0x0002 — CountdownTime

Path example:

1/97/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/97/2": 0
}

Attribute 3 / 0x0003 — OperationalStateList

Path example:

1/97/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/97/3": []
}

Attribute 4 / 0x0004 — OperationalState

Path example:

1/97/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/97/4": 0
}

Attribute 5 / 0x0005 — OperationalError

Path example:

1/97/5

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

Value is a ErrorStateStruct struct (see Data Types).

Example:

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

Cluster 97 Commands

Cluster 97 has 1 client-to-server command and 0 responses.

AcceptedCommandList

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

endpoint_id / 97 / 65529

{
  "1/97/65529": [
    128
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Pause is a server response of the RVC Operational State cluster.

Command Identity

Payload Fields

This response has no fields.

Command: Stop

Purpose

Stop is a server response of the RVC Operational State cluster.

Command Identity

Payload Fields

This response has no fields.

Command: Start

Purpose

Start is a server response of the RVC Operational State cluster.

Command Identity

Payload Fields

This response has no fields.

Command: Resume

Purpose

Resume is a server response of the RVC Operational State cluster.

Command Identity

Payload Fields

This response has no fields.

Command: OperationalCommandResponse

Purpose

OperationalCommandResponse is a server response of the RVC Operational State cluster.

Command Identity

Payload Fields

This response has no fields.

Command: GoHome

Purpose

On receipt of this command, the device must start seeking the charging dock, if possible in the current state of the device. If this command is received when already in the SeekingCharger state the device must respond with an OperationalCommandResponse command with an ErrorStateID of NoError but the command has no other effect. A device that receives this command in any state which does not allow seeking the charger, such as Charging or Docked, must respond with an OperationalCommandResponse command with an ErrorStateID of CommandInvalidInState and has no other effect.

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": 97,
    "command_name": "GoHome",
    "payload": {}
  }
}

Cluster 97 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 97 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/97/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.