组管理 Cluster（Groups）

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

Groups Cluster 管理设备的组成员关系，是 Matter 组播（Multicast）消息的基础。 将多个设备加入同一个 Group，之后向该 Group ID 发送命令，所有成员设备都会同时响应 —— 比如「一键关闭客厅所有灯」就是典型的组播场景。

命令（Commands）

Groups Cluster 共有 6 个命令，用于管理设备的组成员关系。 其中 AddGroup、RemoveGroup、RemoveAllGroups 是写操作，ViewGroup 和 GetGroupMembership 是查询操作， AddGroupIfIdentifying 是一个条件写入命令（设备必须处于 Identify 模式才生效）。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

AddGroup —— 加入组（0x00）

将当前设备（Endpoint）加入指定的 Group。如果设备已经是该组的成员，命令仍然成功（幂等）， 但会更新组名称（如果设备支持 GN 特性）。 执行后返回 AddGroupResponse，包含操作状态和 GroupID。

AddGroupResponse

请求示例：

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x00"       // AddGroup
    },
    "commandFields": {
      "0": 1,                   // GroupID = 0x0001
      "1": "客厅灯组"            // GroupName
    }
  }]
}

响应示例：

{
  "invokeResponseValue": {
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x00"       // AddGroupResponse
    },
    "commandFields": {
      "0": 0,                   // Status = SUCCESS
      "1": 1                    // GroupID = 0x0001
    }
  }
}

↑ 返回命令列表

ViewGroup —— 查询组（0x01）

查询设备是否属于指定的 Group，如果属于则返回该组的名称。

ViewGroupResponse

↑ 返回命令列表

GetGroupMembership —— 查询组成员关系（0x02）

批量查询设备属于哪些组。可以传入一组 GroupID 做筛选查询，也可以传空列表获取设备所属的全部组。 响应中还包含 Capacity 字段，告诉你设备还能加入多少个组。

GetGroupMembershipResponse

请求示例（查询设备是否属于组 1、2、3）：

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x02"       // GetGroupMembership
    },
    "commandFields": {
      "0": [1, 2, 3]            // GroupList — 查询设备是否属于这三个组
    }
  }]
}

响应示例（设备属于组 1 和组 3，还可再加入 5 个组）：

{
  "invokeResponseValue": {
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x02"       // GetGroupMembershipResponse
    },
    "commandFields": {
      "0": 5,                   // Capacity = 5（还能再加入 5 个组）
      "1": [1, 3]               // GroupList — 设备属于组 1 和组 3
    }
  }
}

↑ 返回命令列表

RemoveGroup —— 移出组（0x03）

将设备从指定的 Group 中移除。如果设备不属于该组，返回 NOT_FOUND。 移除组成员关系后，设备将不再响应该组的组播命令。

RemoveGroupResponse

↑ 返回命令列表

RemoveAllGroups —— 移出所有组（0x04）

将设备从所有已加入的组中移除，相当于清空组表。没有参数，也没有响应。 同时会清除所有关联的 Scene。

↑ 返回命令列表

AddGroupIfIdentifying —— 在标识模式下加入组（0x05）

功能与 AddGroup 相同，但增加了一个前置条件：设备必须正处于 Identify 模式 （即 Identify Cluster 的 IdentifyTime > 0）才会执行。 如果设备不在 Identify 模式，命令会被静默忽略。没有响应。

↑ 返回命令列表

属性详解

Groups Cluster 只有一个应用属性。点击属性 ID 可跳转到详细说明。

NameSupport（名称支持）

一个 8 位的位图，描述设备是否支持存储组名称。目前只使用了 Bit 7（最高位）。

NameSupport 位图

↑ 返回属性列表

Feature 位图

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

示例数据

读取一个支持 GN 特性的设备的 Groups Cluster 属性：

{
  // --- 属性 ---
  "0x0000": 128          // NameSupport — Bit 7 = 1，支持组名称
}

常见场景