扫地机器人操作状态 Cluster（RvcOperationalState）

Cluster ID: 0x0061  |  所在 Endpoint: 通常在 Endpoint 1（功能端点） |  继承自: OperationalState（0x0060）

RvcOperationalState 是 OperationalState（0x0060） 的扫地机器人专用派生 Cluster。它继承了基础状态机的所有属性和事件结构， 但根据扫地机器人的实际使用场景做了重要调整：

• 去掉了 Start 和 Resume 命令 —— 扫地机器人通过 RvcRunMode Cluster 选择清扫模式来启动，不直接用 Start
• 新增了 GoHome 命令（0x80） —— 让机器人主动回充电座
• 扩展了 3 个 RVC 专属运行状态 —— SeekingCharger（寻找充电座）、Charging（充电中）、Docked（已停靠）
• 扩展了 8 个 RVC 专属错误码 —— 涵盖充电座、卡住、尘盒、水箱、拖布等常见故障

命令（Commands）

RvcOperationalState Cluster 共有 3 个命令。相比基础 OperationalState 的 4 个命令， 去掉了 Start（0x02）和 Resume（0x03）， 因为扫地机器人的启动和模式切换由 RvcRunMode Cluster 负责。 新增了 GoHome（0x80） 命令，用于让机器人返回充电座。 所有命令执行后都会返回 OperationalCommandResponse，包含一个 ErrorStateStruct 用于指示操作是否成功。

Pause —— 暂停（0x00）

暂停机器人当前正在进行的操作（清扫、回充等）。执行成功后，OperationalState 属性变为 Paused (2)。机器人会原地停止并保留当前位置和清扫进度。不需要参数。

↑ 返回命令列表

Stop —— 停止（0x01） 新版已移除

完全停止机器人的当前操作。执行成功后，OperationalState 属性变为 Stopped (0)。与 Pause 不同，Stop 会结束本次清扫任务， 需要通过 RvcRunMode 重新选择模式才能开始新的清扫。不需要参数。

↑ 返回命令列表

GoHome —— 返回充电座（0x80）

RVC 专属命令。指示机器人停止当前操作并返回充电座。 执行成功后，OperationalState 属性变为 SeekingCharger (0x40)， 机器人开始自动导航回充电座。到达后状态依次变为 Charging (0x41) → Docked (0x42)。不需要参数。

↑ 返回命令列表

OperationalCommandResponse —— 命令响应

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

↑ 返回命令列表

属性详解

RvcOperationalState Cluster 继承了基础 OperationalState 的全部 6 个属性，定义完全一致。 点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

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

描述机器人当前清扫任务的阶段进度和剩余时间。 扫地机器人的阶段划分可能包括：主区域清扫、沿边清扫、拖地、回充等。

↑ 返回属性列表

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

描述机器人的运行状态和错误信息。OperationalStateList 会包含基础的 4 个状态 以及 RVC 扩展的 3 个状态（SeekingCharger/Charging/Docked）。

↑ 返回属性列表

枚举定义

OperationalStateEnum —— 运行状态

RVC 的运行状态枚举继承了基础 OperationalState 的 4 个标准值（0~3）， 并在 0x40~0x42 范围内扩展了 3 个扫地机器人专属状态。

基础状态（继承自 OperationalState）

RVC 扩展状态

ErrorStateEnum —— 错误类型

RVC 的错误状态枚举继承了基础的 4 个通用错误码（0~3）， 并在 0x40~0x47 范围内扩展了 8 个扫地机器人专属错误码，涵盖充电座、机械故障、耗材等常见问题。

基础错误码（继承自 OperationalState）

RVC 扩展错误码

数据结构

ErrorStateStruct —— 错误状态结构

用于描述机器人的错误信息。既用于 OperationalError 属性，也用于命令响应。 结构与基础 OperationalState 完全一致。

OperationalStateStruct —— 操作状态结构

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

事件（Events）

RvcOperationalState Cluster 继承了基础 OperationalState 的 2 个事件， 用于通知控制端机器人的重要状态变化。

OperationalError 事件

当机器人进入错误状态时触发此事件。事件优先级为 CRITICAL， 确保 App 能及时收到错误通知（如机器人卡住、尘盒已满等）。

OperationCompletion 事件

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

示例数据

一台正在清扫中的扫地机器人的 RvcOperationalState Cluster 读取结果：

{
  // --- 阶段信息 ---
  "0x0000": ["主刷清扫", "沿边清扫", "回充中"],  // PhaseList（操作阶段列表）
  "0x0001": 0,                                    // CurrentPhase = 0（当前处于「主刷清扫」阶段）
  "0x0002": 2400,                                  // CountdownTime = 2400 秒（剩余约 40 分钟）

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

常见场景

场景 1：完整清扫生命周期

1. 机器人处于 Docked (0x42) 状态，停靠在充电座上待机
2. 用户通过 RvcRunMode Cluster 发送 ChangeToMode 命令，选择「标准清扫」模式
3. 机器人离开充电座，状态变为 Running (1)，开始清扫
4. App 订阅 OperationalState、CurrentPhase、CountdownTime， 实时更新清扫进度和剩余时间
5. 清扫完成后，机器人自动进入 SeekingCharger (0x40) 状态回充
6. 到达充电座后变为 Charging (0x41)，充满电后变为 Docked (0x42)
7. 触发 OperationCompletion 事件，App 展示清扫报告：「清扫完成，总耗时 45 分钟」

场景 2：清扫中的错误处理

1. 机器人正在清扫（Running (1)），突然被地毯边缘卡住
2. 机器人尝试脱困失败，状态变为 Error (3)，OperationalError 更新为：
   • ErrorStateID = 0x41 (Stuck)
   • ErrorStateLabel = "机器人卡住"
   • ErrorStateDetails = "左侧轮子无法转动，请检查是否有异物缠绕"
3. 设备触发 OperationalError 事件（CRITICAL 优先级），App 弹出推送通知
4. App 根据错误码 0x41（Stuck）展示对应的操作指引：「请将机器人搬到开阔位置」
5. 用户处理完毕后，发送 Stop (0x01) 新版已移除 清除错误状态
6. 通过 RvcRunMode 重新启动清扫任务

场景 3：手动回充（GoHome）

1. 机器人正在清扫（Running (1)），用户想让它提前回充
2. App 发送 GoHome (0x80) 命令
3. 机器人停止清扫，状态变为 SeekingCharger (0x40)，开始自动导航回充电座
4. App 可以展示「正在返回充电座...」的状态提示
5. 机器人到达充电座后，状态变为 Charging (0x41)
6. 如果导航过程中找不到充电座，状态变为 Error (3)， 错误码为 FailedToFindChargingDock (0x40)
7. App 展示：「找不到充电座，请检查充电座是否通电并且前方无障碍物」