Skip to content

Commit b0fe451

Browse files
maciejbaczmanskimaciejbaczmanski
committed
samples: matter: add cluster extension
Add cluster extension to manufacturer-specific sample and update custom cluster guide. Additionaly rename `NordicDevKitCluster` to `NordicDevKit` Signed-off-by: Maciej Baczmanski <[email protected]>
1 parent f90952e commit b0fe451

File tree

23 files changed

+658
-255
lines changed

23 files changed

+658
-255
lines changed

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

Lines changed: 141 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,10 @@ See the :file:`<default Matter SDK location>/src/app/zap-templates/zcl/data-mode
4646

4747
The XML file consists of the following elements:
4848

49+
* ``<cluster>`` - Cluster definition.
50+
* ``<clusterExtension>`` - Cluster extension definition.
4951
* ``<enum>`` - Enumerated type definition.
5052
* ``<struct>`` - Structure definition.
51-
* ``<cluster>`` - Cluster definition.
5253
* ``<deviceType>`` - Device type definition.
5354

5455
See the description of each element in the following tabs:
@@ -57,7 +58,7 @@ See the description of each element in the following tabs:
5758

5859
.. tab:: ``<cluster>``
5960

60-
``<cluster>`` defines the cluster and consist of the following attributes:
61+
``<cluster>`` defines the cluster and consist of the following child elements:
6162

6263
* ``<domain>`` - The domain to which the cluster belongs.
6364
* ``<name>`` - The name of the cluster.
@@ -71,7 +72,7 @@ See the description of each element in the following tabs:
7172
* ``define`` - The C++ preprocessor macro name for the attribute, typically in uppercase with words separated by underscores.
7273
* ``type`` - The data type of the attribute.
7374
* ``entryType`` - The data type of array elements if the attribute is an array.
74-
* ``writable`` - Indicates whether the attribute can be written to.
75+
* ``writable`` - Indicates whether the attribute can be written by a Matter controller.
7576
* ``default`` - The default value of the attribute.
7677
* ``optional`` - Indicates whether the attribute is optional.
7778
* ``name`` - The name of the attribute.
@@ -102,26 +103,81 @@ See the description of each element in the following tabs:
102103
103104
<?xml version="1.0"?>
104105
<cluster>
105-
<domain>General</domain>
106-
<name>MyNewCluster</name>
107-
<code>0xFFF1FC01</code>
108-
<define>MY_NEW_CLUSTER</define>
109-
<description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>
110-
<attribute side="server" code="0x00" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
111-
<command source="client" code="0x02" name="MyCommand" response="MyCommandResponse" optional="false">
112-
<description>Command that takes two uint8 arguments and returns their sum.</description>
113-
<arg name="arg1" type="int8u"/>
114-
<arg name="arg2" type="int8u"/>
115-
</command>
116-
<event source="server" code="0x01" name="MyEvent" optional="false">
117-
<description>Event that is generated by the server.</description>
118-
<arg name="arg1" type="int8u"/>
119-
</event>
106+
<domain>General</domain>
107+
<name>MyNewCluster</name>
108+
<code>0xFFF1FC01</code>
109+
<define>MY_NEW_CLUSTER</define>
110+
<description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>
111+
<attribute side="server" code="0x00" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
112+
<command source="client" code="0x02" name="MyCommand" response="MyCommandResponse" optional="false">
113+
<description>Command that takes two uint8 arguments and returns their sum.</description>
114+
<arg name="arg1" type="int8u"/>
115+
<arg name="arg2" type="int8u"/>
116+
</command>
117+
<event source="server" code="0x01" name="MyEvent" optional="false">
118+
<description>Event that is generated by the server.</description>
119+
<arg name="arg1" type="int8u"/>
120+
</event>
120121
</cluster>
121122
123+
.. tab:: ``<cluster>``
124+
125+
``<clusterExtension>`` defines the extension of an existing cluster and consist of the following attributes and child elements:
126+
127+
* ``code`` - A 32-bit identifier for the existing cluster, that will be extended.
128+
* ``<attribute>`` - An attribute definition within the cluster.
129+
130+
* ``side`` - Specifies whether the attribute is on the client or server side.
131+
* ``code`` - A unique identifier for the attribute within the cluster.
132+
* ``define`` - The C++ preprocessor macro name for the attribute, typically in uppercase with words separated by underscores.
133+
* ``type`` - The data type of the attribute.
134+
* ``entryType`` - The data type of array elements if the attribute is an array.
135+
* ``writable`` - Indicates whether the attribute can be written by a Matter controller.
136+
* ``default`` - The default value of the attribute.
137+
* ``optional`` - Indicates whether the attribute is optional.
138+
* ``name`` - The name of the attribute.
139+
140+
* ``<command>`` - A command definition within the cluster.
141+
142+
* ``source`` - Specifies whether the command originates from the client or server.
143+
* ``code`` - A unique identifier for the command within the cluster.
144+
* ``name`` - The name of the command.
145+
* ``optional`` - Indicates whether the command is optional.
146+
* ``disableDefaultResponse`` - Indicates whether the default response to the command is disabled.
147+
* ``response`` - The name of the response command, if any.
148+
* ``description`` - A brief description of the command's purpose and functionality.
149+
* ``arg`` - An argument for the command, specifying its name and type.
150+
151+
* ``<event>`` - An event definition within the cluster.
152+
153+
* ``source`` - Specifies whether the event originates from the client or server.
154+
* ``code`` - A unique identifier for the event within the cluster.
155+
* ``name`` - The name of the event.
156+
* ``optional`` - Indicates whether the event is optional.
157+
* ``description`` - A brief description of the event's purpose and functionality.
158+
* ``arg`` - An argument for the event, specifying its name and type.
159+
160+
For example, the following XML code extends a ``Basic Information`` cluster with one attribute, one command, and one event:
161+
162+
.. code-block:: xml
163+
164+
<?xml version="1.0"?>
165+
<clusterExtension code="0x0028">
166+
<attribute side="server" code="0x17" define="EXTENDED_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">ExtendedAttribute</attribute>
167+
<command source="client" code="0x00" name="ExtendedCommand" response="ExtendedCommandResponse" optional="false">
168+
<description>Command that takes two uint8 arguments and returns their sum.</description>
169+
<arg name="arg1" type="int8u"/>
170+
<arg name="arg2" type="int8u"/>
171+
</command>
172+
<event source="server" code="0x04" name="ExtendedEvent" optional="false">
173+
<description>Event that is generated by the server.</description>
174+
<arg name="arg1" type="int8u"/>
175+
</event>
176+
</clusterExtension>
177+
122178
.. tab:: ``<enum>``
123179

124-
``<enum>`` elements define the enumerated types that can be used in the cluster and consist of the following attributes:
180+
``<enum>`` elements define the enumerated types that can be used in the cluster and consist of the following attributes and child elements:
125181

126182
* ``name`` - The unique name of the enumerated type.
127183
* ``<cluster code>`` - The cluster code(s) that the enumerated type is associated with.
@@ -138,14 +194,14 @@ See the description of each element in the following tabs:
138194
.. code-block:: xml
139195
140196
<enum name="MyNewEnum" type="uint8">
141-
<cluster code="0xFFF1FC01" />
142-
<item name="EnumValue1" value="0" />
143-
<item name="EnumValue2" value="1" />
197+
<cluster code="0xFFF1FC01" />
198+
<item name="EnumValue1" value="0" />
199+
<item name="EnumValue2" value="1" />
144200
</enum>
145201
146202
.. tab:: ``<struct>``
147203

148-
``<struct>`` elements define the structure types that can be used in the cluster and consist of the following attributes:
204+
``<struct>`` elements define the structure types that can be used in the cluster and consist of the following attributes and child elements:
149205

150206
* ``name`` - The unique name of the structure.
151207
* ``isFabricScoped`` - Indicates if the structure is fabric-scoped.
@@ -176,7 +232,7 @@ See the description of each element in the following tabs:
176232
177233
.. tab:: ``<deviceType>``
178234

179-
``<deviceType>`` elements define the device types that can be used in the cluster and consist of the following attributes:
235+
``<deviceType>`` elements define the device types that can be used in the cluster and consist of the following child elements:
180236

181237
* ``<name>`` - The unique name of the device.
182238
* ``<domain>`` - The domain to which the device belongs.
@@ -211,18 +267,18 @@ See the description of each element in the following tabs:
211267
.. code-block:: xml
212268
213269
<deviceType>
214-
<name>my-new-device</name>
215-
<domain>CHIP</domain>
216-
<typeName>My new device</typeName>
217-
<profileId editable="false">0x0FFF</profileId>
218-
<deviceId editable="false">0x001</deviceId>
219-
<class>Simple</class>
220-
<scope>Endpoint</scope>
221-
<clusters lockOthers="true">
222-
<include cluster="MyNewCluster" client="true" server="true" clientLocked="false" serverLocked="false"/>
223-
<requireAttribute>MY_ATTRIBUTE</requireAttribute>
270+
<name>my-new-device</name>
271+
<domain>CHIP</domain>
272+
<typeName>My new device</typeName>
273+
<profileId editable="false">0x0FFF</profileId>
274+
<deviceId editable="false">0x001</deviceId>
275+
<class>Simple</class>
276+
<scope>Endpoint</scope>
277+
<clusters lockOthers="true">
278+
<include cluster="MyNewCluster" client="true" server="true" clientLocked="false" serverLocked="false"/>
279+
<requireAttribute>MY_ATTRIBUTE</requireAttribute>
224280
<requireCommand>MyCommand</requireCommand>
225-
</clusters>
281+
</clusters>
226282
</deviceType>
227283
228284
.. note::
@@ -235,44 +291,56 @@ You can use the following template for the :file:`MyCluster.xml` file:
235291
236292
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
237293
<configurator>
238-
<cluster>
239-
<domain>General</domain>
240-
<name>MyNewCluster</name>
241-
<code>0xFFF1FC01</code>
242-
<define>MY_NEW_CLUSTER</define>
243-
<description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>
244-
<attribute side="server" code="0x00" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
245-
<command source="client" code="0x02" name="MyCommand" optional="false">
246-
<description>Command that takes two uint8 arguments and returns their sum.</description>
247-
<arg name="arg1" type="int8u"/>
248-
<arg name="arg2" type="int8u"/>
249-
</command>
250-
<event source="server" code="0x01" name="MyEvent" optional="false">
251-
<description>Event that is generated by the server.</description>
252-
<arg name="arg1" type="int8u"/>
253-
</event>
254-
</cluster>
255-
<enum name="MyNewEnum" type="int8u">
256-
<cluster code="0xFFF1FC01" />
257-
<item name="EnumValue1" value="0" />
258-
<item name="EnumValue2" value="1" />
259-
</enum>
260-
<struct name="MyStruct" isFabricScoped="true">
261-
<cluster code="0xFFF1FC01"/>
262-
<item fieldId="1" name="Data" type="octet_string" length="128" isFabricSensitive="true"/>
263-
</struct>
264-
<deviceType>
265-
<name>my-new-device</name>
266-
<domain>CHIP</domain>
267-
<typeName>My new device</typeName>
268-
<profileId editable="false">0x0FFF</profileId>
269-
<deviceId editable="false">0x001</deviceId>
270-
<class>Simple</class>
271-
<scope>Endpoint</scope>
272-
<clusters lockOthers="true">
273-
<include cluster="MyNewCluster" client="true" server="true" clientLocked="false" serverLocked="false"/>
274-
</clusters>
275-
</deviceType>
294+
<cluster>
295+
<domain>General</domain>
296+
<name>MyNewCluster</name>
297+
<code>0xFFF1FC01</code>
298+
<define>MY_NEW_CLUSTER</define>
299+
<description>The MyNewCluster cluster showcases a cluster manufacturer extensions</description>
300+
<attribute side="server" code="0x00" define="MY_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">MyAttribute</attribute>
301+
<command source="client" code="0x02" name="MyCommand" optional="false">
302+
<description>Command that takes two uint8 arguments and returns their sum.</description>
303+
<arg name="arg1" type="int8u"/>
304+
<arg name="arg2" type="int8u"/>
305+
</command>
306+
<event source="server" code="0x01" name="MyEvent" optional="false">
307+
<description>Event that is generated by the server.</description>
308+
<arg name="arg1" type="int8u"/>
309+
</event>
310+
</cluster>
311+
<clusterExtension code="0x0028">
312+
<attribute side="server" code="0x17" define="EXTENDED_ATTRIBUTE" type="boolean" writable="true" default="false" optional="false">ExtendedAttribute</attribute>
313+
<command source="client" code="0x00" name="ExtendedCommand" response="ExtendedCommandResponse" optional="false">
314+
<description>Command that takes two uint8 arguments and returns their sum.</description>
315+
<arg name="arg1" type="int8u"/>
316+
<arg name="arg2" type="int8u"/>
317+
</command>
318+
<event source="server" code="0x04" name="ExtendedEvent" optional="false">
319+
<description>Event that is generated by the server.</description>
320+
<arg name="arg1" type="int8u"/>
321+
</event>
322+
</clusterExtension>
323+
<enum name="MyNewEnum" type="int8u">
324+
<cluster code="0xFFF1FC01" />
325+
<item name="EnumValue1" value="0" />
326+
<item name="EnumValue2" value="1" />
327+
</enum>
328+
<struct name="MyStruct" isFabricScoped="true">
329+
<cluster code="0xFFF1FC01"/>
330+
<item fieldId="1" name="Data" type="octet_string" length="128" isFabricSensitive="true"/>
331+
</struct>
332+
<deviceType>
333+
<name>my-new-device</name>
334+
<domain>CHIP</domain>
335+
<typeName>My new device</typeName>
336+
<profileId editable="false">0x0FFF</profileId>
337+
<deviceId editable="false">0x001</deviceId>
338+
<class>Simple</class>
339+
<scope>Endpoint</scope>
340+
<clusters lockOthers="true">
341+
<include cluster="MyNewCluster" client="true" server="true" clientLocked="false" serverLocked="false"/>
342+
</clusters>
343+
</deviceType>
276344
</configurator>
277345
278346

‎samples/matter/manufacturer_specific/README.rst‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,8 @@ Overview
4848
Matter command ``SetLED`` is used to control the state of ``UserLED``.
4949
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).
5050
**LED 2** reflects the state of the ``UserLED``.
51-
``NordicDevkit`` cluster additionally introduces a writable ``DevKitName`` attribute, of string type.
51+
The ``NordicDevkit`` cluster introduces a writable ``DevKitName`` attribute, of string type as well.
52+
The sample additionally extends the ``Basic Information`` cluster with a ``RandomNumber`` attribute and ``GenerateRandom`` command that updates the ``RandomNumber`` with a random value.
5253

5354
.. group-tab:: nRF54 DKs
5455

@@ -59,7 +60,8 @@ Overview
5960
Matter command ``SetLED`` is used to control the state of ``UserLED``.
6061
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).
6162
**LED 1** reflects the state of the ``UserLED``.
62-
``NordicDevkit`` cluster additionally introduces a writable ``DevKitName`` attribute, of string type.
63+
The ``NordicDevkit`` cluster introduces a writable ``DevKitName`` attribute, of string type as well.
64+
The sample additionally extends the ``Basic Information`` cluster with a ``RandomNumber`` attribute and ``GenerateRandom`` command that updates the ``RandomNumber`` with a random value.
6365

6466

6567
Custom manufacturer-specific cluster
@@ -227,7 +229,7 @@ To test ``NordicDevkit`` cluster's attributes and commands, complete the followi
227229
228230
chip-tool interactive start
229231
230-
#. Read the attributes by index:
232+
#. Read the ``NordicDevkit`` cluster's attributes by index:
231233

232234
.. parsed-literal::
233235
:class: highlight
@@ -261,8 +263,23 @@ To test ``NordicDevkit`` cluster's attributes and commands, complete the followi
261263
262264
any subscribe-by-id 0xFFF1FC01 3 0 120 1 1
263265
264-
#. Press the button assigned to the ``UserButton``, check if the attribute state is updated in the chip-tool.
265-
#. Reboot the device, restart chip-tool and check if the attributes are persisting after joining the network.
266+
#. Press the button assigned to the ``UserButton`` and check if the attribute state is updated in the chip-tool.
267+
#. Read the ``Basic Information`` cluster's ``RandomNumber`` attribute:
268+
269+
.. parsed-literal::
270+
:class: highlight
271+
272+
any read-by-id 0x0028 0x17 1 0
273+
274+
#. Send the ``GenerateRandom`` command to the device to update the ``RandomNumber`` attribute:
275+
276+
.. parsed-literal::
277+
:class: highlight
278+
279+
any command-by-id 0x0028 0 '{}' 1 0
280+
281+
#. Verify that the random value has been generated and the attribute value is updated.
282+
#. Reboot the device, restart the chip-tool, and check if the attributes are persisting after joining the network.
266283

267284
Upgrading the device firmware
268285
=============================

0 commit comments

Comments
 (0)