扫地机运行模式 Cluster（RvcRunMode）
Cluster ID: 0x0054 |
所在 Endpoint: 通常在 Endpoint 1（功能端点） |
基类: ModeBase（0x0050）
RvcRunMode 是 Matter 为扫地机器人（Robot Vacuum Cleaner）定义的运行模式 Cluster。 它继承自 ModeBase，专门管理扫地机的高级运行状态 —— 空闲、清扫、建图。 通过切换运行模式，用户可以控制扫地机是开始打扫、绘制地图还是返回待命。
Matter 为扫地机器人定义了三个协作 Cluster，各管一面：
- RvcRunMode（本页）—— 高级运行状态：空闲 / 清扫 / 建图
- RvcCleanMode —— 清扫强度：静音 / 标准 / 深度清洁
- RvcOperationalState —— 实时运行状态：寻找充电座、充电中、卡住等
典型流程：先通过 RvcCleanMode 设好清扫强度，再通过 RvcRunMode 切到清扫模式启动工作， 运行过程中的实时状态（充电、卡住、回充）由 RvcOperationalState 上报。
命令（Commands）
RvcRunMode 继承自 ModeBase，只有一对命令：发送模式切换请求，设备返回执行结果。
ChangeToMode —— 切换运行模式（0x00）
请求设备切换到指定的运行模式。模式编号必须是 SupportedModes 中定义的有效值。
设备收到后会校验当前状态是否允许切换（例如正在充电时可能无法直接开始清扫），然后通过
ChangeToModeResponse 返回结果。
| 参数 | 类型 | 说明 |
|---|---|---|
| NewMode | uint8 | 目标模式编号，必须是 SupportedModes 列表中某个模式的 Mode 字段值 |
使用场景
用户在 App 上点击「开始清扫」，App 发送 ChangeToMode(NewMode=1) 将扫地机从空闲切换到清扫模式。 如果扫地机电量过低或尘盒未安装，设备会在响应中返回对应的错误状态码。
ChangeToModeResponse —— 切换结果（0x01）
设备对 ChangeToMode 命令的响应。通过 Status 字段告知切换是否成功，失败时附带文字说明。
| 字段 | 类型 | 说明 |
|---|---|---|
| Status | uint8 |
0x00 = 成功；其他值为错误码（见状态码章节）
|
| StatusText | string（可选） | 人类可读的状态描述，用于调试或展示给用户 |
Status 字段的值空间分为两段：0x00–0x3F 是 ModeBase 通用错误码（如 GenericFailure、InvalidInMode），
0x40–0x7F 是扫地机专属的错误码（如卡住、尘盒缺失等）。
App 端处理时需要覆盖两段。
属性详解
RvcRunMode 继承 ModeBase 的三个属性。注意：ModeBase 定义了 StartUpMode（0x0002）， 但扫地机不支持该属性 —— 扫地机每次上电后的行为由 OnMode 决定。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x0000 |
SupportedModes | list<ModeOptionStruct> | 设备支持的运行模式列表 |
0x0001 |
CurrentMode | uint8 | 当前运行模式 |
0x0003 |
OnMode 新版已移除 | uint8 / null | 设备唤醒时自动进入的模式 |
SupportedModes —— 支持的模式列表（0x0000）
设备支持的全部运行模式。每个模式包含标签名称、模式编号和一组模式标签（ModeTag）。 列表在设备整个生命周期中固定不变。
| 字段 | 类型 | 说明 |
|---|---|---|
| Label | string | 模式的显示名称，如 "清扫"、"建图" |
| Mode | uint8 | 模式编号，在列表内唯一，作为 ChangeToMode 的参数 |
| ModeTags | list<ModeTagStruct> | 模式标签列表，标识该模式的语义（见模式标签章节） |
CurrentMode —— 当前模式（0x0001）
设备当前的运行模式编号，值必须是 SupportedModes 中某个模式的 Mode 字段。 订阅此属性可以实时跟踪扫地机的运行状态变化。
建议 App 通过 Subscribe 订阅 CurrentMode 的变化，而不是轮询。 当扫地机完成清扫自动回到空闲模式、或因异常停止时，订阅能实时收到通知。
OnMode —— 唤醒模式（0x0003） 新版已移除
OnMode 已不在较新版本的 Matter 规范中（本站对照的 connectedhomeip v1.6 官方定义里已没有它）。按新版本开发的设备不会实现它，这里保留说明仅供对接旧设备时参考。新版本中控制端通过 ChangeToMode 命令切换模式。
设备从非活跃状态唤醒时自动进入的模式。值为 SupportedModes 中某个模式的 Mode 字段，
或 null 表示不自动切换模式。
ModeBase 定义了 StartUpMode（0x0002） 属性，但 RvcRunMode 明确排除了它。
扫地机的上电行为仅由 OnMode 控制。如果你在读取属性时发现 0x0002 不存在，这是正常的。
模式标签（ModeTag）
每个运行模式通过 ModeTag 标识其语义。ModeTag 让不同厂商的扫地机能用不同的 Label 文字， 但 App 仍然能通过标准化的 Tag 值识别出「这是清扫模式」还是「这是建图模式」。
厂商 A 的清扫模式叫 "Auto Clean"（Mode=1），厂商 B 叫 "智能清扫"（Mode=3），
但两者的 ModeTags 都包含 0x4001 (Cleaning)。
App 判断模式语义时应看 ModeTag 而非 Label 或 Mode 编号。
状态码（StatusCode）
ChangeToModeResponse 的 Status 字段使用以下错误码。0x00 表示成功，
0x01–0x03 是 ModeBase 通用错误码，0x41–0x48 是扫地机专属错误码。
通用状态码（ModeBase）
扫地机专属状态码
这些状态码对应的都是用户可以自行解决的物理问题。 App 收到错误码后应向用户展示明确的操作指引，例如「请清空尘盒后重试」「请安装水箱」， 而不是显示通用的「操作失败」。StatusText 字段也可作为兜底的展示文案。
示例数据
一台支持三种运行模式的扫地机器人，当前正在清扫中的 RvcRunMode Cluster 读取结果：
{
// --- 支持的运行模式 ---
"0x0000": [ // SupportedModes（设备支持的模式列表）
{
"Label": "空闲",
"Mode": 0,
"ModeTags": [{ "Value": 16384 }] // 0x4000 = Idle
},
{
"Label": "清扫",
"Mode": 1,
"ModeTags": [{ "Value": 16385 }] // 0x4001 = Cleaning
},
{
"Label": "建图",
"Mode": 2,
"ModeTags": [{ "Value": 16386 }] // 0x4002 = Mapping
}
],
// --- 当前状态 ---
"0x0001": 1 // CurrentMode = 1（当前正在清扫）
}
示例中 ModeTags 的 Value 使用十进制：16384 = 0x4000（Idle），
16385 = 0x4001（Cleaning），16386 = 0x4002（Mapping）。
实际协议传输中使用的是整数值，文档中常写十六进制是为了方便对照规范。
常见场景
场景 1：启动清扫
- 读取
SupportedModes（0x0000），找到 ModeTags 包含0x4001 (Cleaning)的模式，记下其 Mode 编号 - 发送
ChangeToMode（0x00），NewMode 设为上一步得到的编号 - 检查
ChangeToModeResponse的 Status：0x00—— 成功，扫地机开始清扫0x42—— 尘盒未安装，提示用户装好尘盒0x43—— 尘盒已满，提示用户清空0x48—— 电量不足，提示用户先充电
- 订阅
CurrentMode（0x0001），当值变回 Idle 对应的编号时，说明清扫完成
场景 2：查询当前状态并展示
- 读取
SupportedModes（0x0000）获取完整模式列表 - 读取
CurrentMode（0x0001）获取当前模式编号 - 在 SupportedModes 中找到匹配的模式，取其 Label 展示在 App 界面上（如「清扫中」）
- 同时检查 ModeTags 中的 Tag 值，用标准化语义辅助 UI 展示：
0x4000 (Idle)—— 显示待命图标0x4001 (Cleaning)—— 显示清扫动画0x4002 (Mapping)—— 显示地图扫描进度