OperationalState Cluster

Cluster ID: 0x0060  |  Endpoint: Typically on Endpoint 1 (application endpoint)

OperationalState is a general-purpose state machine Cluster in Matter for describing appliance operational states. It provides a unified control interface for devices requiring Start/Pause/Stop/Resume operations, such as washing machines, dryers, ovens, and robot vacuums. As the base Cluster, device-specific variants (e.g., OvenCavityOperationalState, RVCOperationalState) all inherit from it.

Commands

OperationalState Cluster has 4 commands corresponding to basic appliance operations. All commands return an OperationalCommandResponse containing an ErrorStateStruct to indicate success or failure. Click a command ID in the table below to jump to its detailed description.

Pause (0x00)

Pauses the device's current operation. On success，OperationalState attribute changes to Paused (2). The device preserves current progress and can be resumed via the Resume command. No parameters required.

↑ Back to Commands

Stop (0x01)

Completely stops the device's current operation. On success，OperationalState attribute changes to Stopped (0). Unlike Pause, Stop discards current progress; a new Start is required to begin a new operation cycle. No parameters required.

↑ Back to Commands

Start (0x02)

Starts the device's operation. On success，OperationalState attribute changes to Running (1). Typically called when the device is in the Stopped (0) state. No parameters required.

↑ Back to Commands

Resume (0x03)

Resumes an operation previously paused by Pause. On success，OperationalState attribute changes to Running (1) and the device continues from where it was paused. No parameters required.

↑ Back to Commands

OperationalCommandResponse

All four commands (Pause/Stop/Start/Resume) return this response. It contains an ErrorStateStruct indicating whether the command succeeded.

↑ Back to Commands

Attributes

OperationalState Cluster has 6 application attributes. Click an attribute ID below to jump to its detailed description.

Phase Information (0x0000, 0x0001, 0x0002)

Describes the phase progress and remaining time of the current operation. For multi-phase devices (e.g., washing machines, dryers), these attributes let the app display precise progress.

↑ Back to Attributes

Operational State (0x0003, 0x0004, 0x0005)

Describes the device operational state and error information. This is the primary data source for device status in the app.

↑ Back to Attributes

Enum Definitions

OperationalStateEnum

Operational state enumeration. The standard defines 4 base values; device-specific Clusters may extend 0x80-0xBF.

ErrorStateEnum

Error state enumeration. The standard defines 4 generic error codes; device-specific Clusters may extend 0x40-0x7F.

Data Structures

ErrorStateStruct

Describes the device's error information. Used for both the OperationalError attribute and command responses. Contains an error code, optional localized label, and detailed description.

OperationalStateStruct

Used in the OperationalStateList attribute to describe each operational state the device supports.

Events

OperationalState Cluster defines 2 events for notifying controllers of important state changes.

OperationalError Event

Triggered when the device enters an error state. Event priority is CRITICAL, ensuring controllers receive timely error notifications.

OperationCompletion Event

Triggered when the device completes a full operation cycle. Event priority is INFO. This event carries time statistics for the app to display an operation report.

Example Data

Read result from an OperationalState Cluster on a running washing machine:

{
  // --- Phase Information ---
  "0x0000": ["Soak", "Wash", "Rinse", "Spin"],  // PhaseList (operation phase list)
  "0x0001": 1,                                   // CurrentPhase = 1（currently in "Wash" phase）
  "0x0002": 1620,                                // CountdownTime = 1620 seconds (27 min remaining)

  // --- Operational State ---
  "0x0003": [                                    // OperationalStateList (supported states)
    { "OperationalStateID": 0, "OperationalStateLabel": "Stopped" },
    { "OperationalStateID": 1, "OperationalStateLabel": "Running" },
    { "OperationalStateID": 2, "OperationalStateLabel": "Paused" },
    { "OperationalStateID": 3, "OperationalStateLabel": "Error" }
  ],
  "0x0004": 1,                                   // OperationalState = Running
  "0x0005": {                                    // OperationalError (no current error)
    "ErrorStateID": 0,
    "ErrorStateLabel": "",
    "ErrorStateDetails": ""
  }
}

Common Scenarios

Scenario 1: Complete Washing Machine Lifecycle

1. The user selects a wash program; the app sends Start (0x02) command
2. The washer state becomes Running (1); PhaseList returns ["Soak", "Wash", "Rinse", "Spin"] with CurrentPhase = 0 (Soak)
3. The app subscribes to CurrentPhase and CountdownTime changes, updating progress bar and countdown in real time
4. The washer progresses through phases: CurrentPhase goes 0 → 1 → 2 → 3
5. On completion, the device becomes Stopped (0) and fires the OperationCompletion event
6. The app shows a completion notification: "Wash complete, total: 65 minutes"

Scenario 2: Error Handling and Recovery

1. The washing machine is running and detects a water inlet anomaly
2. The device state becomes Error (3); OperationalError updates to:
   • ErrorStateID = 1 (UnableToStartOrResume)
   • ErrorStateLabel = "Water Inlet Error"
   • ErrorStateDetails = "Water flow below threshold; check if the faucet is open"
3. The device fires the OperationalError event (CRITICAL); the app shows an error notification
4. After fixing the inlet, send Stop (0x01) to clear the error state
5. The device returns to Stopped (0); send Start (0x02) to begin a new cycle

Scenario 3: Progress Tracking and UI Display

1. The app reads PhaseList and renders a progress indicator (e.g., a 4-step bar)
2. Subscribe to CurrentPhase; highlight the corresponding step on change
3. Subscribe to CountdownTime; update the countdown in real time
4. Subscribe to OperationalState; switch UI based on state:
   • Stopped (0) —— show the "Start" button
   • Running (1) —— show "Pause" and "Stop" buttons with progress and countdown
   • Paused (2) —— show "Resume" and "Stop" buttons; countdown is paused
   • Error (3) —— show error information and a "Stop" button
5. Handle PhaseList = null — do not show phase progress; display only state and countdown