开关 Cluster（OnOff）

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

OnOff 是 Matter 中最基础的控制 Cluster —— 负责设备的开/关/切换操作。 所有需要「开关」能力的设备类型（灯、插座、开关面板等）都依赖这个 Cluster。 它也是入门 Matter 开发时最先接触的 Cluster。

Lighting 特性（LT）

OnOff Cluster 定义了一个 Lighting（LT） Feature。 启用 LT 后，Cluster 会额外提供 GlobalSceneControl、OnTime、OffWaitTime、StartUpOnOff 四个属性， 以及 OffWithEffect、OnWithRecallGlobalScene、OnWithTimedOff 三个高级命令。 灯具类设备通常启用此特性，普通开关面板可能不需要。

命令（Commands）

OnOff Cluster 共有 6 个命令。基础三件套（Off / On / Toggle）是所有设备都支持的， 后三个高级命令需要设备启用 Lighting（LT）特性。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

ID 名称 说明 所需特性
0x00 Off 关闭设备 无
0x01 On 开启设备 无
0x02 Toggle 切换开关状态 无
0x40 OffWithEffect 带过渡效果关闭 LT
0x41 OnWithRecallGlobalScene 开启并恢复全局场景 LT
0x42 OnWithTimedOff 定时开启（超时后自动关闭） LT

Off —— 关闭（0x00）

将设备切换到关闭状态。执行成功后，OnOff 属性变为 false。 这是最基础的命令，不需要任何参数。

使用场景

用户点击 App 上的关灯按钮、自动化规则触发关灯、语音助手执行「关灯」指令时调用。

↑ 返回命令列表

On —— 开启（0x01）

将设备切换到开启状态。执行成功后，OnOff 属性变为 true。 同样不需要参数。

使用场景

用户点击开灯按钮、人体传感器检测到有人触发开灯时调用。

↑ 返回命令列表

Toggle —— 切换（0x02）

切换设备当前状态：如果当前是开，变为关；如果当前是关，变为开。 适合不关心当前状态、只想「翻转」的场景。不需要参数。

使用场景

物理墙壁开关的按下动作、遥控器的单一按键操作。相比单独发 On 或 Off，Toggle 不需要先读取当前状态。

↑ 返回命令列表

OffWithEffect —— 带效果关闭（0x40）

关闭设备的同时应用一个视觉过渡效果（如渐灭、延迟关闭等）。 关闭前会自动保存当前场景到全局场景（GlobalScene），以便后续通过 OnWithRecallGlobalScene 恢复。

参数类型说明
EffectIdentifier EffectIdentifierEnum 效果类型（见下方枚举）
EffectVariant enum8 效果变体（含义取决于 EffectIdentifier 的值）

EffectIdentifier 枚举值

0
DelayedAllOff 延迟全灭 —— 先淡出再关闭
1
DyingLight 残灯效果 —— 模拟灯泡熄灭时先变亮再暗灭

DelayedAllOff 的 EffectVariant

0
DelayedOffFastFade 快速淡出（默认）
1
NoFade 无淡出，直接关闭
2
DelayedOffSlowFade 慢速淡出

DyingLight 的 EffectVariant

0
DyingLightFadeOff 先增亮 20% 再缓慢熄灭（默认且唯一）
使用场景

智能灯「晚安」场景：用户点击后灯光慢慢熄灭（DelayedAllOff + SlowFade），而非突然黑灯。 设备会在关闭前保存当前亮度和颜色到 GlobalScene，下次调用 OnWithRecallGlobalScene 时可恢复。

↑ 返回命令列表

OnWithRecallGlobalScene —— 开启并恢复场景（0x41）

开启设备并恢复之前 OffWithEffect 保存的全局场景（GlobalScene）。 没有参数。执行后 GlobalSceneControl 重新变为 true。

使用场景

与 OffWithEffect 配对使用。例如：晚上用 OffWithEffect 关灯（保存了 70% 暖光的状态）， 早上调用 OnWithRecallGlobalScene，灯会直接恢复到 70% 暖光，而不是默认的 100% 白光。

↑ 返回命令列表

OnWithTimedOff —— 定时开启（0x42）

开启设备并设定一个自动关闭倒计时。如果设备已经开启，则刷新倒计时时间。 适合「只开一会儿」的临时需求。

参数类型说明
OnOffControl OnOffControlBitmap Bit 0: AcceptOnlyWhenOn —— 为 1 时，仅在设备已开启时才接受此命令
OnTime uint16 开启持续时间，单位 1/10 秒。例如 300 = 30 秒
OffWaitTime uint16 关闭后的等待时间（防抖），单位 1/10 秒
使用场景与参数

走廊灯、楼道灯：人体传感器触发时发送 OnWithTimedOff（OnTime=300，即 30 秒）， 如果在 30 秒内没有再次触发，灯自动关闭。 如果有新检测，重新发一次 OnWithTimedOff 即可刷新倒计时。

AcceptOnlyWhenOn 的用途：避免在用户手动关灯后，传感器又把灯打开。 设置 AcceptOnlyWhenOn = 1 后，只有灯已经亮着时才续时，不会重新打开已关闭的灯。

↑ 返回命令列表

属性详解

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

ID 名称 类型 分组 说明
0x0000 OnOff bool 开关状态 当前开关状态
0x4000 GlobalSceneControl bool 开关状态 全局场景是否有效
0x4001 OnTime uint16 定时参数 剩余开启时间（1/10 秒）
0x4002 OffWaitTime uint16 定时参数 关闭等待时间（1/10 秒）
0x4003 StartUpOnOff enum8 / null 上电行为 设备上电时的初始状态

开关状态（0x0000, 0x4000）

描述设备当前的开关状态和全局场景控制标记。

ID 名称 类型 说明
0x0000 OnOff（开关状态） bool 设备当前的开关状态。true = 开启，false = 关闭。这是 OnOff Cluster 唯一的必选属性
0x4000 GlobalSceneControl（全局场景控制） bool 标识全局场景是否有效。调用 OffWithEffect 后变为 false（场景已保存待恢复），调用 OnWithRecallGlobalScene 后恢复为 true。需要 LT 特性

↑ 返回属性列表

定时参数（0x4001, 0x4002）

用于 OnWithTimedOff 命令的倒计时控制。这两个属性由设备自动维护，通常不需要手动写入。

时间单位注意

OnTime 和 OffWaitTime 的单位是 1/10 秒（100 毫秒），不是秒也不是毫秒。 例如值为 300 表示 30 秒，值为 10 表示 1 秒。

ID 名称 类型 说明
0x4001 OnTime（开启倒计时） uint16 设备剩余的开启时间，单位 1/10 秒。由 OnWithTimedOff 命令设置，倒计时归零后设备自动关闭。值为 0 表示未启用定时。需要 LT 特性
0x4002 OffWaitTime（关闭等待时间） uint16 设备关闭后的等待期，单位 1/10 秒。在此期间如果收到 OnWithTimedOff 且 AcceptOnlyWhenOn = 1，命令会被忽略。用于防止传感器误触发重新开灯。需要 LT 特性

↑ 返回属性列表

上电行为（0x4003）

控制设备上电（或重启）后的初始开关状态。这个属性对用户体验影响很大 —— 断电恢复后灯是亮还是灭，取决于它。

ID 名称 类型 说明
0x4003 StartUpOnOff（上电行为） enum8 / null 设备上电后的开关状态（见下方枚举）。Nullable —— null 表示恢复断电前的状态。写入需要 manage 权限。需要 LT 特性

StartUpOnOff 枚举值

0
Off 上电后始终关闭
1
On 上电后始终开启
2
Toggle 上电后切换为断电前的相反状态
null
Previous 恢复断电前的状态（最常用）
null 与 0xFF

StartUpOnOff 是 Nullable 类型。在 Matter 协议的线上编码中，null 对应 0xFF。 所以如果你在底层协议数据中看到 0xFF，实际含义是「恢复断电前的状态」，不是一个有效的枚举值。

↑ 返回属性列表

Feature 位图

OnOff Cluster 通过 FeatureMap（0xFFFC）声明设备支持哪些高级能力：

Bit 0
LT（Lighting） 灯具特性 —— 启用场景保存/恢复、定时开关、渐变关闭、上电行为
Bit 1
DF（DeadFrontBehavior） 关闭时切断前端电源，设备处于「死前端」状态（不响应交互）
Bit 2
OO（OffOnly） 仅支持关闭操作（设备由外部机制开启，如物理按钮）

示例数据

一个启用了 Lighting 特性的智能灯在开启状态下的 OnOff Cluster 读取结果：

{
  // --- 开关状态 ---
  "0x0000": true,           // OnOff = true（当前为开启状态）
  "0x4000": true,           // GlobalSceneControl = true（全局场景有效）

  // --- 定时参数 ---
  "0x4001": 0,              // OnTime = 0（未启用定时开启）
  "0x4002": 0,              // OffWaitTime = 0（未启用关闭等待）

  // --- 上电行为 ---
  "0x4003": null             // StartUpOnOff = null（保持断电前的状态）
}
开发提示

对于最简单的设备（如普通开关面板、插座），可能只有 OnOff (0x0000) 一个属性。 只有支持 Lighting 特性的设备才会上报 0x4000 ~ 0x4003 这四个属性。 读取前可先检查 FeatureMap (0xFFFC) 判断设备支持哪些特性。

常见场景

场景 1：基础开关控制

  1. 发送 On (0x01) 或 Off (0x00) 命令控制设备
  2. 订阅 OnOff (0x0000) 属性变化，同步 App 界面状态
  3. 如果不关心当前状态，可以直接用 Toggle (0x02)

场景 2：走廊灯 / 感应灯自动关闭

  1. 传感器检测到有人，发送 OnWithTimedOff (0x42)，OnTime 设为 300（30 秒）
  2. 30 秒内无人，灯自动关闭
  3. 如果又检测到人，再次发送 OnWithTimedOff 刷新倒计时
  4. 设置 AcceptOnlyWhenOn = 1 可防止用户手动关灯后传感器又把灯打开

场景 3：设置上电恢复行为

  1. 读取 FeatureMap (0xFFFC)，确认设备支持 Lighting（LT）特性
  2. 写入 StartUpOnOff (0x4003) 的值：
    • 0（Off）—— 停电后恢复供电时灯保持关闭
    • 1（On）—— 恢复供电后灯自动亮起
    • null（Previous）—— 恢复到断电前的状态（推荐）
  3. 注意：写入 StartUpOnOff 需要 manage 级别的权限（Administrator 角色）

场景 4：渐灭 + 场景恢复（晚安 / 早安）

  1. 晚安时：发送 OffWithEffect (0x40)，设备保存当前亮度和颜色到全局场景，然后渐灭
  2. 早安时：发送 OnWithRecallGlobalScene (0x41)，设备恢复到晚安前的亮度和颜色
  3. 注意：直接调用 On (0x01) 不会恢复场景，灯会以默认亮度开启