Matter Cluster 49 — Network Commissioning Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 49 values in the device shadow use this format:

endpoint_id / 49 / attribute_id

Example:

{
  "0/49/0": 1
}

Cluster 49 Features

The FeatureMap attribute (0/49/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 7 means every feature listed above is enabled.

Data Types

NetworkCommissioningStatusEnum

WiFiBandEnum

WiFiBandEnum encodes a supported Wi-Fi frequency band present in the WiFiBand field of the WiFiInterfaceScanResultStruct.

ThreadCapabilitiesBitmap (bitmap)

The ThreadCapabilitiesBitmap encodes the supported Thread features and capabilities of a Thread-enabled network interface. The valid combinations of capabilities are restricted and dependent on Thread version.

WiFiSecurityBitmap (bitmap)

WiFiSecurityBitmap encodes the supported Wi-Fi security types present in the Security field of the WiFiInterfaceScanResultStruct.

NetworkInfoStruct (struct)

NetworkInfoStruct struct describes an existing network configuration, as provided in the Networks attribute.

ThreadInterfaceScanResultStruct (struct)

ThreadInterfaceScanResultStruct represents a single Thread network scan result.

WiFiInterfaceScanResultStruct (struct)

WiFiInterfaceScanResultStruct represents a single Wi-Fi network scan result.

Cluster 49 Attributes

Cluster 49 defines 11 attributes 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 — MaxNetworks

Path example:

0/49/0

This indicates the maximum number of network configuration entries that can be added, based on available device resources. The length of the Networks attribute is less than or equal to this value.

Example:

{
  "0/49/0": 1
}

Attribute 1 / 0x0001 — Networks

Path example:

0/49/1

Indicates the network configurations that are usable on the network interface represented by this cluster server instance. The order of configurations in the list reflects precedence. That is, any time the Node attempts to connect to the network it must attempt to do so using the configurations in Networks Attribute in the order as they appear in the list. The order of list items only be modified by the AddOrUpdateThreadNetwork, AddOrUpdateWiFiNetwork and ReorderNetwork commands.

Each entry is a NetworkInfoStruct (see Data Types).

Example:

{
  "0/49/1": []
}

Attribute 2 / 0x0002 — ScanMaxTimeSeconds

Path example:

0/49/2

No condensed specification text is available for ScanMaxTimeSeconds; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/49/2": 0
}

Attribute 3 / 0x0003 — ConnectMaxTimeSeconds

Path example:

0/49/3

Indicates the maximum duration taken, in seconds, by the network interface on this cluster server instance to report a successful or failed network connection indication. This maximum time must account for all operations needed until a successful network connection is deemed to have occurred, including, for example, obtaining IP addresses, or the execution of necessary internal retries.

Example:

{
  "0/49/3": 0
}

Attribute 4 / 0x0004 — InterfaceEnabled

Path example:

0/49/4

Indicates whether the associated network interface is enabled or not. By default all network interfaces should be enabled during initial commissioning (InterfaceEnabled set to true). It is undefined what happens if InterfaceEnabled is written to false on the same interface as that which is used to write the value. In that case, it is possible that the Administrator would have to await expiry of the fail-safe, and associated recovery of network configuration to prior safe values, before being able to communicate with the node again.

Example:

{
  "0/49/4": true
}

Attribute 5 / 0x0005 — LastNetworkingStatus

Path example:

0/49/5

Indicates the status of the last attempt either scan or connect to an operational network, using this interface, whether by invocation of the ConnectNetwork command or by autonomous connection after loss of connectivity or during initial establishment. If no such attempt was made, or no network configurations exist in the Networks attribute, then this attribute is set to null. This attribute is present to assist with error recovery during Network commissioning and to assist in non-concurrent networking commissioning flows.

Values (NetworkCommissioningStatusEnum):

Example:

{
  "0/49/5": 0
}

Attribute 6 / 0x0006 — LastNetworkID

Path example:

0/49/6

No condensed specification text is available for LastNetworkID; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/49/6": "AQID"
}

Attribute 7 / 0x0007 — LastConnectErrorValue

Path example:

0/49/7

Indicates the ErrorValue used in the last failed attempt to connect to an operational network, using this interface, whether by invocation of the ConnectNetwork command or by autonomous connection after loss of connectivity or during initial establishment. If no such attempt was made, or no network configurations exist in the Networks attribute, then this attribute is set to null. If the last connection succeeded, as indicated by a value of Success in the LastNetworkingStatus attribute, then this field is set to null. This attribute is present to assist with error recovery during Network commissioning and to assist in non-concurrent networking commissioning flows.

Example:

{
  "0/49/7": 1
}

Attribute 8 / 0x0008 — SupportedWiFiBands

Path example:

0/49/8

Indicates all the frequency bands supported by the Wi-Fi interface configured by the cluster instance.

Example:

{
  "0/49/8": []
}

Attribute 9 / 0x0009 — SupportedThreadFeatures

Path example:

0/49/9

Indicates all of the Thread features supported by the Thread interface configured by the cluster instance. This attribute is primarily used to determine the most important general capabilities of the Thread interface associated with the cluster instance, as opposed to the current runtime dynamic configuration. Most run-time details of the actual Thread interface are found in the Thread Network Diagnostics cluster, if supported.

Bits (ThreadCapabilitiesBitmap):

Example:

{
  "0/49/9": 0
}

Attribute 10 / 0x000A — ThreadVersion

Path example:

0/49/10

Indicates the Thread version supported by the Thread interface configured by the cluster instance. The format must match the value mapping found in the "Version TLV" section of Thread specification.

Example:

{
  "0/49/10": 1
}

Cluster 49 Commands

Cluster 49 has 6 client-to-server commands and 3 responses.

AcceptedCommandList

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

endpoint_id / 49 / 65529

{
  "0/49/65529": [
    0,
    2,
    3,
    4,
    6,
    8
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

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

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

Purpose

This command is used to scan for available networks on the network interface associated with the cluster instance. This command must scan on the Cluster instance's associated network interface for either of: - All available networks (non-directed scanning) - Specific networks (directed scanning) Scanning for available networks detects all networks of the type corresponding to the cluster server instance's associated network interface that are possible to join, such as all visible Wi-Fi access points for Wi-Fi cluster server instances, all Thread PANs for Thread cluster server instances, within bounds of the maximum response size.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 49,
    "command_name": "ScanNetworks",
    "payload": {
      "ssid": "AQID",
      "breadcrumb": 1
    }
  }
}

The device answers with ScanNetworksResponse (see below).

Command: ScanNetworksResponse

Purpose

This command is used to report the results of a ScanNetworks command. This command contains the status of the last ScanNetworks command, and the associated scan results if the operation was successful. Results are valid only if NetworkingStatus is Success. Before generating a ScanNetworksResponse, the server must set the LastNetworkingStatus attribute value to the NetworkingStatus matching the response.

Command Identity

Response Fields

NetworkingStatus values (NetworkCommissioningStatusEnum): 0 = Success, 1 = OutOfRange, 2 = BoundsExceeded, 3 = NetworkIDNotFound, 4 = DuplicateNetworkID, 5 = NetworkNotFound, 6 = RegulatoryError, 7 = AuthFailure, 8 = UnsupportedSecurity, 9 = OtherConnectionFailure, 10 = IPV6Failed, 11 = IPBindFailed, 12 = UnknownError

Command: AddOrUpdateWiFiNetwork

Purpose

This command is used to add or update a Wi-Fi network configuration. This command is used to add or modify Wi-Fi network configurations. If this command is received without an armed fail-safe context, then this command must fail with a FAILSAFE_REQUIRED status code sent back to the initiator.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 49,
    "command_name": "AddOrUpdateWiFiNetwork",
    "payload": {
      "ssid": "AQID",
      "credentials": "AQID"
    }
  }
}

The device answers with NetworkConfigResponse (see below).

Command: AddOrUpdateThreadNetwork

Purpose

This command is used to add or update a Thread network configuration. This command is used to add or modify Thread network configurations. The XPAN ID in the OperationalDataset serves as the NetworkID for the network configuration to be added or updated. If the Networks attribute does not contain an entry with the same NetworkID as the one provided in the OperationalDataset, the operation is considered an addition, otherwise, it is considered an update.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 49,
    "command_name": "AddOrUpdateThreadNetwork",
    "payload": {
      "operationalDataset": "AQID"
    }
  }
}

The device answers with NetworkConfigResponse (see below).

Command: RemoveNetwork

Purpose

This command is used to remove a network configuration on the network interface associated with the cluster instance. This command must remove the network configuration from the Cluster if there was already a network configuration with the same NetworkID. The relative order of the entries in the Networks attribute must remain unchanged, except for the removal of the requested network configuration. If this command is received without an armed fail-safe context, then this command must fail with a FAILSAFE_REQUIRED status code sent back to the initiator.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 49,
    "command_name": "RemoveNetwork",
    "payload": {
      "networkID": "AQID"
    }
  }
}

The device answers with NetworkConfigResponse (see below).

Command: NetworkConfigResponse

Purpose

This command is used to report the results of a network configuration command (AddOrUpdateWiFiNetwork, AddOrUpdateThreadNetwork, or RemoveNetwork). This response command relates status information for some commands which require it as their response command. See each individual cluster server command for the situations that may cause a NetworkingStatus different than Success. Before generating a NetworkConfigResponse, the server must set the LastNetworkingStatus attribute value to the NetworkingStatus matching the response.

Command Identity

Response Fields

NetworkingStatus values (NetworkCommissioningStatusEnum): 0 = Success, 1 = OutOfRange, 2 = BoundsExceeded, 3 = NetworkIDNotFound, 4 = DuplicateNetworkID, 5 = NetworkNotFound, 6 = RegulatoryError, 7 = AuthFailure, 8 = UnsupportedSecurity, 9 = OtherConnectionFailure, 10 = IPV6Failed, 11 = IPBindFailed, 12 = UnknownError

Command: ConnectNetwork

Purpose

This command is used to connect to a network on the network interface associated with the cluster instance. This command must attempt to connect to a network whose configuration was previously added by either the AddOrUpdateWiFiNetwork or AddOrUpdateThreadNetwork commands. Network is identified by its NetworkID. This command must fail with a BUSY status code returned to the initiator if the server is currently unable to proceed with such an operation, such as if it is currently attempting to connect in the background, or is already proceeding with a prior ConnectNetwork.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 49,
    "command_name": "ConnectNetwork",
    "payload": {
      "networkID": "AQID"
    }
  }
}

The device answers with ConnectNetworkResponse (see below).

Command: ConnectNetworkResponse

Purpose

This command is used to report the results of a ConnectNetwork command. Before generating a ConnectNetworkResponse, the server must: - Set the LastNetworkingStatus attribute value to the NetworkingStatus matching the response. - Set the LastNetworkID attribute value to the NetworkID that was used in the ConnectNetwork command which caused the response to be generated. - Set the LastConnectErrorValue attribute value to the ErrorValue matching the response, including setting it to null if the ErrorValue is not applicable.

Command Identity

Response Fields

NetworkingStatus values (NetworkCommissioningStatusEnum): 0 = Success, 1 = OutOfRange, 2 = BoundsExceeded, 3 = NetworkIDNotFound, 4 = DuplicateNetworkID, 5 = NetworkNotFound, 6 = RegulatoryError, 7 = AuthFailure, 8 = UnsupportedSecurity, 9 = OtherConnectionFailure, 10 = IPV6Failed, 11 = IPBindFailed, 12 = UnknownError

Command: ReorderNetwork

Purpose

This command is used to re-order the network configuration list. This command must set the specific order of the network configuration selected by its NetworkID in the Networks attribute to match the position given by NetworkIndex.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 0,
    "cluster_id": 49,
    "command_name": "ReorderNetwork",
    "payload": {
      "networkID": "AQID",
      "networkIndex": 1
    }
  }
}

The device answers with NetworkConfigResponse (see below).

Cluster 49 Events

Cluster 49 defines no events.

SmartphoneKey Notes

• Used during commissioning only. AcceptedCommandList tells you whether a device is a Thread (AddOrUpdateThreadNetwork, id 3) or Wi-Fi (AddOrUpdateWiFiNetwork, id 2) device.
• Shadow paths follow endpoint/49/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.