场景管理 Cluster（SceneManagement）

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

SceneManagement 是 Matter 中的场景管理 Cluster —— 负责将多个 Cluster 的属性值打包成一个「快照」， 然后通过一条命令一键恢复到这组状态。 比如「观影模式」可以同时把灯调暗、色温调暖、窗帘关上，这些动作就是一个场景。

每个场景由 GroupID + SceneID 唯一标识，属于某个组（Group）， 组内可以包含多个场景。场景的核心数据结构是 ExtensionFieldSets —— 一组「Cluster ID + 属性值列表」的快照，定义了这个场景要把哪些 Cluster 的哪些属性设成什么值。

命令（Commands）

SceneManagement Cluster 共有 8 个命令，覆盖场景的增删改查、一键召回和跨组复制。 其中 AddScene 和 RecallScene 是日常开发最常用的两个。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

AddScene —— 添加场景（0x00）

向设备的场景表中添加一个新场景，或更新已有场景。 场景的核心数据通过 ExtensionFieldSets 传入 —— 它定义了这个场景要控制哪些 Cluster 的哪些属性值。 如果指定的 GroupID + SceneID 已存在，会覆盖更新。

AddSceneResponse 返回字段

↑ 返回命令列表

ViewScene —— 查看场景（0x01）

读取指定场景的完整数据，包括过渡时间、场景名称和 ExtensionFieldSets。 用于在 App 界面上展示场景详情或编辑前获取当前配置。

ViewSceneResponse 返回字段

↑ 返回命令列表

RemoveScene —— 删除场景（0x02）

从设备的场景表中删除指定的一个场景。删除后该 SceneID 可以被重新使用。

RemoveSceneResponse 返回字段

↑ 返回命令列表

RemoveAllScenes —— 删除组内所有场景（0x03）

一次性删除指定组内的全部场景。适合重置或清空某个区域的场景配置。

RemoveAllScenesResponse 返回字段

↑ 返回命令列表

StoreScene —— 捕获当前状态（0x04）

将设备当前的实际状态「拍快照」保存为一个场景。设备会自动读取自身各 Cluster 的当前属性值， 打包成 ExtensionFieldSets 存入场景表。相比 AddScene 需要手动指定每个属性值， StoreScene 更像一个「保存当前状态」的快捷操作。

StoreSceneResponse 返回字段

↑ 返回命令列表

RecallScene —— 恢复场景（0x05）

一键恢复指定场景。设备会读取场景中保存的 ExtensionFieldSets， 将各 Cluster 的属性值设置到场景记录的目标值。 如果指定了 TransitionTime，设备会在过渡时间内平滑切换（如灯光渐变）。

↑ 返回命令列表

GetSceneMembership —— 查询场景列表（0x06）

查询指定组内有哪些场景。返回该组下所有已存储的 SceneID 列表和剩余容量。 用于在 App 界面展示场景列表或判断还能创建多少个场景。

GetSceneMembershipResponse 返回字段

↑ 返回命令列表

CopyScene —— 复制场景（0x40）

在组之间复制场景。可以复制单个场景，也可以一次性复制源组的全部场景到目标组。 适合在不同房间之间共享相同的场景配置。

CopySceneResponse 返回字段

↑ 返回命令列表

属性详解

SceneManagement Cluster 有 3 个属性。场景数据本身不通过属性暴露， 而是通过 ViewScene / GetSceneMembership 命令读取。 属性提供的是场景表的容量、当前状态等元信息。

LastConfiguredBy（0x0000） 新版已移除

记录最后一次修改场景表的节点 ID（Node ID）。 可以用来排查「是谁改了场景配置」的问题。 值为 null 表示场景表从未被修改，或设备不支持追踪此信息。

↑ 返回属性列表

SceneTableSize（0x0001）

设备场景表的最大容量，即最多能存储多少个场景。 这是所有 Fabric 共享的总容量。典型设备值在 8~16 之间。

↑ 返回属性列表

FabricSceneInfo（0x0002）

每个 Fabric 独立维护的场景状态信息。这是一个列表，每个元素对应一个 Fabric。 通过它可以知道当前 Fabric 有多少个场景、当前激活的是哪个场景、还能再存多少个。

↑ 返回属性列表

核心数据结构

ExtensionFieldSets（扩展字段集）

ExtensionFieldSets 是场景的核心数据 —— 它记录了「这个场景要把哪些 Cluster 的哪些属性设成什么值」。 结构是一个列表，每个元素包含一个 Cluster ID 和该 Cluster 下要设置的属性值列表。

举个例子，一个「观影模式」场景的 ExtensionFieldSets 可能包含：

• OnOff（0x0006）：开关 = 开启
• LevelControl（0x0008）：亮度 = 25（约 10%）
• ColorControl（0x0300）：色温 X = 370，色温 Y = 300（暖白光）

设备执行 RecallScene 时，会逐个读取这些属性对，调用对应 Cluster 的逻辑设置属性值。 每个 Cluster 需要实现 ScenesManagement 的回调接口来支持场景存取。

Feature 位图

SceneManagement Cluster 通过 FeatureMap（0xFFFC）声明设备支持的高级能力：

示例数据

属性读取示例

读取 SceneManagement Cluster 属性时的返回数据：

{
  // --- 场景表信息 ---
  "0x0001": 16,            // SceneTableSize = 16（最多存储 16 个场景）

  // --- Fabric 场景信息 ---
  "0x0002": [              // FabricSceneInfo（当前 Fabric 的场景概况）
    {
      "SceneCount": 3,           // 当前 Fabric 已存储 3 个场景
      "CurrentScene": 1,         // 当前激活的场景 ID
      "CurrentGroup": 0,         // 当前激活场景所属的组 ID
      "SceneValid": true,        // 当前场景状态有效
      "RemainingCapacity": 13,   // 还能再存 13 个场景
      "FabricIndex": 1           // 所属 Fabric 索引
    }
  ]
}

AddScene 命令示例

创建一个「观影模式」场景，包含 OnOff、LevelControl、ColorControl 三个 Cluster 的属性快照：

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0062",
      "commandId": "0x00"       // AddScene
    },
    "commandFields": {
      "GroupID": 0,              // 组 ID（0 = 不属于任何组）
      "SceneID": 1,              // 场景 ID
      "TransitionTime": 10,      // 过渡时间 = 1.0 秒（单位 0.1 秒）
      "SceneName": "Movie",      // 场景名称（需 SN 特性）
      "ExtensionFieldSets": [    // 各 Cluster 的属性快照
        {
          "ClusterID": "0x0006", // OnOff Cluster
          "AttributeValueList": [
            { "AttributeID": "0x0000", "ValueUnsigned8": 1 }
          ]
        },
        {
          "ClusterID": "0x0008", // LevelControl Cluster
          "AttributeValueList": [
            { "AttributeID": "0x0000", "ValueUnsigned8": 25 }
          ]
        },
        {
          "ClusterID": "0x0300", // ColorControl Cluster
          "AttributeValueList": [
            { "AttributeID": "0x0003", "ValueUnsigned16": 370 },
            { "AttributeID": "0x0004", "ValueUnsigned16": 300 }
          ]
        }
      ]
    }
  }]
}

常见场景