Matter Cluster 4 — Groups Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 4 values in the device shadow use this format:

endpoint_id / 4 / attribute_id

Example:

{
  "1/4/0": 0
}

Cluster 4 Features

The FeatureMap attribute (1/4/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 1 means every feature listed above is enabled.

Data Types

NameSupportBitmap (bitmap)

Cluster 4 Attributes

Cluster 4 defines 1 attribute plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — NameSupport

Path example:

1/4/0

This attribute provides legacy, read-only access to whether the Group Names feature is supported. The most significant bit, bit 7 (GroupNames), is equal to bit 0 of the FeatureMap attribute (GN Feature). All other bits is 0.

Bits (NameSupportBitmap):

Example:

{
  "1/4/0": 0
}

Cluster 4 Commands

Cluster 4 has 6 client-to-server commands and 4 responses.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 4 / 65529

{
  "1/4/65529": [
    0,
    1,
    2,
    3,
    4,
    5
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "AddGroup",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 4, always use "cluster_id": 4. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: AddGroup

Purpose

The AddGroup command allows a client to add group membership in a particular group for the server endpoint.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "AddGroup",
    "payload": {
      "groupID": 1,
      "groupName": "example"
    }
  }
}

The device answers with AddGroupResponse (see below).

Command: AddGroupResponse

Purpose

The AddGroupResponse is sent by the Groups cluster server in response to an AddGroup command.

Command Identity

Response Fields

Command: ViewGroup

Purpose

The ViewGroup command allows a client to request that the server responds with a ViewGroupResponse command containing the name string for a particular group.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "ViewGroup",
    "payload": {
      "groupID": 1
    }
  }
}

The device answers with ViewGroupResponse (see below).

Command: ViewGroupResponse

Purpose

The ViewGroupResponse command is sent by the Groups cluster server in response to a ViewGroup command.

Command Identity

Response Fields

Command: GetGroupMembership

Purpose

The GetGroupMembership command allows a client to inquire about the group membership of the server endpoint, in a number of ways.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "GetGroupMembership",
    "payload": {
      "groupList": []
    }
  }
}

The device answers with GetGroupMembershipResponse (see below).

Command: GetGroupMembershipResponse

Purpose

The GetGroupMembershipResponse command is sent by the Groups cluster server in response to a GetGroupMembership command.

Command Identity

Response Fields

Command: RemoveGroup

Purpose

The RemoveGroup command allows a client to request that the server removes the membership for the server endpoint, if any, in a particular group.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "RemoveGroup",
    "payload": {
      "groupID": 1
    }
  }
}

The device answers with RemoveGroupResponse (see below).

Command: RemoveGroupResponse

Purpose

The RemoveGroupResponse command is generated by the server in response to the receipt of a RemoveGroup command.

Command Identity

Response Fields

Command: RemoveAllGroups

Purpose

The RemoveAllGroups command allows a client to direct the server to remove all group associations for the server endpoint.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "RemoveAllGroups",
    "payload": {}
  }
}

Command: AddGroupIfIdentifying

Purpose

The AddGroupIfIdentifying command allows a client to add group membership in a particular group for the server endpoint, on condition that the endpoint is identifying itself. Identifying functionality is controlled using the Identify cluster,. For correct operation of the AddGroupIfIdentifying command, any endpoint that supports the Groups server cluster must also support the Identify server cluster. This command might be used to assist configuring group membership in the absence of a commissioning tool.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 4,
    "command_name": "AddGroupIfIdentifying",
    "payload": {
      "groupID": 1,
      "groupName": "example"
    }
  }
}

Cluster 4 Events

Cluster 4 defines no events.

SmartphoneKey Notes

• Cluster 4 is present on SmartphoneKey devices or hubs today. See Matter Bridge Clusters — Detailed Reference and Matter Device Attributes & Commands for the values the bridge actually reports.
• Shadow paths follow endpoint/4/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.