The clusters that you configured in the previous exercise are described in.xml files. It is possible to create new clusters by manually creating the .xml files, however this is not a convenient way to create them.
Nordic Semiconductor provides a dedicated tool called the Matter Cluster Editor that can be used for creating and editing Matter clusters, cluster extensions, and device types in accordance with the Matter Data Model. The tool provides a graphical user interface and can be easily installed, as it is available as one of the applications in nRF Connect for Desktop.
In this exercise, our goal will be to create a new device type called Random Number Generator and a cluster that implements this functionality. The new device type will be added to the OnOff Plug sample that was created in Exercise 1 of this lesson.
Exercise steps
0. Get the base code for this exercise.
In Visual Studio Code, in the WELCOME panel, select Open an existing application, navigate to the GitHub repository for the course, and open the l3/l3_e2 directory. The application should appear under the APPLICATIONS panel.
The base code for this exercise is the solution from the previous exercise, with added instructions for where to input the code snippets from this exercise.
1. Open the Matter Cluster Editor
1.1 Launch nRF Connect for Desktop and go to the Apps tab.
1.2 Install and open the Matter Cluster Editor app.
The following window will appear:
2. Add the Random Number Generator cluster
2.1 Navigate to the CLUSTER tab and fill all the fields with the following information:
- Domain: General
- Name: RandomNumberGenerator
- Code: 0xfff1fc01
- Define: RANDOM_NUMBER_GENERATOR
- Description: A cluster for generating random numbers
For an explanation of the allowed values, such as Code, hover over the field name and the tool tip description will appear on the side.
The selected Domain does not have significant impact on how the cluster works, but allows us to group clusters based on common purpose, which simplifies navigating over the cluster lists, for example using the ZAP Tool. If you would like to create a cluster for measuring some parameter, the suitable domain would be Measurement & Sensing. In case of RandomNumberGenerator the suitable domain is not defined, so the best option is just to select the General domain that groups clusters not belonging to any other specific group.
The Code is 32-bit value, where the most significant 16 bits are the manufacturer code and least significant 16 bits are the cluster id. If you are a manufacturer that has an own code registered, you can use it, but in this exercise the code from test codes range was used – 0xFFF1. The custom cluster id should be a value within 0xFC00-0xFFFE range, so as an example the value 0xFC01 was used in this exercise.
2.2 Navigate to the COMMANDS tab and click on the Add Command button.
Fill the fields with the following information to create a Generate command:
- Name: Generate
- Code: 0xfff10000
- Source: client
- Response:
- Description: Command that triggers random number generation. Additionally it uses arguments that define min and max range of generation.
Code is a 32-bit value, with the most significant 16 bits representing the manufacturer code and the least significant 16 bits representing the command ID. For the cluster in this exercise, you are using an ID reserved for testing: 0xFFF1. The command ID should be a value between 0x0000 and 0x00FF, so you can select a random 0x0000 value in this exercise.
The Source of the command should be set to client, as our Nordic DK runs the server role, and it is the external client device (the Matter controller in particular) that is going to send this command.
Then, click on the Arguments button, and the plus sign that appears to add command arguments.
Fill in the fields with the following information to create two arguments that set the minimum and maximum value of the generated number:
First, fill in the details for the minimum value
- Name: MinValue
- Type: int16s
- Min: -32768
- Max: 32767
Then click on the plus sign to add another Argument and fill in the details for the maximum value
- Name: MaxValue
- Type: int16s
- Min: -32768
- Max: 32767
Click the Save button in the Arguments view and then click Save again in the Command view.
The command will appear in the COMMANDS view, as presented in the following picture:
2.3 Navigate to the ATTRIBUTES tab and click on the Add Attribute button.
Fill the fields with the following information to create a GeneratedNumber attribute:
- Name: GeneratedNumber
- Side: server
- Code: 0xfff10000
- Define: GENERATED_NUMBER
- Type: int16s
- Min: -32768
- Max: 32767
The Code is 32-bit value, where the most significant 16 bits are the manufacturer code and least significant 16 bits are the attribute id. As in case of the cluster, in this exercise the code from test codes range was used – 0xFFF1. The command id should be a value within 0x0000-0x4FFF range, so as an example the value 0x0000 was used in this exercise.
Note
You can spot that the code of that attribute and code of the Generate command is the same. That is coincidence, not a requirement, as in this exercise the first available values from required ranges were used.
The Side of the attribute should be set to server, as the Nordic device runs a server role and keeps the attribute state.
The Type was selected to 16-bit size signed integer and Min, and Max values were set as defined limits for a 16-bit signed integer.
Click the Save button. The attribute will appear in the ATTRIBUTES view, as presented in the following picture:
2.4 Navigate to the EVENTS tab and click on the Add Event button.
Fill the fields with the following information to create a NumberGenerated event:
- Name: NumberGenerated
- Code: 0xfff10000
- Side: server
- Priority: info
- Description: Event is generated once the new number is generated
The Code is 32-bit value, where the most significant 16 bits are the manufacturer code and least significant 16 bits are the event id. As in case of the cluster, in this exercise the code from test codes range was used – 0xFFF1. The command id should be a value within 0x0000-0x00FF range, so as an example the value 0x0000 was used in this exercise.
The Side of the attribute should be set to server, as the Nordic device runs a server role and keeps the attribute state.
The Priority can be set to any available value from the list, as an example the info priority was selected.
Click the Save button. The event will appear in the EVENTS view, as presented in the following picture:
2.5 Navigate to the DEVICE TYPE tab and fill in the fields with the following information to create a Random number generator device type:
- Name: random-number-generator
- Type Name: Random number generator
- Domain: CHIP
- Class: Simple
- Scope: Endpoint
- Profile ID: 0x104
- Device ID: 0xfff10001
- Lock Others: Enabled
The selected Domain, as in case of creating a new cluster, does not have significant impact on how the device type works. In case of this device type, the suitable domain is not defined, so as for the RandomNumberGenerator cluster, the General domain was selected.
The Class should be set to Simple, as the new device type does not represent any Utility functionalities and is not meant to operate on the Dynamic endpoint.
The Scope should be set to Endpoint, as the new device type does not apply to the whole node’s functionality, but to a single feature represented by a single endpoint.
The Profile ID represents Matter stack revision, which is Matter 1.5, so it should be set to 0x105.
The Device ID is 32-bit value, where the most significant 16 bits are the manufacturer code and least significant 16 bits are the device id. As in case of the cluster, in this exercise the code from test codes range was used – 0xFFF1. The device id should be a value within 0x0000-0x4FFF range, so as an example the value 0x0001 was used in this exercise.
Right now, the new device type does not require any clusters to be enabled.
To add this requirement, click on the Add Cluster assignment to device type button.
Input the required “RandomNumberGenerator” cluster into the Cluster field, and enable the switch next to the Server field, to indicate that the cluster uses Server attributes and commands. Then click Save.
2.6 Click the Save to file button in the bar on the left.
Navigate to the src/default_zap directory relative to your sample’s directory, in our case C:\ncs\matt-fund\l3\l3_e2\src\default_zap, and name the file RandomNumberGenerator.xml. Then click Save.
3. Add the Random Number Generator device type using the ZAP Tool
3.1 In Visual Studio Code, in the APPLICATIONS panel, right click on the application and select “Start New Terminal”, select the nRF Connect SDK version and corresponding toolchain version. This will open a terminal in your sample directory.
Run the ZAP Tool using the following command that includes the RandomNumberGenerator.xmlfile describing our new device type and cluster:
west zap-gui -j src/default_zap/zcl.json --clusters ./src/default_zap/RandomNumberGenerator.xmlThe ZAP Tool window should appear.
3.2 Click the + ADD ENDPOINT button and under Device, search for “Random number generator”, select it, and the rest of the fields will fill themselves.
Then select Create to enable the Random number generator device type.
3.3 Make sure that the RandomNumberGenerator cluster is enabled in a Server role, by searching for the RandomNumberGenerator cluster in the search window in the top right:
3.4 Click on the gear icon, and make sure that all attributes, commands, and events are enabled.
3.5 Save the configuration by clicking File->Save on the top bar and exit the application.
3.6 Generate the code based on the .zap file by invoking the following command in the terminal:
west zap-generate --fullAt this point, the new endpoint and all required clusters have been added to your application.
Note
Invoking the west zap-generate command with the --full option results in re-generating the whole Matter data model, which may take dozens of seconds. Please be patient till the process ends.
4. Handle RandomNumberGenerator functionalities in the application code
4.1 Point the build system to the generated files that include the custom cluster, instead of the default ones that include only specified Matter clusters. To do that, modify the CMakeLists.txt file located in the sample’s directory. Add the following code snippet to the CMakeLists.txt file
include(${ZEPHYR_NRF_MODULE_DIR}/samples/matter/common/cmake/zap_helpers.cmake)
ncs_get_zap_parent_dir(ZAP_PARENT_DIR)
#Override zap-generated directory.
get_filename_component(CHIP_APP_ZAP_DIR ${ZAP_PARENT_DIR}/zap-generated REALPATH CACHE)4.2 Then, add the following lines to pass the custom cluster to the Matter data model configuration:
ncs_configure_data_model(
EXTERNAL_CLUSTERS "RANDOM_NUMBER_GENERATOR" # Add EXTERNAL_CLUSTERS flag
)4.3 Define the Init callback for the RandomNumberGenerator cluster.
This implementation must be provided for every cluster handled in the code, even if it is empty.
In the app_task.cpp file at its very bottom, add the following code:
void MatterRandomNumberGeneratorPluginServerInitCallback() {
}4.4 Include the header file that contains the data model callback declarations in the app_task.cpp file:
#include <app-common/zap-generated/callback.h>4.5 Add using namespace entry, near the other similar lines, for the custom cluster to allow for shorter macro usage:
using namespace ::chip::app::Clusters::RandomNumberGenerator;4.6 Now you must define the implementation of a callback that will be automatically called by the data model, once the Generate command from the RandomNumberGenerator cluster is received. The function shell is already defined in the base code for this exercise, as
bool emberAfRandomNumberGeneratorClusterGenerateCallback(chip::app::CommandHandler *commandObj, const chip::app::ConcreteCommandPath &commandPath,
const RandomNumberGenerator::Commands::Generate::DecodableType &commandData) {}4.7 Obtain arguments included in the command that are min and max values for the random number generation.
Add the following two lines
int16_t minValue = commandData.minValue;
int16_t maxValue = commandData.maxValue;4.8 Include the header file that contains the method for generating random numbers:
#include <zephyr/random/random.h>4.9 Add code that generates a random number in a specified range and prints it in the device logs for debugging purposes.
LOG_INF("Generating random number between %d and %d", minValue, maxValue);
int16_t randomNumber = sys_rand16_get() % (maxValue - minValue + 1) + minValue;
LOG_INF("Random number generated: %d", randomNumber);4.10 Set the generated number as a value of the GeneratedNumber attribute and add status to the default response command to inform the client device if the command succeeded or not.
Protocols::InteractionModel::Status status = RandomNumberGenerator::Attributes::GeneratedNumber::Set(commandPath.mEndpointId, randomNumber);
commandObj->AddStatus(commandPath, status);
if (status == Protocols::InteractionModel::Status::Success) {
return true;
}
return false;4.11 Add handling the GenerateNumber attribute value changes.
This can be done in the MatterPostAttributeChangeCallback method that was used in Exercise 1. Modify its existing code, by adding an else if condition that obtains the value that was changed and prints a log with it to ensure that the generated number was really set to the Matter data model:
else if (clusterId == RandomNumberGenerator::Id && attributeId == RandomNumberGenerator::Attributes::GeneratedNumber::Id) {
int16_t generatedNumber = 0;
memcpy(&generatedNumber, value, sizeof(int16_t));
LOG_INF("Cluster RandomNumberGenerator: attribute GeneratedNumber set to %d", generatedNumber);
}5. Build and flash the application to the DK
Build and flash the application to the DK.
6. Commission the Matter device using CHIP Tool.
Commission the Matter device using CHIP Tool, similarly to previous exercises.
6.1 Ensure the Thread Border Router is still running. If not:
6.1.1 Open a new command-line terminal and run the following command to run the OpenThread Border Router:
Replace the /dev/ttyACM0 with the serial port number that is used by your Thread Coprocessor.
sudo docker run -it --rm --privileged --name otbr --network otbr -p 8080:80 \
--sysctl "net.ipv6.conf.all.disable_ipv6=0 net.ipv4.conf.all.forwarding=1 net.ipv6.conf.all.forwarding=1" \
--volume /dev/ttyACM0:/dev/radio nrfconnect/otbr:fbde28a --radio-url spinel+hdlc+uart:///dev/radio?uart-baudrate=1000000Important
If you get an error like “The container name “/otbr” is already in use by container…, run the following commands
sudo docker kill otbr
sudo ip -6 route del "fd11:22::/64" dev otbr0 via "fd11:db8:1::2"
sudo ip link set dev otbr0 down
sudo docker network rm otbr
6.1.2 Open the http://localhost:8080/ address in a web browser to get access to the OpenThread Border Router graphical user interface.
6.1.3 Navigate to the Form tab from the side panel and make sure that all the inserted data is the same as in the following picture. Then press the FORM button to request from the OpenThread Border Router to form a Thread network and become a Thread leader.
6.1.4 Open a new command-line terminal and check the status of the Thread node running inside the Docker:
sudo docker exec -it otbr sh -c "sudo ot-ctl state"The output should be the following:
leader
Done6.2 Ensure CHIP Tool is still running. If not:
6.2.1 Open a new command-line terminal and run the downloaded binary file you obtained in the previous exercise using the following command:
With PC:
./chip-tool_x64 interactive start
With Raspberry Pi:
./chip-tool_arm64 interactive start
6.3 Commission the device to the network.
6.3.1 Make sure that Matter advertising over Bluetooth LE is running.
The following logs should be visible in the device serial port:
I: 730208 [DL]CHIPoBLE advertising started
I: 730212 [DL]NFC Tag emulation startedNote that the Matter advertising over Bluetooth LE is automatically started for the Matter Template sample, but it timeouts after 1 hour. If the advertising timed out, press BUTTON0 on the Matter device to start it again.
6.3.2 Return to the terminal window running the CHIP Tool application.
Start the commissioning process by running the following command and fill the <thread dataset> argument with your Thread dataset that was obtained in Lesson 2 Exercise 1 and stored on your computer. Replace <your_selected_node_id> with a random node ID that has not been used in other exercises, e.g 3. This same number will be used when sending commands to the device via CHIP Tool.
pairing ble-thread <your_selected_node_id> hex:<thread dataset> 20202021 3840As a result, the Matter device and the CHIP Tool application will start printing many verbose messages in the logs that present the commissioning flow. These are especially useful in case of issues with pairing and allow for troubleshooting the problem.
6.1 Ensure CHIP Tool is still running. If not:
6.1.1 Open a new command line terminal and run the downloaded binary file obtained in the previous exercise using the following command:
With PC:
./chip-tool_x64 interactive start
With Raspberry Pi:
./chip-tool_arm64 interactive start
6.2 Commission the device to the network.
6.2.1 Press BUTTON0 on the Matter device to start Matter advertising over Bluetooth LE.
The following logs should be visible in the device serial port:
I: 730208 [DL]CHIPoBLE advertising started
I: 730212 [DL]NFC Tag emulation started6.2.2 Return to the terminal window running the CHIP Tool application.
Run the following command and fill the <wifi_ssid> and <wifi_password> arguments with your Wi-Fi network data.
Replace <your_selected_node_id> with a random node ID that has not been used in other exercises, e.g 3. This same number will be used when sending commands to the device via CHIP Tool.
pairing ble-wifi <your_selected_node_id> <wifi_ssid> <wifi_password> 20202021 3840As a result, the Matter device and the CHIP Tool application will start printing many verbose messages in the logs that present the commissioning flow. These are especially useful in case of issues with pairing and allow for troubleshooting the problem.
7. Test the Random number generator device functionality
7.1 Get the value of the GeneratedNumber attribute from the RandomNumberGenerator cluster.
The CHIP Tool does not support controlling custom clusters and attributes by its name. However, it can be done using the code assigned during cluster creation. For example, for the RandomNumberGenerator cluster, the code is 0xFFF1FC01, and for the GeneratedNumber attribute, the code is 0xFFF10000. Use the following command to learn the required syntax:
any read-by-idThen to read the attribute’s value, use the following command in the CHIP Tool terminal:
any read-by-id 0xFFF1FC01 0xFFF10000 <your_selected_node_id> 2You will see a similar output in the CHIP Tool terminal:
[1770662965.655] [78890:78892] [DMG] Data = 0 (signed),
[1770662965.655] [78890:78892] [DMG] },
[1770662965.655] [78890:78892] [DMG]
[1770662965.655] [78890:78892] [DMG] },
[1770662965.655] [78890:78892] [DMG]
[1770662965.655] [78890:78892] [DMG] ],
[1770662965.655] [78890:78892] [DMG]
[1770662965.655] [78890:78892] [DMG] SuppressResponse = true,
[1770662965.655] [78890:78892] [DMG] InteractionModelRevision = 12
[1770662965.655] [78890:78892] [DMG] }
[1770662965.655] [78890:78892] [TOO] Endpoint: 2 Cluster: 0xFFF1_FC01 Attribute 0xFFF1_0000 DataVersion: 4218421684
[1770662965.655] [78890:78892] [TOO] Don't know how to log attribute valueThe Data = 0 (signed) field presents the attribute’s value, which is set to 0 by default.
7.2 Request the generation of a new number using the Generate command from the RandomNumberGenerator cluster.
Similarly to the attributes and clusters, the command can be sent using its code, which is 0xFFF10000. Additionally, the command arguments can be passed using their indexes and values with a dedicated character describing their data type. Use the following command to learn the required syntax:
any command-by-idThen, invoke the following command to send the Generate command with MinValue set to -10 and MaxValue set to 10:
any command-by-id 0xFFF1FC01 0xFFF10000 '{"0x0": "s:-10", "0x1": "s:10"}' <your_selected_node_id> 2You will see a similar output in the logs from the Matter device:
I: Generating random number between -10 and 10
I: Random number generated: -5
I: Cluster RandomNumberGenerator: attribute GeneratedNumber set to -57.3 Get the value of the GeneratedNumber attribute again to make sure it was changed, by using the following command:
any read-by-id 0xFFF1FC01 0xFFF10000 <your_selected_node_id> 2And you will see the following output in the CHIP Tool terminal:
[1770664264.909] [91192:91194] [DMG] Data = -5 (signed),
[1770664264.909] [91192:91194] [DMG] },
[1770664264.909] [91192:91194] [DMG]
[1770664264.909] [91192:91194] [DMG] },
[1770664264.909] [91192:91194] [DMG]
[1770664264.909] [91192:91194] [DMG] ],
[1770664264.909] [91192:91194] [DMG]
[1770664264.909] [91192:91194] [DMG] SuppressResponse = true,
[1770664264.909] [91192:91194] [DMG] InteractionModelRevision = 12
[1770664264.909] [91192:91194] [DMG] }
[1770664264.910] [91192:91194] [TOO] Endpoint: 2 Cluster: 0xFFF1_FC01 Attribute 0xFFF1_0000 DataVersion: 3312041728
[1770664264.910] [91192:91194] [TOO] Don't know how to log attribute valueThe Data = -5 (signed) presents the attribute’s value, which was modified and is consistent with the value visible in the Matter device’s logs.
7.4 Repeat steps 7.2 and 7.3 a couple of times and observe that the random values are generated. You can also try to change the MinValue and MaxValue to adjust the range of values used.
