扫地机清洁模式 Cluster（RvcCleanMode）
Cluster ID: 0x0055 |
所在 Endpoint: 通常在 Endpoint 1（功能端点）
RvcCleanMode 是扫地机器人（Robotic Vacuum Cleaner）的清洁强度模式 Cluster， 派生自 ModeBase（0x0049）。它定义了扫地机不同的清洁方式 —— 深度清洁、仅吸尘、仅拖地、吸拖一体等。 与 RvcRunMode（0x0054，运行模式：清扫/映射/回充）搭配使用：RvcRunMode 决定「做什么任务」， RvcCleanMode 决定「用什么强度做」。
RvcCleanMode 继承 ModeBase 的全部命令和属性结构，但不支持 StartUpMode 属性
（规范明确禁止）。开机后的默认清洁模式由 OnMode 控制。
模式标签（ModeTag）在 0x4000~0x4003 范围内定义了 RVC 专属的清洁类型。
命令（Commands）
RvcCleanMode 只有一个命令 ChangeToMode，继承自 ModeBase。
设备收到后切换清洁模式，并通过 ChangeToModeResponse 返回执行结果。
ChangeToMode —— 切换模式（0x00）
请求设备切换到指定的清洁模式。NewMode 必须是
SupportedModes 列表中存在的 Mode 值，否则设备会拒绝。
| 参数 | 类型 | 说明 |
|---|---|---|
| NewMode | uint8 | 目标模式编号，取自 SupportedModes 中的 Mode 字段 |
扫地机运行中时切换清洁模式，设备可能会拒绝并返回
InvalidInMode (0x03)。部分设备只允许在空闲或回充状态下切换。
建议先检查 RvcRunMode 的 CurrentMode，确认设备处于非活动状态再切换。
ChangeToModeResponse —— 响应（0x01）
设备收到 ChangeToMode 后返回此响应，指示切换是否成功。
| 字段 | 类型 | 说明 |
|---|---|---|
| Status | uint8 | 状态码。0x00 (Success) 表示切换成功，其余见状态码 |
| StatusText | string | 可选的说明文字，失败时提供更多信息 |
属性详解
RvcCleanMode 继承 ModeBase 的三个属性。注意：ModeBase 定义的 StartUpMode (0x0002)
在 RvcCleanMode 中被禁止，不会出现。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x0000 |
SupportedModes | list<ModeOptionStruct> | 设备支持的所有清洁模式 |
0x0001 |
CurrentMode | uint8 | 当前清洁模式 |
0x0003 |
OnMode 新版已移除 | uint8 / null | 开机后自动切换到的模式 |
SupportedModes —— 模式列表（0x0000）
设备支持的全部清洁模式列表。每个模式包含编号、标签和模式标签（ModeTag）， ModeTag 用于标识该模式的清洁类型（如深度清洁、仅吸尘等）。
| 字段（ModeOptionStruct） | 类型 | 说明 |
|---|---|---|
| Label | string | 模式的可读名称，最长 64 字符，如「深度清洁」「仅吸尘」 |
| Mode | uint8 | 模式编号，在列表内唯一。ChangeToMode 命令的参数就是这个值 |
| ModeTags | list<ModeTagStruct> | 模式标签列表，至少一个。详见模式标签 |
CurrentMode —— 当前模式（0x0001）
设备当前的清洁模式编号，始终是 SupportedModes 中某个条目的 Mode 值。 订阅此属性可以在模式切换时同步更新 App 界面。
OnMode —— 开机模式（0x0003） 新版已移除
OnMode 已不在较新版本的 Matter 规范中（本站对照的 connectedhomeip v1.6 官方定义里已没有它）。按新版本开发的设备不会实现它，这里保留说明仅供对接旧设备时参考。新版本中控制端通过 ChangeToMode 命令切换模式。
设备开机后自动切换到的清洁模式。Nullable —— null
表示开机后保持上次使用的模式。写入需要操作权限。
ModeBase 规范中定义了 StartUpMode (0x0002)，但 RvcCleanMode
明确禁止使用 StartUpMode。开机模式的控制统一通过 OnMode 完成。
如果 OnMode 为 null，设备保持断电前的清洁模式。
模式标签（ModeTag）
RvcCleanMode 在 0x4000~0x4003 范围内定义了 4 个专属标签，用于标识清洁方式的语义。 App 可以根据 ModeTag 展示对应的图标或分类，而不依赖 Label 字符串匹配。
除了上述 RVC 专属标签，每个模式还可以携带 ModeBase 定义的通用标签，
如 Auto (0x0000)、Quick (0x0001)、Quiet (0x0002) 等。
一个模式可以同时拥有多个标签 —— 例如「安静吸尘」可以标记为
VacuumOnly (0x4001) + Quiet (0x0002)。
状态码（StatusCode）
ChangeToModeResponse 中的 Status 字段使用以下状态码，与 RvcRunMode 共享同一套扩展定义。
扫地机在「清扫中」「回充中」等运行状态下，切换清洁模式通常会被拒绝
（返回 InvalidInMode）。建议在发送 ChangeToMode 前，
先读取 RvcRunMode 的 CurrentMode 确认设备处于空闲或待机状态。
示例数据
一台支持四种清洁模式的扫地机器人，当前处于「吸拖一体」模式：
{
// --- 模式列表 ---
"0x0000": [ // SupportedModes
{
"Label": "深度清洁",
"Mode": 0,
"ModeTags": [{ "Value": 16384 }] // DeepClean (0x4000)
},
{
"Label": "仅吸尘",
"Mode": 1,
"ModeTags": [{ "Value": 16385 }] // VacuumOnly (0x4001)
},
{
"Label": "仅拖地",
"Mode": 2,
"ModeTags": [{ "Value": 16386 }] // MopOnly (0x4002)
},
{
"Label": "吸拖一体",
"Mode": 3,
"ModeTags": [{ "Value": 16387 }] // VacuumAndMop (0x4003)
}
],
// --- 当前模式 ---
"0x0001": 3 // CurrentMode = 3（吸拖一体）
}
不同厂商的扫地机支持的模式数量和标签可能不同。有些机型没有拖地模块，
就不会出现 MopOnly 和 VacuumAndMop 标签。
App 应始终以 SupportedModes 返回的实际列表为准，
通过 ModeTag 识别清洁类型，用 Label 作为展示文字。
常见场景
场景 1：用户切换清洁模式
- App 读取
SupportedModes (0x0000)，获取设备支持的所有清洁模式列表 - 根据每个模式的 ModeTag 展示对应图标 —— 如 VacuumOnly 显示吸尘器图标，MopOnly 显示拖布图标
- 用户选择「仅拖地」（Mode = 2），App 发送
ChangeToMode，NewMode = 2 - 设备返回
ChangeToModeResponse，Status =0x00 (Success) - App 订阅
CurrentMode (0x0001)变化，确认已切换到目标模式并更新高亮
场景 2：设置开机默认清洁模式
- 用户在设置页选择「开机默认使用深度清洁」
- App 写入
OnMode (0x0003)新版已移除 = 0（深度清洁的 Mode 值） - 下次扫地机开机或从充电桩激活时，自动切换到深度清洁模式
- 如果用户选择「保持上次模式」，App 写入
OnMode = null