操作状态 Cluster（OperationalState）

Cluster ID: 0x0060  |  所在 Endpoint: 通常在 Endpoint 1（功能端点）

OperationalState 是 Matter 中用于描述家电运行状态的通用状态机 Cluster。 它为洗衣机、烘干机、烤箱、扫地机器人等需要「启动/暂停/停止/恢复」操作的设备提供统一的控制接口。 作为基础 Cluster，设备特定的变体（如 OvenCavityOperationalState、RVCOperationalState）都继承自它。

命令（Commands）

OperationalState Cluster 共有 4 个命令，对应家电操作的基本动作。 所有命令执行后都会返回 OperationalCommandResponse，包含一个 ErrorStateStruct 用于指示操作是否成功。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

Pause —— 暂停（0x00）

暂停设备当前正在进行的操作。执行成功后，OperationalState 属性变为 Paused (2)。设备会保留当前进度，可以通过 Resume 命令恢复。 不需要参数。

↑ 返回命令列表

Stop —— 停止（0x01）

完全停止设备的当前操作。执行成功后，OperationalState 属性变为 Stopped (0)。与 Pause 不同，Stop 会放弃当前进度， 需要重新 Start 才能开始新的操作周期。不需要参数。

↑ 返回命令列表

Start —— 启动（0x02）

启动设备的操作。执行成功后，OperationalState 属性变为 Running (1)。通常在设备处于 Stopped (0) 状态时调用。 不需要参数。

↑ 返回命令列表

Resume —— 恢复（0x03）

恢复之前被 Pause 暂停的操作。执行成功后，OperationalState 属性变为 Running (1)，设备从暂停的位置继续执行。不需要参数。

↑ 返回命令列表

OperationalCommandResponse —— 命令响应

所有四个命令（Pause/Stop/Start/Resume）执行后都会返回此响应。 它包含一个 ErrorStateStruct，用于指示命令是否成功。

↑ 返回命令列表

属性详解

OperationalState Cluster 共有 6 个应用属性。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

阶段信息（0x0000, 0x0001, 0x0002）

描述设备当前操作的阶段进度和剩余时间。对于支持多阶段流程的设备（如洗衣机、烘干机），这些属性可以让 App 展示精确的进度信息。

↑ 返回属性列表

运行状态（0x0003, 0x0004, 0x0005）

描述设备的运行状态和错误信息。这是 App 上展示设备状态的核心数据源。

↑ 返回属性列表

枚举定义

OperationalStateEnum —— 运行状态

设备的运行状态枚举。标准定义了 4 个基础值，设备特定的 Cluster 可以在 0x80~0xBF 范围内扩展。

ErrorStateEnum —— 错误类型

错误状态枚举。标准定义了 4 个通用错误码，设备特定的 Cluster 可以在 0x40~0x7F 范围内扩展。

数据结构

ErrorStateStruct —— 错误状态结构

用于描述设备的错误信息。既用于 OperationalError 属性，也用于命令响应。 包含错误码、可选的本地化标签和详细描述。

OperationalStateStruct —— 操作状态结构

用于 OperationalStateList 属性中，描述设备支持的每一个运行状态。

事件（Events）

OperationalState Cluster 定义了 2 个事件，用于通知控制端设备的重要状态变化。

OperationalError 事件

当设备进入错误状态时触发此事件。事件优先级为 CRITICAL， 确保控制端能及时收到错误通知。

OperationCompletion 事件

当设备完成一个完整操作周期时触发此事件。事件优先级为 INFO。 该事件携带操作的时间统计信息，方便 App 展示操作报告。

示例数据

一台正在运行中的洗衣机的 OperationalState Cluster 读取结果：

{
  // --- 阶段信息 ---
  "0x0000": ["浸泡", "洗涤", "漂洗", "脱水"],  // PhaseList（操作阶段列表）
  "0x0001": 1,                                   // CurrentPhase = 1（当前处于「洗涤」阶段）
  "0x0002": 1620,                                // CountdownTime = 1620 秒（剩余 27 分钟）

  // --- 运行状态 ---
  "0x0003": [                                    // OperationalStateList（设备支持的状态列表）
    { "OperationalStateID": 0, "OperationalStateLabel": "已停止" },
    { "OperationalStateID": 1, "OperationalStateLabel": "运行中" },
    { "OperationalStateID": 2, "OperationalStateLabel": "已暂停" },
    { "OperationalStateID": 3, "OperationalStateLabel": "错误" }
  ],
  "0x0004": 1,                                   // OperationalState = Running（正在运行）
  "0x0005": {                                    // OperationalError（当前无错误）
    "ErrorStateID": 0,
    "ErrorStateLabel": "",
    "ErrorStateDetails": ""
  }
}

常见场景

场景 1：洗衣机完整洗涤生命周期

1. 用户选好洗涤程序，App 发送 Start (0x02) 命令
2. 洗衣机状态变为 Running (1)，PhaseList 返回 ["浸泡", "洗涤", "漂洗", "脱水"]，CurrentPhase = 0（浸泡）
3. App 订阅 CurrentPhase 和 CountdownTime 属性变化，实时更新进度条和倒计时
4. 洗衣机依次进入各阶段，CurrentPhase 从 0 → 1 → 2 → 3
5. 操作完成后，设备状态变为 Stopped (0)，触发 OperationCompletion 事件
6. App 收到事件，展示完成通知：「洗涤完成，总耗时 65 分钟」

场景 2：错误处理与恢复

1. 洗衣机正在运行，突然检测到进水管异常
2. 设备状态变为 Error (3)，OperationalError 更新为：
   • ErrorStateID = 1 (UnableToStartOrResume)
   • ErrorStateLabel = "进水异常"
   • ErrorStateDetails = "进水流量低于阈值，请检查水龙头是否打开"
3. 设备触发 OperationalError 事件（CRITICAL 优先级），App 弹出错误通知
4. 用户检查并修复进水管后，发送 Stop (0x01) 清除错误状态
5. 设备回到 Stopped (0)，用户重新发送 Start (0x02) 开始新周期

场景 3：进度追踪与界面展示

1. App 读取 PhaseList，根据阶段数量渲染进度指示器（如 4 个步骤的进度条）
2. 订阅 CurrentPhase 属性，收到变化后高亮对应的阶段步骤
3. 订阅 CountdownTime 属性，实时更新倒计时显示
4. 订阅 OperationalState 属性，根据不同状态切换界面：
   • Stopped (0) —— 显示「启动」按钮
   • Running (1) —— 显示「暂停」和「停止」按钮，展示进度和倒计时
   • Paused (2) —— 显示「继续」和「停止」按钮，倒计时暂停
   • Error (3) —— 显示错误信息和「停止」按钮
5. 注意处理 PhaseList = null 的情况 —— 不显示阶段进度，仅显示状态和倒计时