Groups Cluster

Cluster ID: 0x0004  |  Endpoint: Typically on Endpoint 1 (application endpoint)

The Groups Cluster manages group membership for devices and is the foundation of Matter multicast messaging. By adding multiple devices to the same Group, commands sent to that Group ID are received by all member devices simultaneously -- for example, "turn off all living room lights at once" is a typical multicast scenario.

Commands

The Groups Cluster has 6 commands for managing device group membership. AddGroup, RemoveGroup, and RemoveAllGroups are write operations; ViewGroup and GetGroupMembership are query operations; AddGroupIfIdentifying is a conditional write command (the device must be in Identify mode for it to take effect). Click a command ID in the table below to jump to its detailed description.

AddGroup -- Add to Group (0x00)

Adds the current device (Endpoint) to a specified Group. If the device is already a member of that group, the command still succeeds (idempotent), but will update the group name (if the device supports the GN feature). Returns an AddGroupResponse containing the operation status and GroupID.

AddGroupResponse

Request example:

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x00"       // AddGroup
    },
    "commandFields": {
      "0": 1,                   // GroupID = 0x0001
      "1": "Living Room Lights" // GroupName
    }
  }]
}

Response example:

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

↑ Back to Commands

ViewGroup -- View Group (0x01)

Queries whether the device belongs to a specified Group, and if so, returns the group's name.

ViewGroupResponse

↑ Back to Commands

GetGroupMembership -- Query Group Membership (0x02)

Queries which groups a device belongs to in bulk. You can pass a list of GroupIDs for a filtered query, or pass an empty list to retrieve all groups the device belongs to. The response also includes a Capacity field that indicates how many more groups the device can join.

GetGroupMembershipResponse

Request example (query whether the device belongs to groups 1, 2, 3):

{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x02"       // GetGroupMembership
    },
    "commandFields": {
      "0": [1, 2, 3]            // GroupList -- query if device belongs to these three groups
    }
  }]
}

Response example (device belongs to groups 1 and 3, can join 5 more groups):

{
  "invokeResponseValue": {
    "commandPath": {
      "endpointId": 1,
      "clusterId": "0x0004",
      "commandId": "0x02"       // GetGroupMembershipResponse
    },
    "commandFields": {
      "0": 5,                   // Capacity = 5 (can join 5 more groups)
      "1": [1, 3]               // GroupList -- device belongs to groups 1 and 3
    }
  }
}

↑ Back to Commands

RemoveGroup -- Remove from Group (0x03)

Removes the device from a specified Group. If the device is not a member of that group, returns NOT_FOUND. After removing the group membership, the device will no longer respond to multicast commands for that group.

RemoveGroupResponse

↑ Back to Commands

RemoveAllGroups -- Remove from All Groups (0x04)

Removes the device from all joined groups, effectively clearing the group table. Takes no parameters and has no response. Also deletes all associated Scenes.

↑ Back to Commands

AddGroupIfIdentifying -- Add to Group If Identifying (0x05)

Functions the same as AddGroup, but with an added precondition: the device must currently be in Identify mode (i.e., the Identify Cluster's IdentifyTime > 0) for the command to execute. If the device is not in Identify mode, the command is silently ignored. There is no response.

↑ Back to Commands

Attributes

The Groups Cluster has only one application attribute. Click the attribute ID to jump to its detailed description.

NameSupport (Name Support)

An 8-bit bitmap indicating whether the device supports storing group names. Currently only Bit 7 (the most significant bit) is used.

NameSupport Bitmap

↑ Back to Attributes

Feature Bitmap

The Groups Cluster declares optional capabilities supported by the device through FeatureMap (0xFFFC):

Example Data

Reading the Groups Cluster attributes of a device that supports the GN feature:

{
  // --- Attributes ---
  "0x0000": 128          // NameSupport -- Bit 7 = 1, supports group names
}

Common Scenarios