Matter Cluster 1873 — Commissioner Control Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 1873 values in the device shadow use this format:

endpoint_id / 1873 / attribute_id

Example:

{
  "0/1873/0": 0
}

Data Types

SupportedDeviceCategoryBitmap (bitmap)

Cluster 1873 Attributes

Cluster 1873 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 — SupportedDeviceCategories

Path example:

0/1873/0

Indicates the device categories specified in SupportedDeviceCategoryBitmap that are supported by this Commissioner Control Cluster server. A client must NOT send the RequestCommissioningApproval command if the intended node to be commissioned does not conform to any of the values specified in SupportedDeviceCategories.

Bits (SupportedDeviceCategoryBitmap):

Example:

{
  "0/1873/0": 0
}

Cluster 1873 Commands

Cluster 1873 has 2 client-to-server commands and 1 response.

AcceptedCommandList

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

endpoint_id / 1873 / 65529

{
  "0/1873/65529": [
    0,
    1
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

This command is sent by a client to request approval for a future CommissionNode call. This is required to be a separate step in order to provide the server time for interacting with a user before informing the client that the CommissionNode operation may be successful. If the command is not executed via a CASE session, the command must fail with a status code of UNSUPPORTED_ACCESS. The server may request approval from the user, but it is not required.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 1873,
    "command_name": "RequestCommissioningApproval",
    "payload": {
      "requestID": 1,
      "vendorID": 1,
      "productID": 1
    }
  }
}

Command: CommissionNode

Purpose

This command is sent by a client to request that the server begins commissioning a previously approved request. The server returns FAILURE if the CommissionNode command is not sent from the same NodeID and on the same fabric as the RequestCommissioningApproval or if the provided RequestID to CommissionNode does not match the value provided to RequestCommissioningApproval. If the command is not executed via a CASE session, the command must fail with a status code of UNSUPPORTED_ACCESS. Upon receipt, the server must respond with ReverseOpenCommissioningWindow if CommissioningRequestResult was generated with StatusCode of SUCCESS for the matching RequestID field and NodeID of the client.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 1873,
    "command_name": "CommissionNode",
    "payload": {
      "requestID": 1,
      "responseTimeoutSeconds": 30
    }
  }
}

The device answers with ReverseOpenCommissioningWindow (see below).

Command: ReverseOpenCommissioningWindow

Purpose

When received within the timeout specified by ResponseTimeoutSeconds in the CommissionNode command, the client must open a commissioning window on a node which matches the VendorID and ProductID provided in the associated RequestCommissioningApproval command. When commissioning this node, the server must check that the VendorID and ProductID fields provided in the RequestCommissioningApproval command match the VendorID and ProductID attributes of the Basic Information Cluster which have already been verified during the Device Attestation Procedure. If they do not match, the server must NOT complete commissioning and should indicate an error to the user.

Command Identity

Response Fields

Cluster 1873 Events

Event 0 — CommissioningRequestResult

This event is generated by the server following a RequestCommissioningApproval command which the server responded to with SUCCESS. The approval is valid for a period determined by the manufacturer and characteristics of the node presenting the Commissioner Control Cluster. Clients should send the CommissionNode command immediately upon receiving a CommissioningRequestResult event.

SmartphoneKey Notes

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