NetworkCommissioning Cluster

Cluster ID: 0x0031  |  Endpoint: Typically on Endpoint 0 (Root Endpoint)

NetworkCommissioning is the most critical Cluster in the Matter device commissioning process, responsible for managing device network credentials — including Wi-Fi passwords, Thread network parameters, or Ethernet configurations. The Commissioner (phone App) uses this Cluster to scan available networks around the device, write network credentials, and instruct the device to connect to a specified network.

Features (Feature Map)

The NetworkCommissioning Cluster uses the Feature Map to indicate which network interface types the device supports. A device must support exactly one of the following three features (mutually exclusive):

Commands

NetworkCommissioning commands fall into two categories: Client → Server (requests from the Commissioner to the device) and Server → Client (responses from the device). Commissioning operations follow a request-response pattern, where each request command has a corresponding response command.

Client → Server (Request Commands)

Server → Client (Response Commands)

ScanNetworks — Scan Networks (0x00)

Instructs the device to scan for available Wi-Fi or Thread networks nearby. This is typically the first step in the commissioning flow — showing users the list of networks they can connect to. The device returns ScanNetworksResponse.

↑ Back to Commands

ScanNetworksResponse — Scan Results (0x01)

Response returned after the device completes a network scan, containing the list of discovered networks. Wi-Fi and Thread devices return different structures.

↑ Back to Commands

AddOrUpdateWiFiNetwork — Add/Update Wi-Fi Network (0x02)

Write Wi-Fi network credentials (SSID + password) to the device. If credentials for the same SSID already exist, the password is updated; otherwise a new entry is added. The device returns NetworkConfigResponse.

↑ Back to Commands

AddOrUpdateThreadNetwork — Add/Update Thread Network (0x03)

Write Thread network credentials (Operational Dataset) to the device. Thread credentials consist of a complete Operational Dataset containing PAN ID, Channel, Network Key, and other information. The device returns NetworkConfigResponse.

↑ Back to Commands

RemoveNetwork — Remove Network (0x04)

Remove stored network credentials from the device. Specify the network to remove via NetworkID. The device returns NetworkConfigResponse.

↑ Back to Commands

NetworkConfigResponse — Network Config Response (0x05)

Unified response from the device for AddOrUpdateWiFiNetwork, AddOrUpdateThreadNetwork, RemoveNetwork, and ReorderNetwork commands.

↑ Back to Commands

ConnectNetwork — Connect Network (0x06)

Instructs the device to connect to a network previously stored via AddOrUpdateWiFiNetwork / AddOrUpdateThreadNetwork. This is the step in the commissioning flow that makes the device "actually go online." The device returns ConnectNetworkResponse.

↑ Back to Commands

ConnectNetworkResponse — Connection Result (0x07)

Network connection result returned by the device. If the connection fails, ErrorValue contains a platform-level error code to help troubleshoot issues.

↑ Back to Commands

ReorderNetwork — Adjust Network Priority (0x08)

Adjust the priority order of stored networks. The device attempts connections from highest to lowest priority during restart or network switching. The device returns NetworkConfigResponse.

↑ Back to Commands

Attributes

NetworkCommissioning Cluster attributes describe the capabilities and current state of the network interface. Click an attribute ID in the summary table below to jump to its detailed description.

Network Capacity (0x00-0x01)

Describes how many network credentials the device can store, and which networks are currently configured.

NetworkInfoStruct Structure

↑ Back to Attributes

Timing Parameters (0x02-0x03)

Define the maximum duration for scan and connect operations, helping the Commissioner set reasonable timeouts.

↑ Back to Attributes

Interface Status (0x04-0x07)

The network interface's enabled state and last operation result are core information for troubleshooting commissioning issues.

↑ Back to Attributes

Wi-Fi Extensions (0x08)

Wi-Fi related attributes added in Matter 1.3, present only when the Feature Map includes WI.

↑ Back to Attributes

Thread Extensions (0x09-0x0A)

Thread related attributes added in Matter 1.3, present only when the Feature Map includes TH.

↑ Back to Attributes

Enums & Structs

NetworkCommissioningStatusEnum

All network operation command responses include this status code to indicate the operation result. This is the first field to check when troubleshooting commissioning issues.

WiFiBandEnum

Identifies the Wi-Fi operating band, used in scan results and the SupportedWiFiBands attribute.

WiFiSecurityBitmap

Security type bitmap for Wi-Fi networks. A network can support multiple security protocols simultaneously (multiple bits set to 1).

WiFiInterfaceScanResultStruct

Detailed information for each network in Wi-Fi scan results.

↑ Back to Enum List

ThreadInterfaceScanResultStruct

Detailed information for each network in Thread scan results.

↑ Back to Enum List

Standard Example

Attribute Data Example

The following is typical attribute data for a commissioned Wi-Fi device:

{
  // --- Network Capacity ---
  "0x00": 1,             // MaxNetworks = 1 (max 1 network credential)
  "0x01": [{             // Networks = List of configured networks
    "networkID": "TXlIb21lV2lGaQ==",  // Base64-encoded SSID
    "connected": true                   // Currently connected
  }],

  // --- Scan & Connection Timeout ---
  "0x02": 30,            // ScanMaxTimeSeconds = 30 seconds
  "0x03": 60,            // ConnectMaxTimeSeconds = 60 seconds

  // --- Interface Status ---
  "0x04": true,          // InterfaceEnabled = true (network interface enabled)

  // --- Last Operation Result ---
  "0x05": 0,             // LastNetworkingStatus = Success
  "0x06": "TXlIb21lV2lGaQ==",  // LastNetworkID (network ID of last operation)
  "0x07": null           // LastConnectErrorValue = null (no error)
}

Scan Networks Flow Example

Commissioner initiates a Wi-Fi scan and retrieves results:

// Commissioner → Device: Scan Wi-Fi networks
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0031",
      "commandId": "0x00"        // ScanNetworks
    },
    "commandFields": {
      "ssid": null,              // null = scan all networks
      "breadcrumb": 1            // Commissioning progress marker
    }
  }]
}

// Device → Commissioner: Return scan results
{
  "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
    }
  ]
}

Add Wi-Fi Network Example

Write Wi-Fi credentials to the device:

// Add Wi-Fi network credentials
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0031",
      "commandId": "0x02"        // AddOrUpdateWiFiNetwork
    },
    "commandFields": {
      "ssid": "TXlIb21lV2lGaQ==",  // Base64 of "MyHomeWiFi"
      "credentials": "cGFzc3dvcmQ=", // Base64 of password
      "breadcrumb": 2
    }
  }]
}

// Device replies with NetworkConfigResponse
{
  "networkingStatus": 0,         // Success
  "networkIndex": 0              // Stored at index 0
}

Common Scenarios