洗碗机模式 Cluster（DishwasherMode）

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

DishwasherMode 用于控制洗碗机的洗涤模式选择。 它派生自 ModeBase Cluster，结构与 LaundryWasherMode 完全一致， 区别仅在于 ModeTag 值针对洗碗机场景定义（Normal / Heavy / Light）。

ModeBase 派生 Cluster

DishwasherMode 是 ModeBase（0x0050）的派生 Cluster，不能独立实现 —— 它复用 ModeBase 的全部命令和属性定义，仅扩展了专属的 ModeTag 枚举值。 了解 ModeBase 的机制后，所有 Mode 类 Cluster（洗衣机、洗碗机、冰箱等）都是同一套用法。

命令（Commands）

DishwasherMode 继承自 ModeBase，只有一对命令：客户端发送 ChangeToMode，设备返回 ChangeToModeResponse。

ID 方向 名称 说明
0x00 客户端 → 设备 ChangeToMode 切换到指定模式
0x01 设备 → 客户端 ChangeToModeResponse 返回切换结果

ChangeToMode —— 切换模式（0x00）

请求设备切换到指定的洗涤模式。目标模式必须是 SupportedModes 中存在的值。

参数类型说明
NewMode uint8 目标模式编号，必须在 SupportedModes 列表中存在
运行中切换

洗碗机正在运行时，设备可能拒绝模式切换并在 ChangeToModeResponse 中返回错误状态码。 具体行为取决于厂商实现。

↑ 返回命令列表

ChangeToModeResponse —— 切换结果（0x01）

设备收到 ChangeToMode 后返回的响应，告知切换是否成功。

参数类型说明
Status enum8 0x00 = 成功；其他值为厂商自定义错误码
StatusText string（可选） 失败时的可读错误描述，最长 64 字节

↑ 返回命令列表

属性详解

DishwasherMode 继承 ModeBase 的 4 个属性。点击属性 ID 可跳转到详细说明。

ID 名称 类型 说明
0x0000 SupportedModes list<ModeOptionStruct> 设备支持的所有模式列表
0x0001 CurrentMode uint8 当前激活的模式编号
0x0002 StartUpMode 新版已移除 uint8 / null 上电后的初始模式
0x0003 OnMode 新版已移除 uint8 / null 开机时强制切换到的模式

SupportedModes —— 支持的模式列表（0x0000）

设备支持的全部洗涤模式，列表中每个元素是一个 ModeOptionStruct：

字段类型说明
Label string 模式的可读名称（如 "Normal"、"Heavy"）
Mode uint8 模式编号，在列表中唯一
ModeTags list<ModeTagStruct> 模式标签，用于标识模式的语义（见 ModeTag 枚举）
Mode 编号由厂商定义

Mode 编号（0、1、2 …）只是厂商自定义的序号，不同厂商可能不一样。 要判断某个模式的语义含义，应查看 ModeTags 中的 ModeTag 值而非 Mode 编号。

↑ 返回属性列表

CurrentMode —— 当前模式（0x0001）

设备当前激活的模式编号，值必须是 SupportedModes 中某个条目的 Mode 值。 订阅此属性可以在模式变化时同步更新 App 界面。

↑ 返回属性列表

StartUpMode —— 上电模式（0x0002） 新版已移除

新版 Matter 已移除

StartUpMode 已不在较新版本的 Matter 规范中（本站对照的 connectedhomeip v1.6 官方定义里已没有它）。按新版本开发的设备不会实现它，这里保留说明仅供对接旧设备时参考。新版本中上电后的模式由设备自行决定，控制端改用 ChangeToMode 命令切换模式。

设备上电（或重启）后使用的初始模式。Nullable —— null 表示不指定， 由设备自行决定（通常恢复断电前的模式）。

↑ 返回属性列表

OnMode —— 开机模式（0x0003） 新版已移除

新版 Matter 已移除

OnMode 已不在较新版本的 Matter 规范中（本站对照的 connectedhomeip v1.6 官方定义里已没有它）。按新版本开发的设备不会实现它，这里保留说明仅供对接旧设备时参考。它依赖的 DEPONOFF（OnOff 依赖）特性也一并被移除；控制端改用 ChangeToMode 命令切换模式。

设备从 Off 切换到 On 时强制切换到的模式。Nullable —— null 表示开机时不强制切换，保持 CurrentMode 不变。

StartUpMode 与 OnMode 的区别

StartUpMode 在设备上电（断电恢复）时生效； OnMode 在设备从关闭状态切换到开启状态时生效（如用户按下开始按钮）。 两者触发时机不同，可以设置不同的值。

↑ 返回属性列表

ModeTag 枚举

DishwasherMode 定义了 3 个专属 ModeTag 值，用于标识洗碗机洗涤模式的语义。 App 应通过 ModeTag 识别模式含义，而非依赖 Label 字符串或 Mode 编号。

0x4000
Normal 标准洗涤 —— 日常餐具的默认模式
0x4001
Heavy 强力洗涤 —— 重油污、锅具等顽固污渍
0x4002
Light 轻柔洗涤 —— 轻微脏污、精致餐具
通用 ModeTag

除了上述专属 Tag，设备也可以使用 ModeBase 定义的通用 Tag，例如 0x0000（Auto）、0x0001（Quick）、0x0002（Quiet）等。 一个模式可以同时携带多个 Tag。

示例数据

一台支持三种洗涤模式的洗碗机，当前处于 Normal 模式时的 DishwasherMode Cluster 读取结果：

{
  // --- 当前模式 ---
  "0x0000": [                 // SupportedModes — 支持的模式列表
    {
      "Label": "Normal",
      "Mode": 0,
      "ModeTags": [{ "Value": 16384 }]
    },
    {
      "Label": "Heavy",
      "Mode": 1,
      "ModeTags": [{ "Value": 16385 }]
    },
    {
      "Label": "Light",
      "Mode": 2,
      "ModeTags": [{ "Value": 16386 }]
    }
  ],
  "0x0001": 0                // CurrentMode = 0（当前为 Normal 模式）
}

常见场景

场景 1：切换洗涤模式

  1. 读取 SupportedModes (0x0000)，获取设备支持的全部模式及其 ModeTag
  2. 在 App 中根据 ModeTag 展示模式选项（如「标准」「强力」「轻柔」）
  3. 用户选择后，发送 ChangeToMode，参数 NewMode 设为目标模式的编号
  4. 检查 ChangeToModeResponse 的 Status —— 如果洗碗机正在运行，可能返回错误
  5. 订阅 CurrentMode (0x0001) 确认切换成功

场景 2：配置默认模式

  1. 用户在 App 设置页选择「每次开机默认使用强力模式」
  2. 写入 OnMode (0x0003) 新版已移除 为 Heavy 模式对应的编号（例如 1）
  3. 之后每次洗碗机从关闭切换到开启，都会自动进入强力模式
  4. 如需取消强制模式，将 OnMode 写回 null