Matter Cluster 48 — General Commissioning Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 48 values in the device shadow use this format:

endpoint_id / 48 / attribute_id

Example:

{
  "0/48/0": 1
}

Cluster 48 Features

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

Data Types

CommissioningErrorEnum

This enumeration is used by several response commands in this cluster to indicate particular errors.

NetworkRecoveryReasonEnum

This data type is derived from enum8, however, the maximum value of the enumeration is less than 15. This enumeration is used by the NetworkRecoveryReason attribute and may be embedded in the beacons advertising the need for Network Recovery.

RegulatoryLocationTypeEnum

This enumeration is used by the RegulatoryConfig and LocationCapability attributes to indicate possible radio usage.

BasicCommissioningInfo (struct)

This structure provides some constant values that may be of use to all commissioners.

Cluster 48 Attributes

Cluster 48 defines 13 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 — Breadcrumb

Path example:

0/48/0

This attribute allows for the storage of a client-provided small payload which Administrators and Commissioners may write and then subsequently read, to keep track of their own progress. This may be used by the Commissioner to avoid repeating already-executed actions upon re-establishing a commissioning link after an error. On start/restart of the server, such as when a device is power-cycled, this attribute is reset to zero. Some commands related to commissioning also have a side-effect of updating or resetting this attribute and this is specified in their respective functional descriptions.

Example:

{
  "0/48/0": 1
}

Attribute 1 / 0x0001 — BasicCommissioningInfo

Path example:

0/48/1

No condensed specification text is available for BasicCommissioningInfo; use the type, conformance and constraint below together with the cluster description above.

Value is a BasicCommissioningInfo struct (see Data Types).

Example:

{
  "0/48/1": {
    "failSafeExpiryLengthSeconds": 1,
    "maxCumulativeFailsafeSeconds": 1
  }
}

Attribute 2 / 0x0002 — RegulatoryConfig

Path example:

0/48/2

Indicates the regulatory configuration for the product.

Values (RegulatoryLocationTypeEnum):

Example:

{
  "0/48/2": 0
}

Attribute 3 / 0x0003 — LocationCapability

Path example:

0/48/3

LocationCapability is statically set by the manufacturer and indicates if this Node needs to be told an exact RegulatoryLocation. For example a Node which is "Indoor Only" would not be certified for outdoor use at all, and thus there is no need for a commissioner to set or ask the user about whether the device will be used inside or outside. However a device which states its capability is "Indoor/Outdoor" means it would like clarification if possible. For Nodes without radio network interfaces (e.g.

Values (RegulatoryLocationTypeEnum):

Example:

{
  "0/48/3": 0
}

Attribute 4 / 0x0004 — SupportsConcurrentConnection

Path example:

0/48/4

Indicates whether this device supports "concurrent connection flow" commissioning mode. If false, the device only supports "non-concurrent connection flow" mode.

Example:

{
  "0/48/4": true
}

Attribute 5 / 0x0005 — TCAcceptedVersion

Path example:

0/48/5

No condensed specification text is available for TCAcceptedVersion; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/48/5": 1
}

Attribute 6 / 0x0006 — TCMinRequiredVersion

Path example:

0/48/6

No condensed specification text is available for TCMinRequiredVersion; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/48/6": 1
}

Attribute 7 / 0x0007 — TCAcknowledgements

Path example:

0/48/7

No condensed specification text is available for TCAcknowledgements; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/48/7": 0
}

Attribute 8 / 0x0008 — TCAcknowledgementsRequired

Path example:

0/48/8

No condensed specification text is available for TCAcknowledgementsRequired; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/48/8": true
}

Attribute 9 / 0x0009 — TCUpdateDeadline

Path example:

0/48/9

No condensed specification text is available for TCUpdateDeadline; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/48/9": 1
}

Attribute 10 / 0x000A — RecoveryIdentifier

Path example:

0/48/10

This attribute contains the identifier to be included in the advertisements used during the Network Recovery Flow. This identifier is intended to be advertised over the air and used by an Administrator to establish a Node's identity without revealing its Node ID. The attribute contains a random 64-bit value, that value is reset on factory reset and must remain unchanged until a next factory reset. It is important that this value be selected at random from a 64-bit number space to ensure a high likelihood of uniqueness from values selected by other Nodes.

Example:

{
  "0/48/10": "AQID"
}

Attribute 11 / 0x000B — NetworkRecoveryReason

Path example:

0/48/11

This attribute contains the primary reason that triggered the Network Recovery flow and its associated advertisements. Null when the Node is not undergoing a Network Recovery flow.

Values (NetworkRecoveryReasonEnum):

Example:

{
  "0/48/11": 1
}

Attribute 12 / 0x000C — IsCommissioningWithoutPower

Path example:

0/48/12

The server must set this attribute to true if and only if is currently operating on the commissioning channel but cannot operate on the operational channel because it is not powered. This may happen during NFC-based commissioning, when the commissioning channel is NFC Transport Layer (NTL), because it can harvest energy from NFC to operate. However, such a Commissionee must be powered on to switch to the operational channel. This attribute is linked to the Commissionee behavior after reception of the ConnectNetwork Command.

Example:

{
  "0/48/12": true
}

Cluster 48 Commands

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

AcceptedCommandList

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

endpoint_id / 48 / 65529

{
  "0/48/65529": [
    0,
    2,
    4,
    6
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

This command is used to arm or disarm the fail-safe timer. Success or failure of this command is communicated by the ArmFailSafeResponse command, unless some data model validations caused a failure status code to be issued during the processing of the command. If the fail-safe timer is not currently armed, the commissioning window is open, and the command was received over a CASE session, the command must leave the current fail-safe state unchanged and immediately respond with an ArmFailSafeResponse containing an ErrorCode value of BusyWithOtherAdmin.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 48,
    "command_name": "ArmFailSafe",
    "payload": {
      "expiryLengthSeconds": 1,
      "breadcrumb": 1
    }
  }
}

The device answers with ArmFailSafeResponse (see below).

Command: ArmFailSafeResponse

Purpose

This command is used to report the result of the ArmFailSafe command.

Command Identity

Response Fields

ErrorCode values (CommissioningErrorEnum): 0 = OK, 1 = ValueOutsideRange, 2 = InvalidAuthentication, 3 = NoFailSafe, 4 = BusyWithOtherAdmin, 5 = RequiredTCNotAccepted, 6 = TCAcknowledgementsNotReceived, 7 = TCMinVersionNotMet

Command: SetRegulatoryConfig

Purpose

This command is used to set the regulatory configuration for the device. This must add or update the regulatory configuration in the RegulatoryConfig Attribute to the value provided in the NewRegulatoryConfig field. Success or failure of this command is communicated by the SetRegulatoryConfigResponse command, unless some data model validations caused a failure status code to be issued during the processing of the command. The CountryCode field must conforms to ISO 3166-1 alpha-2 and is used to set the Location attribute reflected by the Basic Information Cluster.

Command Identity

Payload Fields

NewRegulatoryConfig values (RegulatoryLocationTypeEnum): 0 = Indoor, 1 = Outdoor, 2 = IndoorOutdoor

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 48,
    "command_name": "SetRegulatoryConfig",
    "payload": {
      "newRegulatoryConfig": 0,
      "countryCode": "example",
      "breadcrumb": 1
    }
  }
}

The device answers with SetRegulatoryConfigResponse (see below).

Command: SetRegulatoryConfigResponse

Purpose

This command is used to report the result of the SetRegulatoryConfig command.

Command Identity

Response Fields

ErrorCode values (CommissioningErrorEnum): 0 = OK, 1 = ValueOutsideRange, 2 = InvalidAuthentication, 3 = NoFailSafe, 4 = BusyWithOtherAdmin, 5 = RequiredTCNotAccepted, 6 = TCAcknowledgementsNotReceived, 7 = TCMinVersionNotMet

Command: CommissioningComplete

Purpose

This command is used to indicate that the commissioning process is complete. Success or failure of this command is communicated by the CommissioningCompleteResponse command, unless some data model validations caused a failure status code to be issued during the processing of the command. This command signals the Server that the Commissioner or Administrator has successfully completed all steps needed during the Fail-Safe period, such as commissioning or other Administrator operations requiring usage of the Fail Safe timer.

Command Identity

Payload Fields

This command has no payload fields.

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 48,
    "command_name": "CommissioningComplete",
    "payload": {}
  }
}

The device answers with CommissioningCompleteResponse (see below).

Command: CommissioningCompleteResponse

Purpose

This command is used to report the result of the CommissioningComplete command.

Command Identity

Response Fields

ErrorCode values (CommissioningErrorEnum): 0 = OK, 1 = ValueOutsideRange, 2 = InvalidAuthentication, 3 = NoFailSafe, 4 = BusyWithOtherAdmin, 5 = RequiredTCNotAccepted, 6 = TCAcknowledgementsNotReceived, 7 = TCMinVersionNotMet

Command: SetTCAcknowledgements

Purpose

SetTCAcknowledgements is a client-to-server command of the General Commissioning cluster.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 48,
    "command_name": "SetTCAcknowledgements",
    "payload": {
      "tcVersion": 1,
      "tcUserResponse": 0
    }
  }
}

The device answers with SetTCAcknowledgementsResponse (see below).

Command: SetTCAcknowledgementsResponse

Purpose

SetTCAcknowledgementsResponse is a server response of the General Commissioning cluster.

Command Identity

Response Fields

ErrorCode values (CommissioningErrorEnum): 0 = OK, 1 = ValueOutsideRange, 2 = InvalidAuthentication, 3 = NoFailSafe, 4 = BusyWithOtherAdmin, 5 = RequiredTCNotAccepted, 6 = TCAcknowledgementsNotReceived, 7 = TCMinVersionNotMet

Cluster 48 Events

Cluster 48 defines no events.

SmartphoneKey Notes

• Cluster 48 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/48/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.