doc: Improved the documentation related to Matter code-gen.

kkasperczyk-no · nordicjm · commit 576c54af9328 · 2025-12-02T07:36:58.000Z
The way of handling data model related code changed in Matter
a lot. Added advanced migration guide and updated the instruction
for creating cluster extension.

Signed-off-by: Kamil Kasperczyk &lt;kamil.kasperczyk@nordicsemi.no&gt;
diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt
@@ -194,6 +194,7 @@
 .. _`Generate partition script`: https://github.com/nrfconnect/sdk-connectedhomeip/blob/bf45da8a28/scripts/tools/nrfconnect/nrfconnect_generate_partition.py
 .. _`Matter nRF Connect scripts`: https://github.com/nrfconnect/sdk-connectedhomeip/tree/bf45da8a28/scripts/tools/nrfconnect
 .. _`Matter nRF Connect Kconfig`: https://github.com/nrfconnect/sdk-connectedhomeip/blob/bf45da8a28/config/nrfconnect/chip-module/Kconfig
+.. _`Matter Clusters Code-Driven support`: https://github.com/nrfconnect/sdk-connectedhomeip/blob/bf45da8a28/src/app/common/templates/config-data.yaml
 
 .. _`bt_nus_service.cpp`: https://github.com/nrfconnect/sdk-nrf/blob/main/samples/matter/common/src/bt_nus/bt_nus_service.cpp
 .. _`bt_nus_service.h`: https://github.com/nrfconnect/sdk-nrf/blob/main/samples/matter/common/src/bt_nus/bt_nus_service.h
diff --git a/doc/nrf/protocols/matter/getting_started/custom_clusters.rst b/doc/nrf/protocols/matter/getting_started/custom_clusters.rst
@@ -798,19 +798,159 @@ Then, you need to implement the following command in the application code:
       // TODO: Implement the plugin server init callback.
    }
 
-The same applies to the extended commands.
+Implement the extension handling in the application code
+********************************************************
 
-.. note::
+The way you handle cluster extensions depends on whether the cluster that you want to extend is implemented using the code-driven approach or with ZAP-generated code.
+
+If the cluster is implemented using the code-driven approach, you must inherit from this cluster delegate class and implement the methods to handle the customized part.
+Then, you must unregister the original cluster delegate and register the customized one.
+For example, if you want to extend the ``BasicInformation`` cluster, you need to implement it in the application code as follows:
+
+* Inherit from the ``BasicInformationCluster`` class and override the methods to handle the customized part.
+
+  .. code-block:: C++
+
+     #include <app/clusters/basic-information/BasicInformationCluster.h>
+     #include <app/server-cluster/ServerClusterContext.h>
+     #include <app/server-cluster/ServerClusterInterface.h>
+
+     class BasicInformationExtension : public chip::app::Clusters::BasicInformationCluster {
+     public:
+        BasicInformationExtension() {}
+
+        /* Overrides the default BasicInformationCluster implementation. */
+        chip::app::DataModel::ActionReturnStatus
+        ReadAttribute(const chip::app::DataModel::ReadAttributeRequest &request,
+                      chip::app::AttributeValueEncoder &encoder) override;
+
+	     CHIP_ERROR Attributes(const chip::app::ConcreteClusterPath &path,
+			      chip::ReadOnlyBufferBuilder<chip::app::DataModel::AttributeEntry> &builder) override;
+
+		  CHIP_ERROR AcceptedCommands(const chip::app::ConcreteClusterPath &path,
+			      chip::ReadOnlyBufferBuilder<chip::app::DataModel::AcceptedCommandEntry> &builder) override;
+
+		  CHIP_ERROR GeneratedCommands(const chip::app::ConcreteClusterPath &path,
+			      chip::ReadOnlyBufferBuilder<chip::app::DataModel::GeneratedCommandEntry> &builder) override;
+
+		  CHIP_ERROR Attributes(const chip::app::ConcreteClusterPath &path,
+			      chip::ReadOnlyBufferBuilder<chip::app::DataModel::AttributeEntry> &builder) override;
+
+        chip::app::DataModel::ActionReturnStatus SetExtendedAttribute(bool newExtendedAttribute);
+
+	  private:
+		  bool mExtendedAttribute;
+	  };
+
+* Implement the body of overridden methods to handle the custom attributes, commands and events.
+
+  .. code-block:: C++
+
+     #include <app/util/attribute-storage.h>
+     #include <clusters/BasicInformation/Events.h>
+     #include <clusters/BasicInformation/Metadata.h>
+
+     using namespace chip;
+     using namespace chip::app;
+
+     constexpr AttributeId kExtendedAttributeId = 0x17;
+
+     constexpr DataModel::AttributeEntry kExtraAttributeMetadata[] = {
+        { kExtendedAttributeId,
+        {} /* qualities */,
+        Access::Privilege::kView /* readPriv */,
+        std::nullopt /* writePriv */ },
+     };
+
+     DataModel::ActionReturnStatus BasicInformationExtension::SetExtendedAttribute(bool newExtendedAttribute)
+     {
+        mExtendedAttribute = newExtendedAttribute;
+        return CHIP_NO_ERROR;
+     }
+
+     DataModel::ActionReturnStatus BasicInformationExtension::ReadAttribute(const DataModel::ReadAttributeRequest &request,
+                                    AttributeValueEncoder &encoder)
+     {
+        switch (request.path.mAttributeId) {
+        case kExtendedAttributeId:
+           return encoder.Encode(mExtendedAttribute);
+        default:
+           return chip::app::Clusters::BasicInformationCluster::ReadAttribute(request, encoder);
+        }
+     }
+
+     DataModel::ActionReturnStatus BasicInformationExtension::WriteAttribute(const DataModel::WriteAttributeRequest &request,
+                                 AttributeValueDecoder &decoder)
+     {
+        switch (request.path.mAttributeId) {
+        case kExtendedAttributeId:
+           bool newExtendedAttribute;
+           ReturnErrorOnFailure(decoder.Decode(newExtendedAttribute));
+           return NotifyAttributeChangedIfSuccess(request.path.mAttributeId, SetExtendedAttribute(newExtendedAttribute));
+        default:
+           return chip::app::Clusters::BasicInformationCluster::WriteAttribute(request, decoder);
+        }
+     }
+
+     CHIP_ERROR BasicInformationExtension::Attributes(const ConcreteClusterPath &path,
+                       ReadOnlyBufferBuilder<DataModel::AttributeEntry> &builder)
+     {
+        ReturnErrorOnFailure(builder.ReferenceExisting(kExtraAttributeMetadata));
+
+        return chip::app::Clusters::BasicInformationCluster::Attributes(path, builder);
+     }
 
-   Before the |NCS| v3.2.0, the extended commands callback were handled by the ``emberAf...`` functions.
-
-   For example, if you want to extend the ``BasicInformation`` cluster with the ``ExtendedCommand`` command, you need to implement it in the application code as follows:
+     CHIP_ERROR BasicInformationExtension::AcceptedCommands(const ConcreteClusterPath &path,
+                              ReadOnlyBufferBuilder<DataModel::AcceptedCommandEntry> &builder)
+     {
+        /* The BasicInformationCluster does not have any commands, so it is not necessary to call the implementation of the base class. */
+        static constexpr DataModel::AcceptedCommandEntry kAcceptedCommands[] = {
+           Clusters::BasicInformation::Commands::ExtendedCommand::kMetadataEntry
+        };
+        return builder.ReferenceExisting(kAcceptedCommands);
+     }
+
+     std::optional<DataModel::ActionReturnStatus>
+     BasicInformationExtension::InvokeCommand(const DataModel::InvokeRequest &request, chip::TLV::TLVReader &input_arguments,
+                     CommandHandler *handler)
+     {
+        switch (request.path.mCommandId) {
+        case Clusters::BasicInformation::Commands::ExtendedCommand::Id: {
+           /* Implement the command handling logic here */
+        }
+        default:
+           /* The BasicInformationCluster does not have any commands, so it is not necessary to call the implementation of the base class. */
+           return Protocols::InteractionModel::Status::UnsupportedCommand;
+        }
+     }
+
+* Unregister the original cluster delegate and register the customized one.
+
+  .. code-block:: C++
+
+     #include <data-model-providers/codegen/CodegenDataModelProvider.h>
+
+     /* Replaces the registered BasicInformation cluster with a customized one that adds random number handling. */
+	  auto &registry = chip::app::CodegenDataModelProvider::Instance().Registry();
+
+	  ServerClusterInterface *interface =
+		  registry.Get({ kRootEndpointId, chip::app::Clusters::BasicInformation::Id });
+
+	  VerifyOrDie(interface != nullptr);
+
+	  registry.Unregister(interface);
+     static RegisteredServerCluster<BasicInformationExtension> sBasicInformationExtension;
+
+	  VerifyOrDie(registry.Register(sBasicInformationExtension.Registration()) == CHIP_NO_ERROR);
+
+If the cluster is implemented with ZAP-generated code, you must implement the required extension callbacks by defining the appropriate ``emberAf...Callback`` functions, as described in the code examples and in the cluster XML.
+For example, if you want to extend the ``LevelControl`` cluster with the ``ExtendedCommand`` command, you need to implement it in the application code as follows:
 
    .. code-block:: c
 
       #include <app-common/zap-generated/callback.h>
 
-      bool emberAfBasicInformationClusterBasicInformationExtendedCommandCallback(chip::app::CommandHandler *commandObj, const chip::app::ConcreteCommandPath &commandPath,
+      bool emberAfLevelControlClusterExtendedCommandCallback(chip::app::CommandHandler *commandObj, const chip::app::ConcreteCommandPath &commandPath,
                                                                                  const chip::app::Clusters::BasicInformation::Commands::ExtendedCommand::DecodableType &commandData)
       {
          // TODO: Implement the command.
diff --git a/doc/nrf/releases_and_maturity/migration/migration_guide_3.2.rst b/doc/nrf/releases_and_maturity/migration/migration_guide_3.2.rst
@@ -104,11 +104,72 @@ Matter
 
       To build your custom board with Wi-Fi support, set both the :kconfig:option:`CONFIG_CHIP_WIFI` and :kconfig:option:`CONFIG_WIFI_NRF70` Kconfig options to ``y``.
 
-    * The :file:`zap-generated` directory now includes the :file:`CodeDrivenCallback.h` and :file:`CodeDrivenInitShutdown.cpp` files.
-      The Matter build system gradually moves to the new approach of data model handling and does not auto-generate some bits of a code responsible for command handling anymore.
-      Invoking the ``west zap-generate`` command removes command handler implementations from the existing :file:`IMClusterCommandHandler.cpp` file.
-      To fix this, you must now manually create the :file:`CodeDrivenCallback.h` and :file:`CodeDrivenInitShutdown.cpp` files, and implement the ``MatterClusterServerInitCallback`` and ``MatterClusterServerShutdownCallback`` callbacks to handle server initialization, shutdown, and Matter cluster commands.
-      Ensure that these callbacks contain your application's command handling logic as required.
+    * The Matter build system is transitioning to a code-driven approach for Data Model and Cluster configuration handling.
+      This approach assumes gradual replacement of the configuration based on the ZAP files and the ZAP-generated code, and handling the configuration in the source code.
+      This change has the following impacts:
+
+      * The :file:`zap-generated` directory now includes the :file:`CodeDrivenCallback.h` and :file:`CodeDrivenInitShutdown.cpp` files.
+        Invoking the ``west zap-generate`` command removes command handler implementations from the existing :file:`IMClusterCommandHandler.cpp` file.
+        To fix this, you must now manually create the :file:`CodeDrivenCallback.h` and :file:`CodeDrivenInitShutdown.cpp` files, and implement the ``MatterClusterServerInitCallback`` and ``MatterClusterServerShutdownCallback`` callbacks to handle server initialization, shutdown, and Matter cluster commands.
+        Ensure that these callbacks contain your application's command handling logic.
+      * The code-driven approach is not yet fully implemented for all available clusters, but the coverage will be increasing and it is used for the newly created clusters.
+        The following clusters are already ported using the code-driven approach:
+
+        * Access Control
+        * Administrator Commissioning
+        * Basic Information
+        * Binding
+        * Boolean State
+        * Descriptor
+        * Diagnostic Logs
+        * Ethernet Network Diagnostics
+        * Fixed Label
+        * General Commissioning
+        * General Diagnostics
+        * Group Key Management
+        * Groupcast
+        * Identify
+        * Localization Configuration
+        * OTA Software Update Provider
+        * Operational Credentials
+        * Push AV Stream Transport
+        * Software Diagnostics
+        * Time Format Localization
+        * User Label
+        * Wi-Fi Network Diagnostics
+
+        For the full list of clusters and their migration status, see the `Matter Clusters Code-Driven support`_ file.
+
+      * By default, all the mandatory attributes are enabled for the cluster.
+        To enable an optional attribute or set an optional feature in the feature map, you must do that in the source code by calling dedicated methods.
+        For example, to enable the Positioning feature and the ``CountdownTime`` optional attribute for the Closure Control cluster, perform the following operations:
+
+        * Implement a delegate class for the Closure Control cluster.
+          See the :file:`samples/matter/closure/src/closure_control_endpoint.h` file for an example.
+        * Enable the attribute and set the feature on cluster initialization.
+          See the ``ClosureControlEndpoint::Init`` function in the :file:`samples/matter/closure/src/closure_control_endpoint.cpp` file for an example.
+
+      * To enable an optional cluster, you must register it in the source code by calling a dedicated method.
+        For example, to enable the Identify cluster, implement the following code:
+
+        .. code-block:: C++
+
+           #include <data-model-providers/codegen/CodegenDataModelProvider.h>
+           #include <app/clusters/identify-server/IdentifyCluster.h>
+
+           chip::app::RegisteredServerCluster<chip::app::Clusters::IdentifyCluster> mIdentifyCluster;
+           chip::app::CodegenDataModelProvider::Instance().Registry().Register(mIdentifyCluster.Registration());
+
+      * To enable a cluster extension for the cluster that is already implemented using the code-driven approach, you must inherit from this cluster delegate class and implement the methods to handle the customized part.
+        You also have to unregister the original cluster delegate and register the customized one.
+        For example, to enable a cluster extension for the Basic Information cluster, perform the following operations:
+
+        * Inherit from the ``BasicInformationCluster`` class and override the methods to handle the customized part.
+          See the :file:`samples/matter/manufacturer_specific/src/basic_information_extension.h` file for an example.
+        * Implement the body of overridden methods to handle the custom attributes, commands, and events.
+          See the :file:`samples/matter/manufacturer_specific/src/basic_information_extension.cpp` file for an example.
+        * Unregister the original cluster delegate and register the customized one.
+          See the ``AppTask::StartApp`` function in the :file:`samples/matter/manufacturer_specific/src/app_task.cpp` file for an example.
 
     * :ref:`matter_lock_sample` sample:
 
diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
@@ -259,6 +259,7 @@ The Matter fork in the |NCS| (``sdk-connectedhomeip``) contains all commits from
 * Added:
 
   * Support for the following new device types:
+
     * Irrigation System
     * Soil Sensor
     * Closure
@@ -284,10 +285,10 @@ The Matter fork in the |NCS| (``sdk-connectedhomeip``) contains all commits from
     For example, to enable a specific cluster or its attribute, the new model requires calling a dedicated delegate and registering the cluster in a source code.
     The code-driven approach is not yet fully implemented for all the available clusters, but the coverage will be increasing and it is used for the newly created clusters.
     The new model is meant to be backward compatible with the previous configuration based on the ZAP files and the ZAP-generated code, until the code-driven approach is fully implemented for all the available clusters.
+    See the `Migration guide for nRF Connect SDK v3.2.0`_ for more information.
   * The :ref:`ug_matter_gs_tools_matter_west_commands_sync` command to synchronize the ZAP and :file:`zcl.json` files after updating the ZAP tool version.
   * The check to all :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool` commands that verify whether ZAP tool sandbox permissions are correctly set.
     In case of detecting incorrect permissions, the command will prompt the user to accept automatically updating the permissions to required ones.
-
 * Updated:
 
   * The :ref:`ug_matter_gs_tools_matter_west_commands_append` command to accept ``--clusters`` argument instead of ``new_clusters`` argument.
