In this project tutorial, I will show how I made my matter smart lock using the nRF52840DK board. I will use Thread for implementing my Matter device. Matter supports WiFi and Thread. Thread is more power efficient than WiFi and ideal for battery-operated matter devices like Smart Lock. For this reason, I have chosen nRF52840DK for my project because this board supports Thread. I will explain complete step-by-step instructions so that any beginner can follow this project tutorial to make one by himself.
First, I will test with the matter light bulb project provided with nRF Connect SDK. Then I will move to the lock sample for implementing my Smart Lock project. Finally, I will connect my custom hardware with the nRF board for completing the lock project.
If you are here, I believe you already know the matter. If you still need more information about Matter Smart Home please have a look at this blog titled: Peeking Under the Hood of Your Matter Smart Home.
To get started with matter visit: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/protocols/matter/getting_started/index.html.
So, Let's get started.
Before starting, watch the short video below. A detailed video is added at the end.
Installing nRF Connect SDK to Ubuntu PCFor developing Matter firmware for the nRF microcontroller we need to use nRF Connect SDK. Though we can directly download and install nRF Connect SDK, I found it convenient to install through nRF Connect for Desktop. You can manage all your nRF tools from nRF Connect for Desktop.
I downloaded nRF Connect for Desktop AppImage from the following link for my Linux PC: https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop/Download#infotabs
Then, I run the AppImage from the terminal using the following command:
./nrfconnect-4.2.1-x86_64.appimage
After running the nRF Connect for Desktop I installed the Toolchain Manager and Programmer app with other apps. These two tools are mandatory for developing the firmware.
Using Toolchain Manager I downloaded the latest version of nRF Connect SDK with VS Code. Now, I can directly open the nRF SDK through the VS Code from the toolchain manager.
By opening the VS Code I found it already installed with the necessary extension packs that are required for developing firmware using nRF Connect SDK.
Making the Thread Border RouterA Thread network requires a Border Router to connect to other networks. A Thread Border Router connects a Thread network to other IP-based networks, such as Wi-Fi or Ethernet. Amazon Echo Smart Speakers (Fourth Generation), Apple HomePod Mini, and Google Nest Hub (2nd Gen.) are some commercially available Smart Home Hubs that have built-in Border routers. But we can make a Border router by ourselves. For making a Border router you will require the following hardware:
- A Raspberry Pi 3B or higher
- A Micro SD Card (8GB or Higher)
- A Raspberry Pi power supply
- A Raspberry Pi compatible IEEE 802.15.4 transceiver (I am using Nordic nRF52840 Dongle)
OpenThread released by Google is an open-source implementation of the Thread® networking protocol. OpenThread's implementation of a Border Router is called OpenThread Border Router (OTBR). OTBR is a Thread Certified Component on the Raspberry Pi 3B with a Nordic nRF52840 RCP (Radio Co-Processor).
Step 1: Installing OS to Raspberry Pi
It is simple to set up a fresh Raspberry Pi device with the rpi-imager
tool by following the instructions on raspberrypi.org. It is convenient to log in to the Raspberry Pi with SSH, you can find instructions here.
Step 2: Building the firmware for the nRF52840 Dongle
To work with Raspberry Pi as a OpenThread Full Thread Device (FTD) we need to build the OpenThread FTD example for the nRF52840 platform and upload it to nRF52840 Dongle. I used my Ubuntu PC for downloading the source and building and uploading the firmware to the dongle.
I cloned and installed OpenThread from the Ubuntu Terminal. The script/bootstrap
commands make sure the toolchain is installed and the environment is properly configured:
mkdir -p ~/src
cd ~/src
git clone --recursive https://github.com/openthread/openthread.git
cd openthread
./script/bootstrap
See
my terminal below for farther clarification:
After successful running of the above command and passing couple of minutes the system is ready to build OpenThread FTD for the nRF52840 boards.
We need to build the OpenThread nRF52840 example with Joiner and native USB functionality. A device uses the Joiner role to be securely authenticated and commissioned onto a Thread network. Native USB enables the use of USB CDC ACM as a serial transport between the nRF52840 and the host.
I run the following command for downloading the source. I again run the script/bootstrap
commands for installing any missing package:
cd ~/src
git clone --recursive https://github.com/openthread/ot-nrf528xx.git
cd ot-nrf528xx
./script/bootstrap
./script/build nrf52840 USB_trans -DOT_BOOTLOADER=USB
My
terminal:
After a successful build, the elf files can be found in <path-to-ot-nrf528xx>/build/bin/*.
See my terminal:
For uploading to nRF Dongle we need to convert them to hex using arm-none-eabi-objcopy:
arm-none-eabi-objcopy -O ihex build/bin/ot-rcp ot-rcp.hex
The
ot-rcp.hex file is now available to ot-nrf528xx directory. See the screenshot below: (I will provide the hex file to the code section so that you can directly burn it to the nRF dongle. In that case you can omit step 2).
Step 3: Uploading the firmware to the nRF52840 Dongle
The.hex file is ready to upload the nRF Dongle. To do so, I connected the nRF52840 Dongle to a USB port of my PC pressing the Reset button of the dongle.
Then I run the following command to run the nRF Connect for Desktop.
./nrfconnect-4.2.1-x86_64.appimage
I opened the Programmer app from the nRF Desktop and add the ot-rcp.hex file by clicking the Add file option of the Programmer app.
Then I selected the nRF device from the SELECT DEVICE option at top right corner.
Finally, I clicked on Write button and the program was successfully uploaded to the nRF52840 Dongle. It is now ready to plug with the Raspberry pi to work as IEEE 802.15.4 transceiver.
Step 4: Installing the OTBR tool to Raspberry Pi
After preparing the Thread radio it is the right time to install the OTBR tool to Raspberry Pi. I used the following command to install the tool to my Raspberry Pi 4B.
git clone https://github.com/openthread/ot-br-posix.git --depth 1
cd ot-br-posix
./script/bootstrap
INFRA_IF_NAME=wlan0 ./script/setup
The Border router was successfully installed to my Pi. We can check either the OTBR is successfully installed or not using the following command:
sudo service otbr-agent status
I found the service is active and running. Then I tried to run the web dashboard of the Border router but it was not loading. I checked either the web-service is running by the following command:
sudo service otbr-web status
I noticed that the web service is not running. So, I run the following command from the terminal of the Pi to install otbr-web service.
WEB_GUI=1 ./script/bootstrap
INFRA_IF_NAME=wlan0 WEB_GUI=1 ./script/setup
After running the above command I checked it again and I got the positive response.
This time the web dashboard of the Border router was visible from the browser.
My Border router is working perfectly. Now, I will make my Matter device.
For making the Matter device I like to use nRF matter sample provided with the nRF Connect SDK. I opened the nRF SDK with VS Code from the Toolchain Manager app.
Then from the nRF Connect extension, I clicked on Open an existing application and opened the matter light_bulb example.
From the APPLICATIONS tab, I clicked on Create new build configuration, chose my target Board (nrf52840dk_nrf52840), and finally clicked on the Build configuration button.
The project was built successfully. The result can be observed from the terminal of VS Code.
After building the project successfully I connected my nRF52840DK board to my PC using a USB cable and clicked on Flash and I got the following error.
To solve the problem I downloaded and installed the JLink driver to my PC. The JLink driver can be downloaded from the link below: https://www.segger.com/downloads/jlink/
Still, the problem was not solved. I got a solution in Nordic DevZone. According to that, I copied libjlinkarm.so to the /usr/lib/ location using the following command. The problem was solved and the firmware was successfully flashed to my device.
sudo cp libjlinkarm.so /usr/lib/libjlinkarm.so
Now, we have the matter device and border router. The next thing we need is a matter controller. Let's install the matter controller on my PC.
Step 5: Getting Matter Controller to Linux PC
The CHIP Tool (chip-tool
) is a Matter controller implementation that allows to commission of a Matter device into the network and to communicate with it using Matter messages, which may encode Data Model actions, such as cluster commands.
The CHIP Tool for Linux or macOS is the default implementation of the Matter controller role and recommended for the nRF Connect platform.
For getting the CHIP Tool on my PC I downloaded the pre-built chip-tool-linux_x64.zip from the following GitHub link:
https://github.com/nrfconnect/sdk-connectedhomeip/releases
I unzipped it to the download location using the unzip command and the tool was ready to use.
After making the matter device the next step is to commission the device in the matter network. I will commission the device using CHIP Tool from my Ubuntu PC using BLE. The host PC must have a BLE device (most of the laptops have one). In the case of a desktop, you may need to use an external BLE adapter. To get the necessary information and see the progress it is better to connect the target board (nRF52840DK in my case) with the PC and run the serial monitor.
Before opening the serial monitor I check the COM port number of the nRF board using the following command from my Ubuntu terminal:
ls /dev/ttyACM*
I found that it is connected as ttyACM0. So, I open the serial monitor using the screen. The command was:
screen /dev/ttyACM0 115200
After running the above command I pressed the reset button of the nRF52840DK board for a fresh start. I got the following message from the serial terminal and LED1 of the DK board was flashing. It was clear that the device was in advertising mode.
So, I got connected with Raspberry Pi using SSH and checked the status of the router. It was active and ot-ctl state was the leader. Then I run the following command to get the dataset that will be required for commissioning the matter device using CHIP tool.
sudo ot-ctl dataset active -x
The dataset was ready for me as shown in the following screenshot.
I ran another terminal window and moved to the directory where the chip-tool was unzipped (Downloads in my case). Then, I run the following command for commissioning the device.
The structure of the command for commissioning over BLE is as follows:
./chip-tool pairing ble-thread <node_id> hex:<operational_dataset> <pin_code> <discriminator>
After successful commissioning, the LED1 of the DK board was turned off and I got the following results from the terminals. (the left is from the matter device and the right one is from the CHIP tool).
The next step is to control the matter device using the CHIP tool command. I was able to turn ON and OFF the LED2 of the nRF52840DK board using the following command:
./chip-tool-debug onoff toggle 1 1
The command pattern to toggle the OnOff attribute state is as follows:
./chip-tool onoff toggle <node_id> <endpoint_id>
Refer to the link below for a better understanding of the CHIP tool command: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/matter/chip_tool_guide.html
Developing Matter LockFor developing my matter lock I will start with the lock sample. For configuring the matter data model (like clusters, commands, and attributes) I will be required ZAP tool. ZCL Advanced Platform, in short ZAP tool, is a third-party tool that is a generic node.js based templating engine for applications and libraries based on Zigbee Cluster Library.
ZAP provides a user-friendly GUI environment for configuring Matter data model. If you want to know more about the matter data model visit: https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/protocols/matter/overview/data_model.html
Installing the ZAP toolFor downloading the ZAP tool I moved to the matter directory and run the following command:
python3 scripts/setup/nrfconnect/get_zap.py -l home/taifur
As I had no ZAP tool installed the download started automatically. After installation, it showed a location need to add my system path. I used the following command to do that:
echo 'export PATH=/home/taifur/ncs/v2.5.0/modules/lib/matter/home/taifur/zap-linux:"$PATH"' >> ${HOME}/.bashrc
source ${HOME}/.bashrc
I want to edit the clusters for the lock sample. So, I copied the lock sample as home_lock and ran the following command to open the ZAP tool in that location:
zap /home/taifur/ncs/v2.5.0/nrf/samples/matter/home_lock/src/lock.zap --zcl /home/taifur/ncs/v2.5.0/modules/lib/matter/src/app/zap-templates/zcl/zcl.json --gen /home/taifur/ncs/v2.5.0/modules/lib/matter/src/app/zap-templates/app-templates.json
The ZAP tool was opened successfully. Two endpoints have already been added to the sample application.
I can easily edit the clusters as per my requirements from the GUI.
For details about creating a new cluster please visit the Nordic official guide "Adding clusters to Matter application".
Modifying the Matter Lock Sample CodeIn this step, I will explain how I modified the lock sample to control a solenoid door lock. The sample was made to control and LED to indicate the lock and unlock state. The LED blinks first as an indication of lock and unlock initiation and finally becomes solid. Blinking is not suitable for a solenoid door lock or any other electromagnetic locking mechanism. So, I selected another pin (P1.03) or pin # 35 for controlling the solenoid lock and modified the code accordingly. I updated the LockStateChanged( ) function as follows:
oid AppTask::LockStateChanged(BoltLockManager::State state, BoltLockManager::OperationSource source)
{
switch (state) {
case BoltLockManager::State::kLockingInitiated:
LOG_INF("Lock action initiated");
/***************************************************/
nrf_gpio_pin_clear(LOCK_PIN);
/***************************************************/
sLockLED.Blink(50, 50);
#ifdef CONFIG_CHIP_NUS
GetNUSService().SendData("locking", sizeof("locking"));
#endif
break;
case BoltLockManager::State::kLockingCompleted:
LOG_INF("Lock action completed");
sLockLED.Set(true);
#ifdef CONFIG_CHIP_NUS
GetNUSService().SendData("locked", sizeof("locked"));
#endif
break;
case BoltLockManager::State::kUnlockingInitiated:
LOG_INF("Unlock action initiated");
/******************************************************/
nrf_gpio_pin_set(LOCK_PIN);
/******************************************************/
sLockLED.Blink(50, 50);
#ifdef CONFIG_CHIP_NUS
GetNUSService().SendData("unlocking", sizeof("unlocking"));
#endif
break;
case BoltLockManager::State::kUnlockingCompleted:
LOG_INF("Unlock action completed");
#ifdef CONFIG_CHIP_NUS
GetNUSService().SendData("unlocked", sizeof("unlocked"));
#endif
sLockLED.Set(false);
break;
}
/* Handle changing attribute state in the application */
Instance().UpdateClusterState(state, source);
}
I defined the lock pin at the beginning of the app_task.cpp file and include the nrf_gpio.h header file.
#include <hal/nrf_gpio.h>
#define LOCK_PIN 35
Inside the init( ) function I initialized the gpio as follows:
nrf_gpio_cfg_output(LOCK_PIN);
Then I built the project for the nRF52840DK board and flashed the device.
The full source is attached in the code section. You can replace the app_task.cpp file with the code in the matter lock sample application.
Making the HardwareThe following diagram represents the connections among the hardware components.
A 12V solenoid door lock is used in the matter lock project. I am using 4 AA cells for powering the project. As 4 AA cells provide 6V but the lock required 12V to run, I used a 12V boost converter module that converts 6V to 12V.
For driving the lock from a gpio pin of the nRF board I used a MOSFET power switch module that works on 3V to 5V.
The signal pin of the MOSFET module is connected to the P1.03 (D3) pin of the nRF52840DK board.
The above image shows the connections of the components.
After making the above connection I got some unstable behavior from the battery and the MOSFET power switch. First I replaced the battery but still, it was not working all the time. So, I decided to replace the MOSFET switch with a relay. I replaced the MOSFET with a relay module and the system was working perfectly. The following image shows the modified connection diagram of my Matter lock.
This updated circuit illustrated above is working perfectly.
Watch the Video Demonstration below for a better understanding:
For locking and unlocking the door I used the following chip-tool commands:
Locking command:
./chip-tool-debug doorlock lock-door 1 1 --timedInteractionTimeoutMs 1000
Unlocking command:
./chip-tool-debug doorlock unlock-door 1 1 --timedInteractionTimeoutMs 1000
Comments