GeneralCommissioning Cluster

Cluster ID: 0x0030  |  Endpoint: Fixed on Endpoint 0 (Root Endpoint)

GeneralCommissioning is the master control Cluster for the Matter commissioning flow — responsible for managing the entire commissioning lifecycle. It does not handle specific network credentials (that is NetworkCommissioning's job), but rather controls the "start," "progress," and "end" of the commissioning flow, and ensures the device can safely roll back on failure through the Fail-Safe mechanism.

Commands

The GeneralCommissioning Cluster has 3 request commands, each with a corresponding response command. These three commands form the backbone of the commissioning flow: first start the safety timer, then set regulatory configuration, and finally submit completion. Click a command ID in the table below to jump to its detailed description.

Client → Server (Request Commands)

Server → Client (Response Commands)

ArmFailSafe — Start Fail-Safe (0x00)

Starts or renews the Fail-Safe timer. This is the first step in the commissioning flow — before any commissioning operation, this must be called to enable safety protection. Once the Fail-Safe timer starts, the device enters a "commissionable" state; if the timer expires before commissioning completes (CommissioningComplete not received), the device will automatically roll back all commissioning changes and restore to its pre-commissioning state.

ArmFailSafeResponse Response Fields

↑ Back to Commands

SetRegulatoryConfig — Set Regulatory Configuration (0x02)

Set the device's regulatory area (indoor/outdoor) and country code. Different countries and regions have different regulatory requirements for wireless devices (e.g., transmission power, available bands), and the device needs to adjust its wireless parameters based on the regulatory configuration.

SetRegulatoryConfigResponse Response Fields

↑ Back to Commands

CommissioningComplete — Complete Commissioning (0x04)

The final step of the commissioning flow. After a successful call, the device will:

1. Stop the Fail-Safe timer
2. Permanently save all changes made during commissioning (network credentials, NOC certificates, ACL permissions, etc.)
3. Reset Breadcrumb to 0

This command has no parameters. Only the Commissioner currently holding the Fail-Safe can call it.

CommissioningCompleteResponse Response Fields

↑ Back to Commands

Attributes

The GeneralCommissioning Cluster has 5 attributes. Click an attribute ID in the summary table below to jump to its detailed description.

Commissioning Tracking (0x0000)

Used by the Commissioner to track the progress of the commissioning flow.

↑ Back to Attributes

Basic Commissioning Info (0x0001)

Describes the device's Fail-Safe time limits, which the Commissioner uses to set reasonable timeout parameters.

BasicCommissioningInfo Structure

↑ Back to Attributes

Regulatory Config (0x0002, 0x0003)

Describes the device's regulatory area configuration and its capability constraints.

↑ Back to Attributes

Connection Capability (0x0004)

Describes the device's network connection capability during commissioning.

↑ Back to Attributes

Enum Definitions

CommissioningErrorEnum

All GeneralCommissioning command responses include this error code to indicate the operation result.

RegulatoryLocationTypeEnum

Identifies the device's regulatory use scenario. Used for the RegulatoryConfig and LocationCapability attributes and the SetRegulatoryConfig command.

Example Data

Attribute Data Example

The following is typical attribute data for a GeneralCommissioning Cluster of a device currently being commissioned:

{
  // --- Commissioning Tracking ---
  "0x0000": 3,                // Breadcrumb = 3（Progress marker set by the Commissioner）

  // --- Basic Commissioning Info ---
  "0x0001": {                 // BasicCommissioningInfo
    "failSafeExpiryLengthSeconds": 60,    // Fail-Safe default 60 seconds
    "maxCumulativeFailsafeSeconds": 900   // Maximum cumulative 900 seconds (15 minutes)
  },

  // --- Regulatory Config ---
  "0x0002": 2,                // RegulatoryConfig = IndoorOutdoor (current config)
  "0x0003": 2,                // LocationCapability = IndoorOutdoor (device capability)

  // --- Concurrent Connection ---
  "0x0004": true              // SupportsConcurrentConnection = true (supports concurrent connection)
}

ArmFailSafe Interaction Example

Commissioner request and response for starting the Fail-Safe timer:

// Commissioner → Device: Start Fail-Safe timer
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0030",
      "commandId": "0x00"        // ArmFailSafe
    },
    "commandFields": {
      "expiryLengthSeconds": 60, // 60 second timeout
      "breadcrumb": 1            // Commissioning progress marker
    }
  }]
}

// Device → Commissioner: Confirm Fail-Safe started
{
  "errorCode": 0,               // OK
  "debugText": ""
}

CommissioningComplete Interaction Example

Final confirmation when commissioning completes:

// Commissioner → Device: Complete commissioning
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0030",
      "commandId": "0x04"        // CommissioningComplete
    },
    "commandFields": {}          // No parameters
  }]
}

// Device → Commissioner: Confirm commissioning complete
{
  "errorCode": 0,               // OK
  "debugText": ""
}

Common Scenarios