Matter Cluster 101 — Groupcast Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 101 values in the device shadow use this format:

endpoint_id / 101 / attribute_id

Example:

{
  "0/101/1": 10
}

Cluster 101 Features

The FeatureMap attribute (0/101/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; 7 means every feature listed above is enabled.

Data Types

GroupcastTestResultEnum

GroupcastTestingEnum

See the GroupcastTesting command for a description of these operations.

MulticastAddrPolicyEnum

MembershipStruct (struct) — fabric-scoped

Cluster 101 Attributes

Cluster 101 defines 5 attributes 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 — Membership

Path example:

0/101/0

Indicates the list of groups memberships currently active on the node. Each entry specifies the group ID and the list of the endpoints that participate in that group, as well as policy for that group. For any single fabric, the server must limit the total number of GroupIDs used across all entries in the Membership attribute to no more than half (rounded down) of the MaxMembershipCount value. If processing a command would cause this per-fabric limit to be exceeded, then the resource exhaustion behavior of the associated command must apply.

Each entry is a MembershipStruct (see Data Types).

Example:

{
  "0/101/0": []
}

Attribute 1 / 0x0001 — MaxMembershipCount

Path example:

0/101/1

Indicates the maximum number of Groups which can be joined and appear in entries of the Membership attribute. This attribute does not specify the maximum number of list entries in the Membership attribute list, but rather the maximum number of different GroupID values which can appear across all entries of the list.

Example:

{
  "0/101/1": 10
}

Attribute 2 / 0x0002 — MaxMcastAddrCount

Path example:

0/101/2

Indicates the maximum number of unique multicast addresses the node can support. The value of this attribute is at least 1, to support the IANA Assigned IPv6 Multicast Address. When the PerGroup feature is supported, this attribute should be equal to MaxMembershipCount. However, the value may be less than MaxMembershipCount.

Example:

{
  "0/101/2": 1
}

Attribute 3 / 0x0003 — UsedMcastAddrCount

Path example:

0/101/3

Indicates the number of unique multicast addresses currently in use by the Groupcast cluster. This count includes the IANA Assigned IPv6 Multicast Address if at least one group is configured to use the IanaAddr policy. This count includes one unique multicast address for each group configured to use the PerGroup policy. The value of this attribute must NOT exceed MaxMcastAddrCount.

Example:

{
  "0/101/3": 1
}

Attribute 4 / 0x0004 — FabricUnderTest

Path example:

0/101/4

Indicates the FabricIndex of the fabric currently testing the Groupcast feature with the GroupcastTesting command. The last accessing fabric to have invoked a successful TestGroupcast command that caused testing mode to be engaged is the value indicated. Otherwise, if Groupcast testing is currently disabled, this attribute has a value of zero, which is the invalid FabricIndex value. This attribute is set to zero when the server initializes.

Example:

{
  "0/101/4": 1
}

Cluster 101 Commands

Cluster 101 has 5 client-to-server commands and 1 response.

AcceptedCommandList

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

endpoint_id / 101 / 65529

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

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 101,
    "command_name": "JoinGroup",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 101, always use "cluster_id": 101. 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: JoinGroup

Purpose

This command is used to instruct the server to join a multicast group. It provides a comprehensive way to add all information required to create a new group in one command. This command is used to create a new GroupID or to add specified endpoints to an existing GroupID. This command may also be used to change the OperationalGroupKey associated with an existing GroupID, but if this is the only operation desired, the UpdateGroupKey command should be used instead.

Command Identity

Payload Fields

McastAddrPolicy values (MulticastAddrPolicyEnum): 0 = IanaAddr, 1 = PerGroup

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 101,
    "command_name": "JoinGroup",
    "payload": {
      "groupID": 1,
      "endpoints": [],
      "keySetID": 1
    }
  }
}

Command: LeaveGroup

Purpose

This command must allow a maintainer to request that the server withdraws itself or specific endpoints from a specific group or from all groups of this client's fabric. This command has the following data fields subject to the listed conformance.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 101,
    "command_name": "LeaveGroup",
    "payload": {
      "groupID": 1
    }
  }
}

The device answers with LeaveGroupResponse (see below).

Command: LeaveGroupResponse

Purpose

This command must allow the server to inform the client about the result of the LeaveGroup command. This command has the following data fields subject to the listed conformance.

Command Identity

Response Fields

Command: UpdateGroupKey

Purpose

This command must allow a fabric administrator to update the OperationalGroupKey associated with the existing group identified by GroupID, which is already joined. This command is used following the rules defined in Groupcast Key Management section. This command has the following data fields subject to the listed conformance.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 101,
    "command_name": "UpdateGroupKey",
    "payload": {
      "groupID": 1,
      "keySetID": 1
    }
  }
}

Command: ConfigureAuxiliaryACL

Purpose

ConfigureAuxiliaryACL is a client-to-server command of the Groupcast cluster.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 101,
    "command_name": "ConfigureAuxiliaryACL",
    "payload": {
      "groupID": 1,
      "useAuxiliaryACL": true
    }
  }
}

Command: GroupcastTesting

Purpose

This command must allow an Administrator to configure test modes that allow validation of Groupcast communication. This command has the following data fields subject to the listed conformance. Note: The behavior of the command when the TestOperation is EnableSenderTesting is provisional.

Command Identity

Payload Fields

TestOperation values (GroupcastTestingEnum): 0 = DisableTesting, 1 = EnableListenerTesting, 2 = EnableSenderTesting

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 101,
    "command_name": "GroupcastTesting",
    "payload": {
      "testOperation": 0
    }
  }
}

Cluster 101 Events

Event 0 — GroupcastTesting

This event is generated during Groupcast testing processing after invocation of the GroupcastTesting command, under the conditions stated in that command's Effect on Receipt section. Some of the fields may be present or absent depending of the test mode involved. This event contains the following fields:

SmartphoneKey Notes

• Cluster 101 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/101/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.