The nRF Connect SDK provides multiple Matter samples that implement functionalities of selected Matter device types. However, for practical reasons, it is not possible to present all available Matter device types as samples.

In this exercise, you will use the Matter Template sample in the nRF Connect SDK, as a basis for creating our own Matter device that uses a device type not available as a sample in the nRF Connect SDK. Our goal will be to create a Matter On/Off Plug device.

The Matter Template sample implements only functionalities related to the Endpoint 0, and does not include implementations specific to any application use case.

Exercise steps

0. Get the GitHub repository for the course.

Clone the GitHub repository for this course.

Avoid storing the repo in locations with long paths, as the build system might fail on some operating systems (Windows) if the application path is too long.

1. Get the base code for this exercise.

1.1 In the nRF Connect extension in VS Code, in the WELCOME panel, select Open an existing application, navigate to the GitHub repository for the course that you cloned in the previous step, and open the l3/l3_e1 directory. The application should appear under the APPLICATIONS panel.

This application is a copy of the Matter Template sample, with added instructions for where to input the code snippets from this exercise.

1.2 Review the content of the files present in the src directory. As described in Lesson 2, the Matter sample uses the nRF Connect Matter API. Specifically:

• app_task.cpp file contains methods that initialize the Matter server and board components, sets the default handler for Matter events and starts the main loop. This base implementation allows you to commission the device to a Matter fabric and interact with the Nordic DK using the following elements:
  • Button 0 – Short click enables advertising over Bluetooth LE, long press over 6 seconds results in a factory reset of the device.
  • LED 0 – Visualizes the state of the device in different ways of blinking. Short blinks mean that the device is not commissioned, fast blinking signals that the device is in the commissioning process, and solid on means that the device has joined the Matter fabric.
• template.zap located in the default_zap directory contains only the mandatory configuration of clusters required for the Endpoint 0 (Root Endpoint).
• zap-generated directory located in the default_zap directory contains source and header files generated based on template.zap file. These files configure clusters and provide default handlers for them.

2. Add the On/Off Plug endpoint using the ZAP Tool

2.1 Start the nRF Connect toolchain in a terminal window.

In Visual Studio Code, in the APPLICATIONS window, right click on our application, l3_e1, and select “Start New Terminal”.

Select the nRF Connect SDK version you are using:

And the corresponding toolchain version:

And a terminal will open in the sample directory.

2.2 Run the ZAP Tool using the following command:

west zap-gui

west zap-gui

The command will automatically download and run the appropriate ZAP Tool version. After completing the installation, the ZAP tool’s Matter Cluster Configurator window appears.

You can see the endpoints listed in the side panel on the left side of the window. Currently, there is only one endpoint with index 0, which is the Root Endpoint.

2.3 In the ZAP tool, click + ADD ENDPOINT.

2.4 In the Create New Endpoint menu, create a new endpoint that represents the on/off plug device type:

Confirm the selection by selecting the CREATE button, and the new endpoint is going to appear in the side panel.

2.5 Let’s verify that all clusters required by the Matter specification are enabled.

By default, after selecting the Matter device type, all required clusters, attributes, and commands should be enabled.

Click on the first row in the window, General, to expand it.

You can also check the configuration, for example, see the details of the On/Off cluster by clicking on the gear icon next to it. The default configuration has all attributes enabled, but in fact, not all attributes are mandatory. Navigate to the Features tab and see that the Lighting feature is enabled, while our use case is not related to lighting.

The tool claims that the lighting feature is mandatory, but the Matter specification states it is optional if the OffOnly feature is disabled, otherwise not supported. Disable this feature and confirm your selection. Ignore the application warning

As a result, the majority of attributes and a few commands will be disabled.

2.6 Save the configuration by clicking File->Save on the top bar and exit the application.

2.7 Generate the code based on the .zap file by invoking the following command in the VS Code terminal:

west zap-generate

west zap-generate

At this point, the new endpoint and all required clusters have been added to your application.

3. Handle the On/Off plug functionalities in the application code
The Matter Data model has been updated, and it can be properly controlled by the Matter controller, but your application should control the On/Off plug, so some actions need to be performed as a result of the attribute changes. In a real device, you could turn the switch on or off to enable power to the outlet, but in a sample application, you can just emulate the outlet state using LED1 on the DK. The outlet could also have a physical button that allows us to manually force the outlet state, and you can emulate this functionality using BUTTON 1 of the DK.

3.1 Handle changes of the OnOff state attribute.

You need to get information that the OnOff state attribute value was changed in the data model, for example, as a result of controller interaction. Then you will be able to change LED1’s state accordingly.

To do that, you must implement the MatterPostAttributeChangeCallback method, which is a callback called by the Matter data model once some attribute’s value has changed.

All the modified code will apply to the app_task.cpp file in the src directory.

3.1.1 Add the following two lines under the other using namespace lines to be able to access the cluster’s methods and values using shorter code lines:

using namespace ::chip::app::Clusters;
using namespace ::chip::app::Clusters::OnOff;

using namespace ::chip::app::Clusters;
using namespace ::chip::app::Clusters::OnOff;

3.1.2 At the bottom of the file, the MatterPostAttributeChangeCallbackmethod is implemented.

Add the following lines to get information about the cluster ID and attribute ID from an attributePath argument:

ClusterId clusterId = attributePath.mClusterId;
AttributeId attributeId = attributePath.mAttributeId;

ClusterId clusterId = attributePath.mClusterId;
AttributeId attributeId = attributePath.mAttributeId;

3.1.3 In the same function, add a check that verifies whether the modified attribute is the one you are interested in, as the MatterPostAttributeChangeCallback method is called on any attribute change. Change the state of LED1 on the DK, depending on the state of an OnOff attribute. Additionally, let’s add a log line for debugging.

Add the following code snippet:

if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) {
	LOG_INF("Cluster OnOff: attribute OnOff set to %" PRIu8 "", *value);
	Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).Set(*value);
}

if (clusterId == OnOff::Id && attributeId == OnOff::Attributes::OnOff::Id) {
	LOG_INF("Cluster OnOff: attribute OnOff set to %" PRIu8 "", *value);
	Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).Set(*value);
}

3.2 Add button handling to change the LED state in reaction to manual state changes.

All the modified code applies to the app_task.cpp file.

3.2.1 In the ButtonEventHandler()function, check if the callback is called in reaction to the BUTTON1 change, as the callback is generic and the library calls it for all buttons. As theButtonEventHandler() function is called directly from an interrupt handler, it is good practice to not perform long operations in it, but schedule them to the application queue, for example using thePostTask()method.

Add the following code snippet:

if ((DK_BTN2_MSK & hasChanged) & state) {
	Nrf::PostTask([] {
			Nrf::GetBoard()
			.GetLED(Nrf::DeviceLeds::LED2)
			.Set(!Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).GetState());

            /* STEP 3.3.3 - Update the attribute state using the Set() method */
	});
}

if ((DK_BTN2_MSK & hasChanged) & state) {
	Nrf::PostTask([] {
			Nrf::GetBoard()
			.GetLED(Nrf::DeviceLeds::LED2)
			.Set(!Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).GetState());

            /* STEP 3.3.3 - Update the attribute state using the Set() method */
	});
}

3.2.2 Pass your custom handler to the Nrf::GetBoard().Init() method that is called in AppTask::Init()method.

To handle a new button in the application, you need to pass the custom button handler to the Nrf::GetBoard().Init() method that is called in theAppTask::Init()method. For documentation on the handler API, see the nrf/samples/matter/common/src/board/board.h file. You will find that the handler has to be of type button_handler_t, which is declared in nrf/include/dk_buttons_and_leds.h file.

Add the following code snippet:

if (!Nrf::GetBoard().Init(ButtonEventHandler)) {
	LOG_ERR("User interface initialization failed.");
	return CHIP_ERROR_INCORRECT_STATE;
}

if (!Nrf::GetBoard().Init(ButtonEventHandler)) {
	LOG_ERR("User interface initialization failed.");
	return CHIP_ERROR_INCORRECT_STATE;
}

3.3 Update the Matter Data Model in reaction to the button press.

So far, the implementation updates the local state of LED1, but this information is not passed to the Matter Data Model, so an attribute state may become inconsistent with the physical device’s state.

3.3.1 Add the following line under the other #include lines:

#include <app-common/zap-generated/attributes/Accessors.h>

#include <app-common/zap-generated/attributes/Accessors.h>

3.3.2 Define a helper const value that will be used to propagate the id of the OnOffPlug endpoint to the methods that are interacting with the Matter Data Model.

constexpr EndpointId kOnOffPlugEndpointId = 1;

constexpr EndpointId kOnOffPlugEndpointId = 1;

3.3.3 Update the OnOff attribute state using the Set() method from the Accessor.h file.

One is not permitted to modify the Matter stack and data model context from an application thread as this may lead to undefined behavior. Rather, you can do this using the Matter thread.

This can be done using theSystemLayer().ScheduleLambda() method.

Add the following code snippet in the ButtonEventHandler() function.

SystemLayer().ScheduleLambda([] {
	Protocols::InteractionModel::Status status = Clusters::OnOff::Attributes::OnOff::Set(
		kOnOffPlugEndpointId, Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).GetState());

	if (status != Protocols::InteractionModel::Status::Success) {
		LOG_ERR("Updating on/off cluster failed: %x", to_underlying(status));
	}
});

SystemLayer().ScheduleLambda([] {
	Protocols::InteractionModel::Status status = Clusters::OnOff::Attributes::OnOff::Set(
		kOnOffPlugEndpointId, Nrf::GetBoard().GetLED(Nrf::DeviceLeds::LED2).GetState());

	if (status != Protocols::InteractionModel::Status::Success) {
		LOG_ERR("Updating on/off cluster failed: %x", to_underlying(status));
	}
});

4. Build and flash the application to the DK

Build and flash the application to the DK, similarly to Lesson 2, Exercise 1.

5. Commission the OnOff Plug device using CHIP Tool

Commission the OnOff Plug device using CHIP Tool, similarly to Lesson 2 Exercise 1.

• Matter over Thread
• Matter over Wi-FI

5.1 Ensure the Thread Border Router is still running. If not:

5.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=1000000

Copy

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=1000000

Terminal command

Important

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

5.1.2 Open the http://localhost:8080/ address in a web browser to get access to the OpenThread Border Router graphical user interface.

5.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.

5.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"

Copy

sudo docker exec -it otbr sh -c "sudo ot-ctl state"

Terminal command

The output should be the following:

leader
Done

Terminal

5.2 Ensure CHIP Tool is still running. If not:

5.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

5.3 Commission the device to the network.

5.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 started

Terminal

Note 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.

5.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 2. 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 3840

Copy

pairing ble-thread <your_selected_node_id> hex:<thread dataset> 20202021 3840

Terminal command

As a result, the Matter door lock 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.

5.1 Ensure CHIP Tool is still running. If not:

5.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

5.2 Commission the device to the network.

5.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 started

Terminal

5.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 2. 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 3840

Copy

pairing ble-wifi <your_selected_node_id> <wifi_ssid> <wifi_password> 20202021 3840

Terminal command

As a result, the Matter door lock 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. Control the state of the OnOff Plug

6.1 Let’s take a look at the available commands for the OnOff cluster by invoking the following command in the CHIP Tool’s terminal:

onoff

onoff

The following output will show you a list of available commands:

   onoff command_name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Commands:                                                                           |
  +-------------------------------------------------------------------------------------+
  | * command-by-id                                                                     |
  | * off                                                                               |
  | * on                                                                                |
  | * toggle                                                                            |
  | * off-with-effect                                                                   |
  | * on-with-recall-global-scene                                                       |
  | * on-with-timed-off                                                                 |
  | * read-by-id                                                                        |
  |   - Read attributes from this cluster; allows wildcard endpoint and attribute.      |
  | * read                                                                              |
  | * write-by-id                                                                       |
  | * force-write                                                                       |
  | * write                                                                             |
  | * subscribe-by-id                                                                   |
  |   - Subscribe to attributes from this cluster; allows wildcard endpoint and attri...|
  | * subscribe                                                                         |
  | * read-event-by-id                                                                  |
  |   - Read events from this cluster; allows wildcard endpoint and event.              |
  | * subscribe-event-by-id                                                             |
  |   - Subscribe to events from this cluster; allows wildcard endpoint and event.      |
  +-------------------------------------------------------------------------------------+

6.2 Check the available attributes to be read for the OnOff cluster, by invoking the following command in the CHIP Tool’s terminal:

onoff read

onoff read

The following output will show you a list of available attributes:

   onoff read attribute-name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Attributes:                                                                         |
  +-------------------------------------------------------------------------------------+
  | * on-off                                                                            |
  | * global-scene-control                                                              |
  | * on-time                                                                           |
  | * off-wait-time                                                                     |
  | * start-up-on-off                                                                   |
  | * generated-command-list                                                            |
  | * accepted-command-list                                                             |
  | * attribute-list                                                                    |
  | * feature-map                                                                       |
  | * cluster-revision                                                                  |
  +-------------------------------------------------------------------------------------+

6.3 Read out the OnOff attribute state, by invoking the following command in the CHIPTool’s terminal:

onoff read on-off <your_selected_node_id> 1

onoff read on-off <your_selected_node_id> 1

You should see a similar output like below in the CHIP Tool terminal, as by default the OnOff Plug state is off (LED1 is off):

[1770350882.137] [23287:23289] [TOO] Endpoint: 1 Cluster: 0x0000_0006 Attribute 0x0000_0000 DataVersion: 4111306799
[1770350882.137] [23287:23289] [TOO]   OnOff: FALSE

6.4 Turn on the OnOff Plug, by invoking the following command in the CHIP Tool terminal:

onoff on <your_selected_node_id> 1

onoff on <your_selected_node_id> 1

You will observe that LED1 changed state to on. Also, you will see a similar output in the logs from the Matter device:

I: 267590 [ZCL]Toggle ep1 on/off from state 0 to 1
I: Cluster OnOff: attribute OnOff set to 1

6.5 Read the state of the OnOff attribute again to check that it was changed, by invoking the following command in the CHIP Tool’s terminal:

onoff read on-off <your_selected_node_id> 1

onoff read on-off <your_selected_node_id> 1

This time you will see a similar output in the CHIP Tool terminal, as the OnOff Plug state is on (LED1 is on):

[1770351060.542] [23287:23289] [TOO] Endpoint: 1 Cluster: 0x0000_0006 Attribute 0x0000_0000 DataVersion: 4111306804
[1770351060.542] [23287:23289] [TOO]   OnOff: TRUE

6.6 Click BUTTON1 and observe that the state of LED1 changed to off.

6.7 Read the state of the OnOff attribute again to check that it was changed, by invoking the following command in the CHIP Tool’s terminal:

onoff read on-off <your_selected_node_id> 1

onoff read on-off <your_selected_node_id> 1

This time you will see a similar output in the CHIP Tool terminal, as the OnOff Plug state is off (LED1 is off):

[1770351094.016] [23287:23289] [TOO] Endpoint: 1 Cluster: 0x0000_0006 Attribute 0x0000_0000 DataVersion: 4111306806
[1770351094.016] [23287:23289] [TOO]   OnOff: FALSE

You can subscribe to the OnOff attribute to not have to read the state from the controller manually, but to be automatically notified if the state changes.

First learn the command usage, by invoking the following commands:

onoff subscribe

onoff subscribe

The following output will show you a list of available attributes:

Usage:
   onoff subscribe attribute-name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Attributes:                                                                         |
  +-------------------------------------------------------------------------------------+
  | * on-off                                                                            |
  | * global-scene-control                                                              |
  | * on-time                                                                           |
  | * off-wait-time                                                                     |
  | * start-up-on-off                                                                   |
  | * generated-command-list                                                            |
  | * accepted-command-list                                                             |
  | * attribute-list                                                                    |
  | * feature-map                                                                       |
  | * cluster-revision                                                                  |
  +-------------------------------------------------------------------------------------+

And, by invoking the following command to learn subscription parameters:

onoff subscribe on-off

onoff subscribe on-off

The following output will show you a list of required arguments:

Usage:
   onoff subscribe on-off min-interval max-interval destination-id endpoint-ids

6.8 Subscribe to the OnOff attribute value, by invoking the following command:

onoff subscribe on-off 0 30 <your_selected_node_id> 1

onoff subscribe on-off 0 30 <your_selected_node_id> 1

You will see a similar output in the CHIP Tool terminal:

[1770351174.845] [23287:23289] [DMG] Subscription established in 217ms with SubscriptionID = 0xd60a035c MinInterval = 0s MaxInterval = 30s Peer = 01:0000000000000001

6.9 Click BUTTON1 and verify that notifications about the OnOff state are received. You will see a similar output in CHIP Tool terminal after every BUTTON1 click:

[1770351187.923] [23287:23289] [TOO] Endpoint: 1 Cluster: 0x0000_0006 Attribute 0x0000_0000 DataVersion: 4111306807
[1770351187.923] [23287:23289] [TOO]   OnOff: FALSE