通用配网 Cluster（GeneralCommissioning）

Cluster ID: 0x0030  |  所在 Endpoint: 固定在 Endpoint 0（Root Endpoint）

GeneralCommissioning 是 Matter 配网（Commissioning）流程的总控 Cluster —— 负责管理整个配网过程的生命周期。 它不处理具体的网络凭据（那是 NetworkCommissioning 的事）， 而是控制配网流程的「开始」「推进」和「结束」，并通过 Fail-Safe 机制保证配网失败时设备能安全回滚。

命令（Commands）

GeneralCommissioning Cluster 共有 3 个请求命令，每个都有对应的响应命令。 这三个命令构成了配网流程的骨架：先启动安全计时器，再设置法规配置，最后提交完成。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

Client → Server（请求命令）

Server → Client（响应命令）

ArmFailSafe —— 启动 Fail-Safe（0x00）

启动或续期 Fail-Safe 计时器。这是配网流程的第一步 —— 在做任何配网操作之前，必须先调用它开启安全保护。 Fail-Safe 计时器一旦启动，设备会进入「可配网」状态；如果计时器超时而配网未完成（未收到 CommissioningComplete）， 设备会自动回滚所有已执行的配网变更，恢复到配网前的状态。

ArmFailSafeResponse 响应字段

↑ 返回命令列表

SetRegulatoryConfig —— 设置法规配置（0x02）

设置设备的法规区域（室内/室外）和国家代码。不同国家和地区对无线电设备有不同的法规要求（如发射功率、可用频段）， 设备需要根据法规配置来调整自己的无线参数。

SetRegulatoryConfigResponse 响应字段

↑ 返回命令列表

CommissioningComplete —— 完成配网（0x04）

配网流程的最后一步。调用成功后，设备会：

1. 停止 Fail-Safe 计时器
2. 永久保存所有配网期间的变更（网络凭据、NOC 证书、ACL 权限等）
3. 将 Breadcrumb 重置为 0

此命令没有参数。只有当前持有 Fail-Safe 的 Commissioner 才能调用它。

CommissioningCompleteResponse 响应字段

↑ 返回命令列表

属性详解

GeneralCommissioning Cluster 共有 5 个属性。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

配网追踪（0x0000）

用于 Commissioner 追踪配网流程的推进状态。

↑ 返回属性列表

基础配网信息（0x0001）

描述设备的 Fail-Safe 时间限制，Commissioner 据此设置合理的超时参数。

BasicCommissioningInfo 结构体

↑ 返回属性列表

法规配置（0x0002, 0x0003）

描述设备的法规区域配置及其能力限制。

↑ 返回属性列表

连接能力（0x0004）

描述设备在配网期间的网络连接能力。

↑ 返回属性列表

枚举定义

CommissioningErrorEnum

所有 GeneralCommissioning 命令的响应都包含此错误码，用于表示操作结果。

RegulatoryLocationTypeEnum

标识设备的法规使用场景。用于 RegulatoryConfig、LocationCapability 属性和 SetRegulatoryConfig 命令。

示例数据

属性数据示例

以下是一个正在配网中的设备的 GeneralCommissioning Cluster 典型属性数据：

{
  // --- 配网追踪 ---
  "0x0000": 3,                // Breadcrumb = 3（Commissioner 设置的进度标记）

  // --- 基础配网信息 ---
  "0x0001": {                 // BasicCommissioningInfo
    "failSafeExpiryLengthSeconds": 60,    // Fail-Safe 默认 60 秒
    "maxCumulativeFailsafeSeconds": 900   // 最长累计 900 秒（15 分钟）
  },

  // --- 法规配置 ---
  "0x0002": 2,                // RegulatoryConfig = IndoorOutdoor（当前配置）
  "0x0003": 2,                // LocationCapability = IndoorOutdoor（设备能力）

  // --- 并发连接 ---
  "0x0004": true              // SupportsConcurrentConnection = true（支持并发连接）
}

ArmFailSafe 交互示例

Commissioner 启动 Fail-Safe 计时器的请求与响应：

// Commissioner → Device：启动 Fail-Safe 计时器
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0030",
      "commandId": "0x00"        // ArmFailSafe
    },
    "commandFields": {
      "expiryLengthSeconds": 60, // 60 秒超时
      "breadcrumb": 1            // 配网进度标记
    }
  }]
}

// Device → Commissioner：确认 Fail-Safe 已启动
{
  "errorCode": 0,               // OK
  "debugText": ""
}

CommissioningComplete 交互示例

配网完成时的最终确认：

// Commissioner → Device：完成配网
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0030",
      "commandId": "0x04"        // CommissioningComplete
    },
    "commandFields": {}          // 无参数
  }]
}

// Device → Commissioner：确认配网完成
{
  "errorCode": 0,               // OK
  "debugText": ""
}

常见场景