samples: matter: Added custom events to the Matter MS sample

Added custom events to NordicDevKit and Basic Information
clusters:
* UserButtonChanged emitted on UserButton state change
* RandomNumberChanged emitted on RandomNumber change

Updated the documentation to contain steps for the events.

Additionally fixed ids for attributes and commands that were not
compatible with the spec and fixed few minor issues in
the documentation.

Signed-off-by: Kamil Kasperczyk <kamil.kasperczyk@nordicsemi.no>

Author: kkasperczyk-no

doc/nrf/protocols/matter/getting_started/custom_clusters.rst

@@ -108,13 +108,13 @@ See the description of each element in the following tabs:
             <code>0xFFF1FC01</code>
             <define>MY_NEW_CLUSTER</define>
             <description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>
-            <attribute side="server" code="0x00" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
-            <command source="client" code="0x02" name="MyCommand" response="MyCommandResponse" optional="false">
+            <attribute side="server" code="0xFFF10000" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
+            <command source="client" code="0xFFF10000" name="MyCommand" response="MyCommandResponse" optional="false">
                <description>Command that takes two uint8 arguments and returns their sum.</description>
                <arg name="arg1" type="int8u"/>
                <arg name="arg2" type="int8u"/>
             </command>
-            <event source="server" code="0x01" name="MyEvent" optional="false">
+            <event source="server" code="0xFFF10000" name="MyEvent" priority="info" optional="false">
                <description>Event that is generated by the server.</description>
                <arg name="arg1" type="int8u"/>
             </event>
@@ -153,6 +153,8 @@ See the description of each element in the following tabs:
          * ``source`` - Specifies whether the event originates from the client or server.
          * ``code`` - A unique identifier for the event within the cluster.
          * ``name`` - The name of the event.
+         * ``priority`` - The priority of the event.
+                          The valid values are ``debug``, ``info``, and ``critical``.
          * ``optional`` - Indicates whether the event is optional.
          * ``description`` - A brief description of the event's purpose and functionality.
          * ``arg`` - An argument for the event, specifying its name and type.
@@ -169,7 +171,7 @@ See the description of each element in the following tabs:
                <arg name="arg1" type="int8u"/>
                <arg name="arg2" type="int8u"/>
             </command>
-            <event source="server" code="0x04" name="ExtendedEvent" optional="false">
+            <event source="server" code="0x04" name="ExtendedEvent" priority="info" optional="false">
                <description>Event that is generated by the server.</description>
                <arg name="arg1" type="int8u"/>
             </event>
@@ -297,13 +299,13 @@ You can use the following template for the :file:`MyCluster.xml` file:
          <code>0xFFF1FC01</code>
          <define>MY_NEW_CLUSTER</define>
          <description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>
-         <attribute side="server" code="0x00" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
-         <command source="client" code="0x02" name="MyCommand" optional="false">
+         <attribute side="server" code="0xFFF10000" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
+         <command source="client" code="0xFFF10000" name="MyCommand" optional="false">
             <description>Command that takes two uint8 arguments and returns their sum.</description>
             <arg name="arg1" type="int8u"/>
             <arg name="arg2" type="int8u"/>
          </command>
-         <event source="server" code="0x01" name="MyEvent" optional="false">
+         <event source="server" code="0xFFF10000" name="MyEvent" priority="info" optional="false">
             <description>Event that is generated by the server.</description>
             <arg name="arg1" type="int8u"/>
          </event>
@@ -315,7 +317,7 @@ You can use the following template for the :file:`MyCluster.xml` file:
             <arg name="arg1" type="int8u"/>
             <arg name="arg2" type="int8u"/>
          </command>
-         <event source="server" code="0x04" name="ExtendedEvent" optional="false">
+         <event source="server" code="0x04" name="ExtendedEvent" priority="info" optional="false">
             <description>Event that is generated by the server.</description>
             <arg name="arg1" type="int8u"/>
          </event>
@@ -361,7 +363,7 @@ This guide focuses on the :ref:`ug_matter_gs_tools_matter_west_commands_zap_tool
 
    .. code-block::
 
-      west zap-gui -j ./zcl.json ./MyCluster.xml
+      west zap-gui -j ./zcl.json --clusters ./MyCluster.xml
 
    This example command copies the original :file:`<default Matter SDK location>/src/app/zap-templates/zcl/zcl.json` file, adds the :file:`MyCluster.xml` cluster, and saves the new :file:`zcl.json` file in the sample directory.
    The newly generated :file:`zcl.json` file is used as an input to the ZAP tool.

samples/matter/manufacturer_specific/README.rst

@@ -37,32 +37,33 @@ The development kits for this sample offer the following IPv6 network support fo
 
 Overview
 ********
+
+The sample starts the Bluetooth® LE advertising automatically and prepares the Matter device for commissioning into a Matter-enabled IPv6 network.
+
 .. tabs::
 
    .. group-tab:: nRF52, nRF53 and nRF70 DKs
 
-      The sample starts the Bluetooth® LE advertising automatically and prepares the Matter device for commissioning into a Matter-enabled IPv6 network.
       The sample uses the **LED 1** to show the state of the connection.
       You can press **Button 1** to start the factory reset when needed.
       **Button 2** is used to set the state of the ``NordicDevkit`` cluster's attribute, ``UserButton``.
-      Matter command ``SetLED`` is used to control the state of ``UserLED``.
-      It takes one argument - the action to be performed (``0`` to turn the LED off, ``1`` to turn it on, ``2`` to toggle the state).
       **LED 2** reflects the state of the ``UserLED``.
-      The ``NordicDevkit`` cluster introduces a writable ``DevKitName`` attribute, of string type as well.
-      The sample additionally extends the ``Basic Information`` cluster with a ``RandomNumber`` attribute and ``GenerateRandom`` command that updates the ``RandomNumber`` with a random value.
 
    .. group-tab:: nRF54 DKs
 
-      The sample starts the Bluetooth LE advertising automatically and prepares the Matter device for commissioning into a Matter-enabled IPv6 network.
       The sample uses the **LED 0** to show the state of the connection.
       You can press **Button 0** to start the factory reset when needed.
       **Button 1** is used to set the state of the ``NordicDevkit`` cluster's attribute, ``UserButton``.
-      Matter command ``SetLED`` is used to control the state of ``UserLED``.
-      It takes one argument - the action to be performed (``0`` to turn the LED off, ``1`` to turn it on, ``2`` to toggle the state).
       **LED 1** reflects the state of the ``UserLED``.
-      The ``NordicDevkit`` cluster introduces a writable ``DevKitName`` attribute, of string type as well.
-      The sample additionally extends the ``Basic Information`` cluster with a ``RandomNumber`` attribute and ``GenerateRandom`` command that updates the ``RandomNumber`` with a random value.
 
+The Matter command ``SetLED`` is used to control the state of ``UserLED``.
+It takes one argument - the action to be performed (``0`` to turn the LED off, ``1`` to turn it on, ``2`` to toggle the state).
+The ``UserButtonChanged`` event is generated when the ``UserButton`` attribute is changed.
+
+The ``NordicDevkit`` cluster introduces a writable ``DevKitName`` attribute, of string type as well.
+The sample additionally extends the ``Basic Information`` cluster with a ``RandomNumber`` attribute and ``GenerateRandom`` command that updates the ``RandomNumber`` with a random value.
+The ``RandomNumberChanged`` event is generated when the ``RandomNumber`` attribute is changed.
+The ``RandomNumber`` attribute value is not persistent and it is generated on each application's boot.
 
 Custom manufacturer-specific cluster
 ====================================
@@ -132,7 +133,7 @@ User interface
          .. include:: /includes/matter_sample_button.txt
 
       Button 2:
-         Sets the state of ``UserButton`` attribute in the ``NordicDevkit`` cluster.
+         Sets the state of ``UserButton`` attribute in the ``NordicDevkit`` cluster to ``true`` on press and ``false`` on release.
 
       .. include:: /includes/matter_segger_usb.txt
 
@@ -148,7 +149,7 @@ User interface
          .. include:: /includes/matter_sample_button.txt
 
       Button 1:
-         Sets the state of ``UserButton`` attribute in the ``NordicDevkit`` cluster.
+         Sets the state of ``UserButton`` attribute in the ``NordicDevkit`` cluster to ``true`` on press and ``false`` on release.
 
       .. include:: /includes/matter_segger_usb.txt
 
@@ -234,24 +235,24 @@ To test ``NordicDevkit`` cluster's attributes and commands, complete the followi
    .. parsed-literal::
       :class: highlight
 
-      any read-by-id read-by-id 0xFFF1FC01 *attribute-id* 1 1
+      any read-by-id 0xFFF1FC01 *attribute-id* 1 1
 
-   * *attribute-id* is the attribute's ID, equal to ``1`` for ``DevKitName``, ``2`` for ``UserLED`` and ``3`` for ``UserButton`` attributes for the ``NordicDevkit`` cluster in this sample.
+   * *attribute-id* is the attribute's ID, equal to ``0xFFF10000`` for ``DevKitName``, ``0xFFF10001`` for ``UserLED`` and ``0xFFF10002`` for ``UserButton`` attributes for the ``NordicDevkit`` cluster in this sample.
 #. Verify that all attributes have been read correctly and are equal to the default values defined in cluster's configuration.
 #. Write the ``DevkitName`` attribute:
 
    .. parsed-literal::
       :class: highlight
 
-      any write-by-id 0xFFF1FC01 1 "NewName" 1 1
+      any write-by-id 0xFFF1FC01 0xFFF10000 "NewName" 1 1
 
 #. Read the ``DevkitName`` attribute again to check if it has changed.
 #. Send the ``SetLED`` command to the device to control the LED state:
 
    .. parsed-literal::
       :class: highlight
 
-      any command-by-id 0xFFF1FC01 0 '{ "0x0": "u:*action*" }' 1 1
+      any command-by-id 0xFFF1FC01 0xFFF10000 '{ "0x0": "u:*action*" }' 1 1
 
    * *action* is the action that should be performed on LED attribute: ``0`` to turn the LED off, ``1`` to turn it on, ``2`` to toggle the state.
 
@@ -261,9 +262,16 @@ To test ``NordicDevkit`` cluster's attributes and commands, complete the followi
    .. parsed-literal::
       :class: highlight
 
-      any subscribe-by-id 0xFFF1FC01 3 0 120 1 1
+      any subscribe-by-id 0xFFF1FC01 0xFFF10002 0 120 1 1
 
 #. Press the button assigned to the ``UserButton`` and check if the attribute state is updated in the chip-tool.
+#. Read the ``UserButtonChanged`` event to check that events were generated on ``UserButton`` attribute changes.
+
+   .. parsed-literal::
+      :class: highlight
+
+      any read-event-by-id 0xFFF1FC01 0xFFF10000 1 1
+
 #. Read the ``Basic Information`` cluster's ``RandomNumber`` attribute:
 
    .. parsed-literal::
@@ -279,6 +287,13 @@ To test ``NordicDevkit`` cluster's attributes and commands, complete the followi
       any command-by-id 0x0028 0 '{}' 1 0
 
 #. Verify that the random value has been generated and the attribute value is updated.
+#. Read the ``Basic Information`` cluster's ``RandomNumberChanged`` event to check that events were generated on ``RandomNumber`` attribute changes.
+
+   .. parsed-literal::
+      :class: highlight
+
+      any read-event-by-id 0x0028 0x4 1 0
+
 #. Reboot the device, restart the chip-tool, and check if the attributes are persisting after joining the network.
 
 Upgrading the device firmware

samples/matter/manufacturer_specific/src/app_task.cpp

@@ -14,11 +14,13 @@
 
 #include <app-common/zap-generated/attributes/Accessors.h>
 
+#include <app/EventLogging.h>
+#include <app/util/attribute-storage.h>
 #include <setup_payload/OnboardingCodesUtil.h>
 
-#include <zephyr/random/random.h>
-#include <zephyr/logging/log.h>
 #include <dk_buttons_and_leds.h>
+#include <zephyr/logging/log.h>
+#include <zephyr/random/random.h>
 
 LOG_MODULE_DECLARE(app, CONFIG_CHIP_APP_LOG_LEVEL);
 
@@ -35,7 +37,7 @@ constexpr EndpointId kNordicDevKitEndpointId = 1;
 
 static void ButtonEventHandler(Nrf::ButtonState /* unused */, Nrf::ButtonMask has_changed)
 {
-        /* Handle button press */
+	/* Handle button press */
 	if (ConnectivityMgrImpl().IsIPv6NetworkProvisioned() && ConnectivityMgrImpl().IsIPv6NetworkEnabled() &&
 	    BUTTON2_MASK & has_changed) {
 		AppTask::Instance().UpdateNordicDevkitClusterState();
@@ -50,19 +52,29 @@ void AppTask::UpdateNordicDevkitClusterState()
 
 		dk_read_buttons(&button_state, nullptr);
 
-		status = Clusters::NordicDevKit::Attributes::UserLED::Set(kNordicDevKitEndpointId,
-								Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).GetState());
+		status = Clusters::NordicDevKit::Attributes::UserLED::Set(
+			kNordicDevKitEndpointId, Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).GetState());
 
 		if (status != Protocols::InteractionModel::Status::Success) {
 			LOG_ERR("Updating NordicDevkit cluster failed: %x", to_underlying(status));
 		}
 
 		status = Clusters::NordicDevKit::Attributes::UserButton::Set(kNordicDevKitEndpointId,
-										    BUTTON2_MASK & button_state);
+									     BUTTON2_MASK & button_state);
 
 		if (status != Protocols::InteractionModel::Status::Success) {
 			LOG_ERR("Updating NordicDevkit cluster failed: %x", to_underlying(status));
 		}
+
+		for (auto endpoint : EnabledEndpointsWithServerCluster(Clusters::NordicDevKit::Id)) {
+			/* If NordicDevKit cluster is implemented on this endpoint */
+			Clusters::NordicDevKit::Events::UserButtonChanged::Type event;
+			EventNumber eventNumber;
+
+			if (CHIP_NO_ERROR != LogEvent(event, endpoint, eventNumber)) {
+				ChipLogError(Zcl, "Failed to emit UserButtonChanged event");
+			}
+		}
 	});
 }
 
@@ -77,6 +89,16 @@ void AppTask::UpdateBasicInformationClusterState()
 		if (status != Protocols::InteractionModel::Status::Success) {
 			LOG_ERR("Updating Basic information cluster failed: %x", to_underlying(status));
 		}
+
+		for (auto endpoint : EnabledEndpointsWithServerCluster(Clusters::BasicInformation::Id)) {
+			/* If Basic cluster is implemented on this endpoint */
+			Clusters::BasicInformation::Events::RandomNumberChanged::Type event;
+			EventNumber eventNumber;
+
+			if (CHIP_NO_ERROR != LogEvent(event, endpoint, eventNumber)) {
+				ChipLogError(Zcl, "Failed to emit RandomNumberChanged event");
+			}
+		}
 	});
 }
 

samples/matter/manufacturer_specific/src/default_zap/NordicDevKitCluster.xml

@@ -12,19 +12,25 @@
     <code>0xFFF1FC01</code>
     <define>NORDIC_DEV_KIT_CLUSTER</define>
     <description>The NordicDevKit cluster showcases a cluster manufacturer extensions</description>
-    <command source="client" code="0x00" name="SetLED" optional="false">
+    <command source="client" code="0xFFF10000" name="SetLED" optional="false">
       <description>Change LED state</description>
       <arg name="Action" type="LEDActionEnum" optional="false"/>
     </command>
-    <attribute side="server" code="0x01" define="DEV_KIT_NAME" type="char_string" writable="true" optional="false" default="Nordic Development Kit">DevKitName</attribute>
-    <attribute side="server" code="0x02" define="USER_LED" type="boolean" length="0" writable="false" reportable="false" isNullable="false" default="false" optional="false" apiMaturity="NaN">UserLED<description/><access op="read" role="view"/></attribute>
-    <attribute side="server" code="0x03" define="USER_BUTTON" type="boolean" length="0" writable="false" reportable="false" isNullable="false" default="false" optional="false" apiMaturity="NaN">UserButton<description/><access op="read" role="view"/></attribute>
+    <attribute side="server" code="0xFFF10000" define="DEV_KIT_NAME" type="char_string" writable="true" optional="false" default="Nordic Development Kit">DevKitName</attribute>
+    <attribute side="server" code="0xFFF10001" define="USER_LED" type="boolean" length="0" writable="false" reportable="false" isNullable="false" default="false" optional="false" apiMaturity="NaN">UserLED<description/><access op="read" role="view"/></attribute>
+    <attribute side="server" code="0xFFF10002" define="USER_BUTTON" type="boolean" length="0" writable="false" reportable="false" isNullable="false" default="false" optional="false" apiMaturity="NaN">UserButton<description/><access op="read" role="view"/></attribute>
+    <event side="server" code="0xFFF10000" name="UserButtonChanged" priority="info" optional="false">
+      <description>The UserButtonChanged event SHALL be emitted by a Node as soon as the User Button is pressed or released.</description>
+    </event>
   </cluster>
   <clusterExtension code="0x0028">
     <command source="client" code="0x00" name="GenerateRandom" optional="false">
       <description>Generate random number</description>
     </command>
     <attribute side="server" code="0x17" define="RANDOM_NUMBER" type="int16u" writable="true" optional="false" default="0">RandomNumber</attribute>
+    <event side="server" code="0x4" name="RandomNumberChanged" priority="info" optional="true">
+      <description>The RandomNumberChanged event SHALL be emitted by a Node as soon as the RandomNumber attribute is changed.</description>
+    </event>
   </clusterExtension>
   <deviceType>
     <name>nordic-dev-kit</name>