Merge branch 'custom-network-config' into 'main'

components/esp_matter: add CustomNetworkConfig support

See merge request app-frameworks/esp-matter!1453

.codespellrc

@@ -1,3 +1,3 @@
 [codespell]
 ignore-regex = _
-ignore-words-list = ot, bootup, requestor, pase, lits, kNo, currenty
+ignore-words-list = ot, bootup, requestor, pase, lits, kNo, currenty, rsource, CurrentY

components/esp_matter/Kconfig

@@ -18,7 +18,7 @@ menu "ESP Matter"
         string "ESP Matter NVS partition name"
         default "nvs"
         help
-            The NVS Partition name for ESP Matter to store the NONVOLATILE attribues
+            The NVS Partition name for ESP Matter to store the NONVOLATILE attributes
 
     config ESP_MATTER_DEFERRED_ATTR_PERSISTENCE_TIME_MS
         int "ESP Matter deferred attribute persistence time (ms)"
@@ -243,6 +243,16 @@ menu "ESP Matter"
             Disable this option to initialize Thread stack and start Thread task with more
             flexibility.
 
+    config CUSTOM_NETWORK_CONFIG
+        bool "Use custom network commissioning (skip Network Commissioning cluster)"
+        default n
+        help
+            Enable this if the device uses out-of-band-configured networking
+            (e.g. rich user interface, manufacturer-specific means, custom
+            commissioning flows). When enabled, the Network Commissioning
+            cluster will NOT be added to the root node endpoint, per the
+            Matter spec CustomNetworkConfig condition.
+
     menu "Select Supported Matter Clusters"
         visible if ESP_MATTER_ENABLE_DATA_MODEL
 

components/esp_matter/data_model/esp_matter_attribute.cpp

@@ -425,6 +425,7 @@ attribute_t *create_tc_update_deadline(cluster_t *cluster, nullable<uint32_t> va
 } /* attribute */
 } /* general_commissioning */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace network_commissioning {
 namespace attribute {
 
@@ -496,6 +497,7 @@ attribute_t *create_thread_version(cluster_t *cluster, uint16_t value)
 
 } /* attribute */
 } /* network_commissioning */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace general_diagnostics {
 namespace attribute {

components/esp_matter/data_model/esp_matter_attribute.h

@@ -133,6 +133,7 @@ attribute_t *create_tc_update_deadline(cluster_t *cluster, nullable<uint32_t> va
 } /* attribute */
 } /* general_commissioning */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace network_commissioning {
 namespace attribute {
 attribute_t *create_max_networks(cluster_t *cluster, uint8_t value);
@@ -148,6 +149,7 @@ attribute_t *create_supported_thread_features(cluster_t *cluster, uint16_t value
 attribute_t *create_thread_version(cluster_t *cluster, uint16_t value);
 } /* attribute */
 } /* network_commissioning */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace general_diagnostics {
 namespace attribute {

components/esp_matter/data_model/esp_matter_cluster.cpp

@@ -425,6 +425,7 @@ cluster_t *create(endpoint_t *endpoint, config_t *config, uint8_t flags)
 }
 } /* general_commissioning */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace network_commissioning {
 const function_generic_t *function_list = NULL;
 const int function_flags = CLUSTER_FLAG_NONE;
@@ -488,6 +489,7 @@ cluster_t *create(endpoint_t *endpoint, config_t *config, uint8_t flags)
     return cluster;
 }
 } /* network_commissioning */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace general_diagnostics {
 const function_generic_t *function_list = NULL;

components/esp_matter/data_model/esp_matter_cluster.h

@@ -110,6 +110,7 @@ typedef struct config {
 cluster_t *create(endpoint_t *endpoint, config_t *config, uint8_t flags);
 } /* general_commissioning */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace network_commissioning {
 typedef struct config {
     uint32_t feature_map;
@@ -124,6 +125,7 @@ typedef struct config {
 } config_t;
 cluster_t *create(endpoint_t *endpoint, config_t *config, uint8_t flags);
 } /* network_commissioning */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace diagnostic_logs {
 typedef struct config {

components/esp_matter/data_model/esp_matter_command.cpp

@@ -1393,6 +1393,7 @@ command_t *create_set_tc_acknowledgements_response(cluster_t *cluster)
 } /* command */
 } /* general_commissioning */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace network_commissioning {
 namespace command {
 
@@ -1452,6 +1453,7 @@ command_t *create_connect_network_response(cluster_t *cluster)
 
 } /* command */
 } /* network_commissioning */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace administrator_commissioning {
 namespace command {

components/esp_matter/data_model/esp_matter_command.h

@@ -120,6 +120,7 @@ command_t *create_set_tc_acknowledgements_response(cluster_t *cluster);
 } /* command */
 } /* general_commissioning */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace network_commissioning {
 namespace command {
 command_t *create_scan_networks(cluster_t *cluster);
@@ -133,6 +134,7 @@ command_t *create_network_config_response(cluster_t *cluster);
 command_t *create_connect_network_response(cluster_t *cluster);
 } /* command */
 } /* network_commissioning */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace administrator_commissioning {
 namespace command {

components/esp_matter/data_model/esp_matter_endpoint.cpp

@@ -70,7 +70,9 @@ esp_err_t add(endpoint_t *endpoint, config_t *config)
     access_control::create(endpoint, &(config->access_control), CLUSTER_FLAG_SERVER);
     basic_information::create(endpoint, &(config->basic_information), CLUSTER_FLAG_SERVER);
     general_commissioning::create(endpoint, &(config->general_commissioning), CLUSTER_FLAG_SERVER);
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
     network_commissioning::create(endpoint, &(config->network_commissioning), CLUSTER_FLAG_SERVER);
+#endif
     general_diagnostics::create(endpoint, &(config->general_diagnostics), CLUSTER_FLAG_SERVER);
     administrator_commissioning::create(endpoint, &(config->administrator_commissioning), CLUSTER_FLAG_SERVER);
     operational_credentials::create(endpoint, &(config->operational_credentials), CLUSTER_FLAG_SERVER);
@@ -1740,6 +1742,7 @@ esp_err_t add(endpoint_t *endpoint, config_t *config)
 
 } /* thread_border_router */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace secondary_network_interface {
 uint32_t get_device_type_id()
 {
@@ -1766,6 +1769,7 @@ esp_err_t add(endpoint_t *endpoint, config_t *config)
     return ESP_OK;
 }
 } /* secondary_network_interface */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace mounted_on_off_control {
 uint32_t get_device_type_id()

components/esp_matter/data_model/esp_matter_endpoint.h

@@ -223,7 +223,9 @@ typedef struct config {
     cluster::access_control::config_t access_control;
     cluster::basic_information::config_t basic_information;
     cluster::general_commissioning::config_t general_commissioning;
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
     cluster::network_commissioning::config_t network_commissioning;
+#endif
     cluster::general_diagnostics::config_t general_diagnostics;
     cluster::administrator_commissioning::config_t administrator_commissioning;
     cluster::operational_credentials::config_t operational_credentials;
@@ -962,6 +964,7 @@ endpoint_t *create(node_t *node, config_t *config, uint8_t flags, void *priv_dat
 esp_err_t add(endpoint_t *endpoint, config_t *config);
 } /* thread_border_router */
 
+#ifndef CONFIG_CUSTOM_NETWORK_CONFIG
 namespace secondary_network_interface {
 typedef struct config {
     cluster::descriptor::config_t descriptor;
@@ -973,6 +976,7 @@ uint8_t get_device_type_version();
 endpoint_t *create(node_t *node, config_t *config, uint8_t flags, void *priv_data);
 esp_err_t add(endpoint_t *endpoint, config_t *config);
 } /* secondary_network_interface */
+#endif // CONFIG_CUSTOM_NETWORK_CONFIG
 
 namespace mounted_on_off_control {
 typedef struct config : on_off_with_lighting_config {

docs/en/faq.rst

@@ -427,6 +427,27 @@ For example, to update ``DefaultOTAProviders`` attribute in ``OTASoftwareUpdateR
           request->AddDefaultOtaProvider(provider);
       }
 
+A1.18 Devices with custom means of network configuration (CustomNetworkConfig)
+------------------------------------------------------------------------------
+
+Some devices configure their network through custom means — such as a rich user interface,
+manufacturer-specific provisioning, custom commissioning flows, or a future IP-compliant
+network technology not yet directly supported by the Network Commissioning cluster — rather
+than through the standard Matter Network Commissioning cluster.
+
+The Matter specification defines a ``CustomNetworkConfig`` condition for such devices.
+When this condition is set, the Network Commissioning cluster is not required on the
+Root Node endpoint.
+
+To enable this in the ESP-Matter SDK:
+
+1. Enable the ``CONFIG_CUSTOM_NETWORK_CONFIG`` option in menuconfig
+   Menu path: (Top) -> Component config -> ESP Matter -> Use custom network commissioning (skip Network Commissioning cluster)
+
+2. When enabled, the Network Commissioning cluster will not be added to the
+   root node endpoint (endpoint 0). The device is expected to handle network
+   configuration through its own out-of-band mechanism.
+
 .. _bleprph: https://github.com/espressif/esp-idf/tree/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/bleprph
 .. _blecent: https://github.com/espressif/esp-idf/tree/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/blecent
 .. _bleprph_advertise(): https://github.com/espressif/esp-idf/blob/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/bleprph/main/main.c#L146