模式选择 Cluster（ModeSelect）

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

ModeSelect 是一个通用的模式选择 Cluster —— 让设备声明自己支持哪些运行模式，控制端可以查询和切换这些模式。它适用于任何有"多模式"概念的设备：洗衣机的洗涤模式、烘干机的烘干程序、咖啡机的冲泡方式等。

历史遗留（Legacy）Cluster

ModeSelect 是 Matter 早期定义的通用模式选择方案。在较新的 Matter 规范中，它已被各设备类型专属的 Mode Cluster 替代（如 LaundryWasherMode、DishwasherMode、RefrigeratorAndTemperatureControlledCabinetMode 等）。新设备开发建议优先使用设备专属 Mode Cluster；ModeSelect 仍用于旧设备兼容和通用场景。

命令（Commands）

ModeSelect Cluster 只有 1 个命令，非常简洁 —— 指定目标模式的编号即可完成切换。

ID	名称	说明	所需特性
`0x00`	ChangeToMode	切换到指定模式	无

ChangeToMode —— 切换模式（0x00）

将设备切换到指定的运行模式。NewMode 的值必须是 SupportedModes 列表中某个 ModeOptionStruct 的 Mode 字段值，否则设备会返回 INVALID_COMMAND 错误。执行成功后，CurrentMode 属性会更新为 NewMode 的值。

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

使用场景

用户在 App 上选择洗衣机的"快洗"模式，App 读取 SupportedModes 获取模式列表和对应编号，然后发送 ChangeToMode 命令将 NewMode 设为该编号。设备收到命令后切换模式，CurrentMode 随之更新。

↑ 返回命令列表

属性详解

ModeSelect Cluster 共有 6 个属性。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

ID	名称	类型	分组	说明
`0x0000`	Description	string	基本信息	集群用途的可读描述
`0x0001`	StandardNamespace	uint16 / null	基本信息	模式命名空间标识
`0x0002`	SupportedModes	list<ModeOptionStruct>	模式列表	设备支持的所有模式
`0x0003`	CurrentMode	uint8	模式列表	当前运行模式的编号
`0x0004`	StartUpMode	uint8 / null	启动与联动	上电时恢复的模式
`0x0005`	OnMode	uint8 / null	启动与联动	设备开机时自动切换的模式

基本信息（0x0000, 0x0001）

描述这个 ModeSelect Cluster 实例的用途和模式命名空间。

ID	名称	类型	说明
`0x0000`	Description（描述）	string	人类可读的字符串，描述这个 ModeSelect Cluster 的用途。例如 `"烘干模式"`、`"洗涤程序"`。同一设备可能有多个 ModeSelect 实例（分布在不同 Endpoint），每个实例通过 Description 区分功能
`0x0001`	StandardNamespace（标准命名空间）	uint16 / null	标识 `SemanticTag` 值的含义来源。`null` 表示厂商自定义命名空间（MfgSpecific），标准值由 Matter 规范定义。有了命名空间，不同厂商的"节能"模式可以使用相同的 SemanticTag 值，控制端无需逐厂商适配

↑ 返回属性列表

模式列表（0x0002, 0x0003）

设备支持的所有运行模式及当前模式。

ID	名称	类型	说明
`0x0002`	SupportedModes（支持的模式）	list<ModeOptionStruct>	设备声明的全部可用模式，每个元素是一个 ModeOptionStruct。列表至少包含 2 个条目，每个 Mode 值唯一、每个 Label 唯一。列表内容在设备生命周期内通常不变
`0x0003`	CurrentMode（当前模式）	uint8	设备当前正在运行的模式编号。该值始终指向 `SupportedModes` 中某个 `ModeOptionStruct.Mode`。通过 `ChangeToMode` 命令改变，也可被 `OnMode` 或 `StartUpMode` 自动设置

Mode 值不一定连续

SupportedModes 中的 Mode 值是任意 uint8，不要求从 0 开始、也不要求连续。控制端应始终先读取 SupportedModes，拿到合法的 Mode 值列表后再发送 ChangeToMode。

↑ 返回属性列表

启动与联动（0x0004, 0x0005）

控制设备上电和开机时的模式行为。

ID	名称	类型	说明
`0x0004`	StartUpMode（上电模式）	uint8 / null	设备上电（硬件重启）时自动切换到的模式。值必须存在于 `SupportedModes` 中。`null` 表示保持断电前的模式。Nullable 且可选
`0x0005`	OnMode（开机模式）	uint8 / null	设备从 Off 变为 On 时自动切换到的模式（与 OnOff Cluster 联动）。值必须存在于 `SupportedModes` 中。`null` 表示开机不改变模式。需要 DEPONOFF 特性

StartUpMode 与 OnMode 的关系

StartUpMode 在硬件上电时生效（类似 OnOff 的 StartUpOnOff）， OnMode 在软件层面开机时生效（OnOff 从 Off 切到 On 时触发）。如果 OnMode 非空，它的优先级高于 StartUpMode —— 设备上电后，先应用 StartUpMode，再由 OnOff 触发 OnMode，最终模式以 OnMode 为准。

↑ 返回属性列表

结构体定义

ModeSelect Cluster 使用两个结构体来描述模式信息。

ModeOptionStruct

描述一个可选模式，包含显示标签、模式编号和语义标签列表。

字段	类型	说明
Label	string	人类可读的模式名称，如 `"标准"`、`"节能"`、`"快速"`。在同一个 `SupportedModes` 列表中唯一
Mode	uint8	模式编号，在同一个 `SupportedModes` 列表中唯一。此值用于 `ChangeToMode` 命令的 `NewMode` 参数
SemanticTags	list<SemanticTagStruct>	语义标签列表，让控制端理解模式含义而无需解析 Label 文本。可为空列表

SemanticTagStruct

为模式附加机器可读的语义信息。通过标准化的标签值，不同厂商设备的"节能""快速"等模式可以被统一识别。

字段	类型	说明
MfgCode	vendor-id（uint16）	厂商标识。`0x0000` 表示 Matter 标准定义的标签值；非零值表示该厂商自定义的标签值。配合 `StandardNamespace` 使用
Value	uint16	标签值，具体含义取决于 `MfgCode` 和 `StandardNamespace`。例如在标准命名空间中，特定值可能代表"节能"、"快速"等语义

SemanticTag 的意义

如果只有 Label（如"ECO"），控制端需要做自然语言识别才能理解模式含义。有了 SemanticTag，控制端可以直接通过数值判断 —— 比如语音助手可以识别出哪个模式是"节能"，而不用解析各国语言的标签文本。

Feature 位图

ModeSelect Cluster 通过 FeatureMap（0xFFFC）声明设备支持的可选能力：

Bit 0

DEPONOFF（Depends on OnOff）依赖 OnOff Cluster —— 启用后支持 OnMode 属性，设备从关变开时自动切换到指定模式

何时启用 DEPONOFF

如果设备同时拥有 OnOff Cluster（即可以开关），且希望每次开机时自动切到特定模式（如空气净化器开机默认"自动"模式），就应该启用 DEPONOFF 特性。纯模式选择、不涉及开关联动的场景则无需启用。

示例数据

一台烘干机的 ModeSelect Cluster 读取结果 —— 当前运行在"节能"模式：

{
  // --- 基本信息 ---
  "0x0000": "烘干模式",          // Description = "烘干模式"（集群用途描述）
  "0x0001": 0,                   // StandardNamespace = 0（MfgSpecific 命名空间）
  "0x0003": 1,                   // CurrentMode = 1（当前运行在"节能"模式）

  // --- 支持的模式列表 ---
  "0x0002": [                    // SupportedModes
    {
      "Label": "标准",           // 模式 0：标准烘干
      "Mode": 0,
      "SemanticTags": []
    },
    {
      "Label": "节能",           // 模式 1：节能烘干
      "Mode": 1,
      "SemanticTags": [
        { "MfgCode": 0, "Value": 16384 }
      ]
    },
    {
      "Label": "快速",           // 模式 2：快速烘干
      "Mode": 2,
      "SemanticTags": []
    }
  ],

  // --- 启动与联动 ---
  "0x0004": null,                // StartUpMode = null（上电恢复断电前的模式）
  "0x0005": 0                    // OnMode = 0（设备开机时切换到"标准"模式）
}

开发提示

控制端显示模式选择 UI 时，应先读取 SupportedModes (0x0002) 获取完整模式列表，再读取 CurrentMode (0x0003) 高亮当前模式。切换模式前无需先读 CurrentMode —— 直接发 ChangeToMode 即可，设备会校验 NewMode 的合法性。

常见场景

场景 1：App 切换设备运行模式

读取 SupportedModes (0x0002)，获取模式列表（Label + Mode 编号）
在 UI 上展示模式列表，读取 CurrentMode (0x0003) 高亮当前模式
用户点击目标模式，发送 ChangeToMode (0x00)，NewMode 设为该模式的 Mode 值
订阅 CurrentMode 属性变化，确认切换成功后更新 UI

场景 2：设置设备上电默认模式

读取 SupportedModes (0x0002)，让用户选择上电后希望恢复的模式
写入 StartUpMode (0x0004) 的值：
- 指定模式编号 —— 上电后始终切到该模式（如空调始终以"制冷"模式启动）
- null —— 恢复断电前的模式（推荐，用户上次选什么就继续用什么）
注意：如果设备同时设置了 OnMode，开机后 OnMode 会覆盖 StartUpMode 的效果

场景 3：开机自动切换模式（OnOff 联动）

确认设备的 FeatureMap (0xFFFC) 包含 DEPONOFF（Bit 0 = 1）
写入 OnMode (0x0005) 的值 —— 比如空气净化器开机自动进入"自动"模式
当设备通过 OnOff Cluster 从 Off 切到 On 时，CurrentMode 会自动变为 OnMode 指定的值
将 OnMode 设为 null 可取消联动 —— 开机后沿用上一次的模式