洗衣机模式 Cluster（LaundryWasherMode）

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

LaundryWasherMode 是 Matter 中用于洗衣机模式选择的 Cluster，派生自 ModeBase Cluster。 它允许用户在洗衣机支持的多种洗涤模式之间切换，例如标准洗、轻柔洗、强力洗、漂白洗等。 每种模式通过语义标签（ModeTag）描述其用途，使不同厂商的洗衣机能以统一方式被控制。

派生自 ModeBase

LaundryWasherMode 继承了 ModeBase Cluster 的全部命令和属性结构， 并定义了洗衣机专属的 ModeTag 值（0x4000 ~ 0x4003）。 如果你已经熟悉 ModeBase 的工作方式，这个 Cluster 的使用方式完全一致，只是模式标签不同。

命令（Commands）

LaundryWasherMode Cluster 只有一个命令 ChangeToMode，用于切换洗涤模式。 命令执行后设备返回 ChangeToModeResponse，告知切换是否成功。

ID 名称 方向 说明
0x00 ChangeToMode Client → Server 切换到指定洗涤模式
0x01 ChangeToModeResponse Server → Client 切换结果响应（Status + StatusText）

ChangeToMode -- 切换模式（0x00）

请求设备切换到指定的洗涤模式。NewMode 的值必须是 SupportedModes 列表中某个 ModeOptionStruct 的 Mode 字段。 设备收到后返回 ChangeToModeResponse。

请求参数

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

响应字段（ChangeToModeResponse）

字段类型说明
Status enum8 操作结果状态码（见状态码）
StatusText string（可选） 人类可读的状态描述，失败时提供原因
使用场景

用户在 App 上选择「轻柔洗」模式，App 发送 ChangeToMode（NewMode = 1）。 洗衣机返回 ChangeToModeResponse（Status = 0x00, Success），CurrentMode 更新为 1。 如果洗衣机正在运行中不允许切换，会返回 GenericFailure 并在 StatusText 中说明原因。

↑ 返回命令列表

属性详解

LaundryWasherMode Cluster 继承 ModeBase 的 4 个属性。

ID 名称 类型 说明
0x0000 SupportedModes list<ModeOptionStruct> 设备支持的所有洗涤模式
0x0001 CurrentMode uint8 当前选中的模式
0x0002 StartUpMode 新版已移除 uint8 / null 设备启动时的默认模式
0x0003 OnMode 新版已移除 uint8 / null 设备开机时自动切换到的模式

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

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

字段类型说明
Label string 模式名称，供人类阅读（如 "Normal"、"Delicate"）
Mode uint8 模式编号，在列表中唯一，用于 ChangeToMode 命令
ModeTags list<ModeTagStruct> 语义标签列表，描述模式的用途（见ModeTag 标签）
Label 与 ModeTag 的区别

Label 是厂商自定义的显示文字，不同厂商可能用不同措辞（"Normal"、"Standard"、"Regular"）。 ModeTag 是标准化的语义标签，App 应优先根据 ModeTag 值判断模式类型，Label 仅用于界面展示。

↑ 返回属性列表

CurrentMode -- 当前模式（0x0001）

当前选中的洗涤模式编号。值必须是 SupportedModes 中某个 ModeOptionStruct 的 Mode 字段。 通过 ChangeToMode 命令修改。可订阅此属性获取模式变更通知。

↑ 返回属性列表

StartUpMode -- 启动模式（0x0002） 新版已移除

新版 Matter 已移除

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

设备上电或重启后的初始模式。Nullable -- 值为 null 时表示保持上次断电前的模式。 设置具体值时，该值必须存在于 SupportedModes 列表中。

↑ 返回属性列表

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

新版 Matter 已移除

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

当设备从 Off 切换到 On 时自动应用的模式。Nullable -- 值为 null 时不覆盖，保持 CurrentMode 不变。 如果 OnMode 有值，每次开机都会将 CurrentMode 强制设为该值，忽略 StartUpMode 的设置。

OnMode 与 StartUpMode 的优先级

如果 OnMode 不为 null，它的优先级高于 StartUpMode。 设备上电流程：先应用 StartUpMode（如果有），再在 Off → On 时应用 OnMode 覆盖。 实际效果是开机后始终使用 OnMode 指定的模式。

↑ 返回属性列表

ModeTag 语义标签

LaundryWasherMode 定义了 4 个专属 ModeTag 值，用于标准化描述洗涤模式的类型。 App 应根据这些标签识别模式用途，而不是依赖厂商自定义的 Label 文字。

0x4000
Normal 标准洗 -- 日常衣物的默认洗涤模式
0x4001
Delicate 轻柔洗 -- 适用于丝绸、内衣等精细衣物
0x4002
Heavy 强力洗 -- 适用于重度污渍的工作服、运动服等
0x4003
Whites 漂白洗 -- 专为白色衣物设计，通常使用更高水温

状态码（StatusCode）

ChangeToModeResponse 中 Status 字段的可能取值：

0x00
Success 模式切换成功
0x01
UnsupportedMode 请求的模式编号不存在于 SupportedModes 中
0x02
GenericFailure 通用失败 -- 设备当前状态不允许切换（如正在运行中）

示例数据

一台支持 4 种洗涤模式、当前处于标准洗的洗衣机的 LaundryWasherMode Cluster 读取结果：

{
  // --- 支持的模式列表 ---
  "0x0000": [                    // SupportedModes
    {
      "Label": "Normal",
      "Mode": 0,
      "ModeTags": [{ "Value": 16384 }]   // 0x4000 = Normal
    },
    {
      "Label": "Delicate",
      "Mode": 1,
      "ModeTags": [{ "Value": 16385 }]   // 0x4001 = Delicate
    },
    {
      "Label": "Heavy",
      "Mode": 2,
      "ModeTags": [{ "Value": 16386 }]   // 0x4002 = Heavy
    },
    {
      "Label": "Whites",
      "Mode": 3,
      "ModeTags": [{ "Value": 16387 }]   // 0x4003 = Whites
    }
  ],

  // --- 当前模式 ---
  "0x0001": 0                    // CurrentMode = 0（Normal）

  // --- 启动与开机模式 ---
}
开发提示

SupportedModes 的内容由设备厂商定义，不同洗衣机支持的模式数量和编号可能不同。 App 展示模式列表时应动态读取 SupportedModes，不要硬编码模式选项。 使用 ModeTag 值判断模式类型，而不是比较 Label 字符串。

常见场景

场景 1：选择洗涤模式

  1. 读取 SupportedModes (0x0000) 获取设备支持的所有洗涤模式
  2. 在 App 界面展示模式列表，根据 ModeTag 值显示对应图标和说明
  3. 用户选择「轻柔洗」，发送 ChangeToMode (0x00)，NewMode 填入对应的 Mode 编号
  4. 检查 ChangeToModeResponse 的 Status：
    • 0x00（Success）-- 切换成功，订阅 CurrentMode 确认更新
    • 0x01（UnsupportedMode）-- 模式编号无效，检查是否与 SupportedModes 同步
    • 0x02（GenericFailure）-- 设备拒绝切换，读取 StatusText 展示原因（如「洗涤中无法切换模式」）

场景 2：配置启动模式

  1. 读取 SupportedModes (0x0000) 获取可选模式列表
  2. 写入 StartUpMode (0x0002) 新版已移除 设置上电默认模式：
    • 写入具体 Mode 编号 -- 每次上电自动使用该模式（如始终默认标准洗）
    • 写入 null -- 保持断电前的模式（推荐）
  3. 如需每次开机强制使用某个模式，可设置 OnMode (0x0003) 新版已移除，其优先级高于 StartUpMode
  4. 大多数家用场景建议两者都设为 null，让用户每次手动选择模式