Matter over Thread with NRF52


Nordic Semiconductor is a key player in the development of Bluetooth Low Energy semiconductors. In their NRF Connect SDK , they include several examples for Matter.  This protocol is a collaborative effort among the three major home automation giants: Amazon, Apple and Google. Together, they aim to promote the development of innovative and interoperable products. Matter can run over WiFi and Thread. In this articule, we present a step by step guide of Matter over Thread with NRF52.

This pioneering technology holds the promise of significantly enhancing the flexibility of the connected-home market. Thus enabling the creation of new products, regardless the manufacturer of the connected-home controller.

To start with this protocol and all Its possibilities, we get the Nordic’s Matter over Thread example Light Bulb. Ccertainly allowing us to deep into the fundamentals of Matter over Thread protocol and its topologies.

In A Blue Thing In The Cloud, we are experts in the development of IoT and BLE. So, we are developing, from the beginning, devices including Matter connectivity. We want to share with you our experience. And that is why we wrote this guide. To help you in the evaluation of this technology for the projects you could have in mind.

Matter Fundamentals

Matter Is a Connected Home over IP (CHIP) project created by the three major connected-home giants. With the objective of unify the application layer for the connected-home communications. The protocol ensures compatibility across diverse physical layer protocols. Especially on WiFi, Thread, and Ethernet, resulting in a fully interoperable application layer.

Matter over Thread with NRF52

A Matter network will always have the following agents:

  • Matter device. The device which Is receiving the matter commands and executes a physical action. In a connected home context, it could be smart light bulbs, thermostats, or security systems.
  • Matter controller. It Is the device which collects the Instructions and sends It to the different matter devices. In a connected home, it could be a Voice Assistant, like Alexa.
  • Border router. This element forwards the messages from the matter controller to the matter devices. It takes the Matter Controller’s application layer command, packs It Into the desired physical layer protocol (Thread or Wi-Fi), and sends It to the corresponding Matter Device.

These three agents interact to each other by different protocols, depending on the current discovery stage. For example, to add a new Matter device, the Matter controller starts a BLE or an IP discovery. Then, if a new Matter device is found, it commissions it to be part of the Matter network. After this process, the Matter device communicates directly with the Border Router by WiFi or Thread. The typical topology on a Matter network consists of a Matter controller. Able to control many Matter devices, using a Thread or WiFi border router to forward the messages. Usually, the Matter controller and the router are connected by Ethernet. But in some scenarios, they are both on the same device.

Examples of network architectures

Matter over Thread with NRF52

On the other hand, a topology where the matter controller and the border router on a WiFi network is more popular on the development stages, because it allows to test easierly the possibility of having the matter controller and the border router on different devices.

Matter over Thread with NRF52

Running the Light Bulb example

The Nordic’s light bulb example is one of the best examples to simulate a Matter device on NRF52840 Development Kit. This is the example we use in this guide for Matter over Thread with NRF52.

Set up

The proposed set up is components are:

  • Firstly, an NRF52840DK with the matter’s Light Bulb example flashed on it, for the purpose of acting as a Matter device
  • Then, a Matter controller running on an Ubuntu Virtual Machine which afterwards will establish the BLE commissioning to the a Matter device and record the Matter commands.
  • Finally, an OpenThread Border Router running on a Docker container on the Ubuntu Virtual Machine. This Border Router should be able to communicate with the Matter Controller through a Wi-Fi access point and set up Thread connections with the Matter Device. For this purpose, we flash a nrf52840 dongle with the sample “coprocessor”.

Step 1. Matter over Thread with NRF52. Flashing the example

Previously, we need to build and flash the Matter’s Light Bulb example on the nrf52840dk, and the Matter’s Coprocessor on the nrf52840 dongle, using the Visual Studio Code’s extension NRF Connect SDK. If you are new to this tool, we strongly recommend to take a look to our guide Getting started with NRF7002 | A Blue Thing In The Cloud, to learn about the tools to build and run Zephyr examples on Nordic development kits.

Remark the Matter’s Light Bulb example has three building configuration options: we propose to build it with prj.conf, disabling the debug options, so information about the commissioning process or the reception of Matter commands will be printed on the Serial port by Log messages.

Matter over Thread with NRF52

Step 2. Matter over Thread with NRF52. Set up the Virtual Machine

Flash both devices with their corresponding firmware, the next step is setting up the Virtual machine which will allocate the Matter Controller and the Border Router.

Step by step:

  • Firstly, install VirtualBox. Installation link.
  • Then, install Ubuntu’s 22.04.2 Virtual Machine. Installation link:
  • At this point, create a new virtual machine with the downloaded Ubuntu image and configure it to use 2 CPUs and a virtual disk of 100 GB.
  • Finally, configure the virtual machine to detect the nrf52840 dongle to run the Border Router. Connect the nrf52740 to a USB port on your PC and then, add It on the “Device menu” of your virtual machine.
Linux VM

Configure the Bluetooth peripheral.

The Matter Controller needs to have access to the Bluetooth driver to execute Commissioning Process, and, since the Matter Controller will be executed from the Virtual Machine, the configuration of the Bluetooth driver on it is compulsory. To use the Bluetooth driver on the virtual machine, follow the steps of this tutorial:

  • Configure the WiFi settings. Since the Border Router and the Matter Controller will be connected through the Wi-Fi access point, it is essential to have access to it from the Virtual machine. By default, the virtual machine configuration connects to an Ethernet interface. To avoid it, with the Virtual Machine turned off, click on the “Configuration menu” and introduce the following settings to the 2nd adaptor:

– Enable network adaptor

– Connected to: bridge adaptor

– Name: <your wifi adaptor name>

– Promiscious mode: Denied

– Cable connected

Then, with the Virtual machine running, disconnect the Ethernet network on the Linux configuration panel.

Linux VM configuration

Now the Virtual Machine is able to recognize all the necessary peripherals to run The Matter Controller and the Border Router.

Step 3. Matter over Thread with NRF52.Configure the Border Router

NRF Connect SDK does not provide a complete Thread Border Router solution, for that reason, the recommendation is to use OpenThread Border Router (OTBR) for development purposes. In brief, OTBR, the border router released by Google, is an open-source Border Router implementation that you can set up your Virtual Machine using Docker.

So, the first step should be to installing docker and create an otbr container to run the Border Router. Open the terminal and follow these steps.

  • Commands to install and execute Docker:
sudo apt update && sudo apt install sudo systemctl start Docker

    • Create an IP-v6 Docker Container

sudo docker network create –ipv6 –subnet fd11:db8:1::/64 -o otbr

    • Add docker to a new group of user.

sudo groupadd -f docker sudo usermod -aG docker $USER newgrp docker groups

    • Create the OTBR docker container

docker pull nrfconnect/otbr:9185bda

This way, the OTBR docker container is created for anytime you wish to run the Border Router. Now, to execute the Border Router functionalities, its time to run the docker container, using the nrf52840 dongle to give it the connectivity options.

  • Check the dongle’s name (ttyACM0 by default)

grep -i ‘tty’ /var/log/dmesg

    • Run the docker container, adding the dongle as a radio device.

sudo modprobe ip6table_filter   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:9185bda –radio-url spinel+hdlc+uart:///dev/radio?uart-baudrate=1000000  

Note: Its Important to stop the execution of the docker container every time you wish to turn off the virtual machine.

Running OTBR

Now the OTBR container is running, you should be able to access to its user interface by searching on a web browser localhost:8080. To finish the configuration of the border router, on its user interface, go to the Forms menu and click the Form button.

OTBR screenshot

Then, open another terminal window and add t to the docker container, introducing the following commands and substituting the highlighted identifier by the on-mesh prefix shown on the localhost form page.

sudo ip -6 route add fd11:22::/64 dev otbr0 via fd11:db8:1::2   sudo docker exec -it otbr sh -c “sudo service otbr-agent status”   sudo docker exec -it otbr sh -c “sudo ot-ctl state”  

These commands should show the OTBR state. If the process has been done successfully, then, the OTBR should be running as leader. If it is running as child, is likely the border router is trying to connect to the ethernet interface instead of the Wi-Fi. To fix it, connect to the correct network and reboot the docker container if it is necessary.

Step 4. Matter over Thread with NRF52. Install CHIP to run the Matter Controller

CHIP Tool for Linux or macOS is the default implementation of the Matter controller role, recommended for the nRF Connect platform. Running the Border Router on a separate Docker container, while CHIP is running on the Linux virtual machine, will simulate both terminals are on separate devices.

The CHIP Tool software repository can be found here.

To set up the CHIP tool you should follow these steps.

  • Generate SSH keys on your Github account. The SSH keys will be used to authenticate you while using the CHIP tool. To generate them and add them to your Github account, first:
  • Download Git Bash for Linux.

ssh keygen -t ed25519 -C ssh add ~/.ssh/id_ed25519

  • Add the generated SSH keys to your Github account.

  • Install CHIP Tool’s Linux dependencies and the UI builds:

sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \ libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev \ python3-pip unzip libgirepository1.0-dev libcairo2-dev libreadline-dev   sudo apt-get install libsdl2-dev  

  • Clone the CHIP Tool project:

git clone

  • Move into the sdk-connectedhomeip and check the available tags, and checkout the valid one. It is important to work with the CHIP Tool tag corresponding to the nRF Connect SDK version used to flash the Matter Device (for example, if we used the nRF Connect SDK v2.3.0 version, we would need to check out the CHIP Tool tag v2.3.0), otherwise, we could find authentication incompatibilities when establishing the commissioning with the matter devices.

cd sdk-connectedhomeip   git tag   git checkout tags/<your nRF Connect SDK version>

  • Continue with the CHIP Tool building and execution by running the following commands:

git submodule update –init source scripts/ gn gen out/host ninja -C out/host ninja -C out/host check

Finally, the Matter controller software is correctly installed and ready to be used.

Step 5. Matter over Thread with NRF52. Test the Matter Example

Once the Border Router and the Matter Controller are configured, the next step Is running the Chip Tool application to implement the Matter Controller role, making possible to test the communication with our Matter Device.

Firstly, make sure the matter device is correctly powered, and open its Serial Port (baud rate:  flashed and 115200 bps). Then, go back to the virtual machine and run the matter controller application, located on  the sdk-connectedhomeip/out/host.

cd sdk-connectedhomeip/out/host   ./chip-tool

Commisioning steps

The first time that you use the Matter device, you would need to do the BLE commissioning steps. The first one is getting the OTBR Operational Dataset, which Is modified in every docker session, which can be obtained by running this command:

sudo docker exec -it otbr sh -c “sudo ot-ctl dataset active -x”  

At this instant, run the following command to start the BLE commissioning, where:

    • Node-Id Is a number used by the Matter Controller to Identify the Matter Device.

    • Operational dataset Is the hexadecimal number got from the OTBR.

    • Pin code Is the pin code from the Matter Device. It is prompted on the nrf52840dk Serial port every time the board is re-started.

    • Discriminator Is the discriminator from the matter device. As the pin code, it is also prompted on the Matter Device Serial port.

./chip-tool pairing ble-thread <node_id> hex:<operational_dataset> <pin_code> <discriminator>   (Example of command) ./chip-tool pairing ble-thread 19 hex:0e08000000000001000035060004001fffe00708fd7d63f2550f28820c0402a0f7f8051000112233445566778899aabbccddeeff030e4f70656e54687265616444656d6f0410445f2b5ca6f2a93a55ce570a70efeecb000300000f0208111111112222222201021234 20202021 3840    

When the commissioning process has finished, the nrf52840dk LED1 stops blinking and turns on. This means the commissioning stage has been completed successfully and the Matter Device is connected to the Border Router, ready to execute Matter commands sent by the Matter Controller.

Running the Matter Commands

Certainly, the CHIP Tool provides a bunch of Matter commands to send to the Matter Devices. You can see the whole list of commands just by executing ./chip-tool

To test if the Matter Device Light Bulb example is running fine, we can try the onoff toggle command, which should toggle LED 2 on the nrf52840dk Matter Device.

./chip-tool onoff toggle <node_id> <endpoint_id>

Where the node_Id parameter Is the node Id on the Matter Controller during the commissioning procedure, the endpoint_Id parameter Is set to 1 on the Light Bulb’s example configuration.

For example, you can change the brightness of the LED 2 on the Matter Device by sending the desired level by a levelcontrol CHIP Tool command.

./chip-tool levelcontrol move-to-level <level> <transition_time> <option_mask> <option_override> <node_id> <endpoint_id>

For instance, sending this command will make LED 1 to bright on a level between 0 and 254. The command parameters are:

    • Level: a number between 0 and 254 related to the raise of the blinds.

    • Transition_time: transition time to achieve the specified level. For instance, use 0 to do It as soon as possible.

    • Option_mask: It Is used to add additional options. Generally, set it to 0

    • Option_override. Generally, set it to 0

    • Node_Id. Obviously, the Matter Device’s node Id specified previously on the commissioning stage.

    • Endpoint_Id. Evidently, the Matter Device’s endpoint. To run the test firmware, set it specifically to 1.

For instance, an example of chip-tool matter commands:

./chip-tool onoff toggle 19 1   ./chip-tool levelcontrol move-to-level 125 0 0 0 19 1

Step 6. Matter over Thread with NRF52. Create your own Matter Device application

Finally, now you have the tools to run a Matter Controller and a Border Router, its time to develop your own for your Matter Device.

At this point, we propose take the Light Bulb example as a starting point and try to give it new functionalities according to your objectives (using IP commissioning instead of BLE or give it brand new functionality other than regulating the brightness of a lamp).

Step 7. Contact us for talking about your experience with Matter

We now that Matter is a promisiing technology, therefore we are working on it from the early beginning. We know that there are not a lot of engineers experts in Matter, but we are one of them!

On the other hand, in addition to robust and well tested libraries, as Nordic Design Partners, you can be sure that we are always updated about its technology, being able to bring you the most appropriate solution to your project.

A Blue Thing In The Cloud. Nordic Design Partner.

Additionally, we also have specialized software for code analysing, so we are able to detect bugs and defects on your firmware. So, even though you could use this guide for doing a first working prototype.  So, it will be always a good idea to get a survey from professionals.  Being sure that your everything will run as expected, and without failures.

With customers in Europe, Asia anc cd North America, after all, we design around 20 new products per year. Therefore, you can be sure that we have already faced most of the challenges you could find. So we can help you design the new products you have in mind.

We look forward to contributing to your success.