网络配置 Cluster（NetworkCommissioning）

Cluster ID: 0x0031  |  所在 Endpoint: 通常在 Endpoint 0（Root Endpoint）

NetworkCommissioning 是 Matter 设备配网过程中最关键的 Cluster，负责管理设备的网络凭据 —— 包括 Wi-Fi 密码、Thread 网络参数或以太网配置。 Commissioner（手机 App）通过这个 Cluster 扫描设备周围的可用网络、写入网络凭据、指示设备连接到指定网络。

Feature 特性（Feature Map）

NetworkCommissioning Cluster 通过 Feature Map 标识设备支持的网络接口类型。 一个设备必须且只能支持以下三种特性之一（互斥关系）：

命令（Commands）

NetworkCommissioning 的命令分为两类：Client → Server（Commissioner 发给设备的请求）和 Server → Client（设备返回的响应）。配网操作是请求-响应模式，每个请求命令都有对应的响应命令。

Client → Server（请求命令）

Server → Client（响应命令）

ScanNetworks —— 扫描网络（0x00）

指示设备扫描周围可用的 Wi-Fi 或 Thread 网络。这通常是配网流程的第一步 —— 让用户看到可以连接的网络列表。 设备会返回 ScanNetworksResponse。

↑ 返回命令列表

ScanNetworksResponse —— 扫描结果（0x01）

设备完成网络扫描后返回的响应，包含扫描到的网络列表。Wi-Fi 和 Thread 设备返回的结构体不同。

↑ 返回命令列表

AddOrUpdateWiFiNetwork —— 添加/更新 Wi-Fi 网络（0x02）

向设备写入 Wi-Fi 网络凭据（SSID + 密码）。如果设备已存储相同 SSID 的凭据，则更新密码；否则新增一条。 设备返回 NetworkConfigResponse。

↑ 返回命令列表

AddOrUpdateThreadNetwork —— 添加/更新 Thread 网络（0x03）

向设备写入 Thread 网络凭据（Operational Dataset）。Thread 的凭据是一个完整的 Operational Dataset， 包含 PAN ID、Channel、Network Key 等信息。设备返回 NetworkConfigResponse。

↑ 返回命令列表

RemoveNetwork —— 删除网络（0x04）

删除设备上已存储的网络凭据。通过 NetworkID 指定要删除的网络。设备返回 NetworkConfigResponse。

↑ 返回命令列表

NetworkConfigResponse —— 网络配置响应（0x05）

设备对 AddOrUpdateWiFiNetwork、AddOrUpdateThreadNetwork、RemoveNetwork、ReorderNetwork 命令的统一响应。

↑ 返回命令列表

ConnectNetwork —— 连接网络（0x06）

指示设备连接到之前通过 AddOrUpdateWiFiNetwork / AddOrUpdateThreadNetwork 存储的网络。 这是配网流程中让设备「真正上网」的那一步。设备返回 ConnectNetworkResponse。

↑ 返回命令列表

ConnectNetworkResponse —— 连接结果（0x07）

设备返回的网络连接结果。如果连接失败，ErrorValue 会包含平台层的错误码，有助于排查问题。

↑ 返回命令列表

ReorderNetwork —— 调整网络优先级（0x08）

调整已存储网络的优先级顺序。设备在重启或网络切换时，会按优先级从高到低尝试连接。 设备返回 NetworkConfigResponse。

↑ 返回命令列表

属性详解

NetworkCommissioning Cluster 的属性描述了网络接口的能力和当前状态。点击下方汇总表中的属性 ID 可跳转到详细说明。

网络容量（0x00-0x01）

描述设备能存储多少个网络凭据，以及当前已配置了哪些网络。

NetworkInfoStruct 结构体

↑ 返回属性列表

时间参数（0x02-0x03）

定义扫描和连接操作的最大耗时，帮助 Commissioner 设置合理的超时等待。

↑ 返回属性列表

接口状态（0x04-0x07）

网络接口的启用状态和上次操作结果，是排查配网问题的核心信息。

↑ 返回属性列表

Wi-Fi 扩展（0x08）

Matter 1.3 新增的 Wi-Fi 相关属性，仅当 Feature Map 包含 WI 时存在。

↑ 返回属性列表

Thread 扩展（0x09-0x0A）

Matter 1.3 新增的 Thread 相关属性，仅当 Feature Map 包含 TH 时存在。

↑ 返回属性列表

枚举与结构体

NetworkCommissioningStatusEnum

所有网络操作命令的响应都会包含这个状态码，用于表示操作结果。这是排查配网问题时最先看的字段。

WiFiBandEnum

标识 Wi-Fi 工作频段，用于扫描结果和 SupportedWiFiBands 属性。

WiFiSecurityBitmap

Wi-Fi 网络的安全类型位图，一个网络可以同时支持多种安全协议（多个 bit 为 1）。

WiFiInterfaceScanResultStruct

Wi-Fi 扫描结果中每个网络的详细信息。

↑ 返回枚举列表

ThreadInterfaceScanResultStruct

Thread 扫描结果中每个网络的详细信息。

↑ 返回枚举列表

标准示例

属性数据示例

以下是一个已配网的 Wi-Fi 设备的典型属性数据：

{
  // --- 网络容量 ---
  "0x00": 1,             // MaxNetworks = 1（最多存 1 个网络凭据）
  "0x01": [{             // Networks = 已配置的网络列表
    "networkID": "TXlIb21lV2lGaQ==",  // Base64 编码的 SSID
    "connected": true                   // 当前已连接
  }],

  // --- 扫描与连接超时 ---
  "0x02": 30,            // ScanMaxTimeSeconds = 30 秒
  "0x03": 60,            // ConnectMaxTimeSeconds = 60 秒

  // --- 接口状态 ---
  "0x04": true,          // InterfaceEnabled = true（网络接口已启用）

  // --- 上次操作结果 ---
  "0x05": 0,             // LastNetworkingStatus = Success
  "0x06": "TXlIb21lV2lGaQ==",  // LastNetworkID（上次操作的网络 ID）
  "0x07": null           // LastConnectErrorValue = null（无错误）
}

扫描网络流程示例

Commissioner 发起 Wi-Fi 扫描并获取结果：

// Commissioner → Device：扫描 Wi-Fi 网络
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0031",
      "commandId": "0x00"        // ScanNetworks
    },
    "commandFields": {
      "ssid": null,              // null = 扫描所有网络
      "breadcrumb": 1            // 配网进度标记
    }
  }]
}

// Device → Commissioner：返回扫描结果
{
  "networkingStatus": 0,         // Success
  "wiFiScanResults": [
    {
      "security": 4,             // WPA2-Personal
      "ssid": "MyHomeWiFi",
      "bssid": "AA:BB:CC:DD:EE:FF",
      "channel": 6,
      "wiFiBand": 0,             // 2.4GHz
      "rssi": -45
    },
    {
      "security": 8,             // WPA3-Personal
      "ssid": "Office5G",
      "bssid": "11:22:33:44:55:66",
      "channel": 36,
      "wiFiBand": 1,             // 5GHz
      "rssi": -62
    }
  ]
}

添加 Wi-Fi 网络示例

向设备写入 Wi-Fi 凭据：

// 添加 Wi-Fi 网络凭据
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0031",
      "commandId": "0x02"        // AddOrUpdateWiFiNetwork
    },
    "commandFields": {
      "ssid": "TXlIb21lV2lGaQ==",  // "MyHomeWiFi" 的 Base64
      "credentials": "cGFzc3dvcmQ=", // 密码的 Base64
      "breadcrumb": 2
    }
  }]
}

// 设备回复 NetworkConfigResponse
{
  "networkingStatus": 0,         // Success
  "networkIndex": 0              // 存储在索引 0
}

常见场景