This sample demonstrates a minimal implementation of the :ref:`Matter <ug_matter>` application layer. This basic implementation enables the commissioning on the device, which allows it to join a Matter network built on top of a low-power, 802.15.4 Thread network or on top of a Wi-Fi network. Support for both Thread and Wi-Fi is mutually exclusive and depends on the hardware platform, so only one protocol can be supported for a specific Matter device. In case of Thread, this device works as a Thread :ref:`Minimal End Device <thread_ot_device_types>`.
Use this sample as a reference for developing your own application. See the :ref:`ug_matter_creating_accessory` page for an overview of the process you need to follow.
The sample supports the following development kits:
.. table-from-sample-yaml::
For testing purposes, that is to commission the device and :ref:`control it remotely <matter_template_network_mode>` through a Thread network, you also need a Matter controller device :ref:`configured on PC or smartphone <ug_matter_configuring>`. This requires additional hardware depending on the setup you choose.
The development kits for this sample offer the following IPv6 network support for Matter:
- Matter over Thread is supported for
nrf52840dk_nrf52840,nrf5340dk_nrf5340_cpuapp, andnrf21540dk_nrf52840. - Matter over Wi-Fi is supported for
nrf5340dk_nrf5340_cpuappwith thenrf7002_ekshield attached or fornrf7002dk_nrf5340_cpuapp.
The sample starts the Bluetooth® LE advertising automatically and prepares the Matter device for commissioning into a Matter-enabled Thread network. The sample uses an LED to show the state of the connection. You can press a button to start the factory reset when needed.
Testing in either a Matter-enabled Thread or a Wi-Fi network requires a Matter controller that you can configure on PC or mobile device. By default, the Matter accessory device has IPv6 networking disabled. You must pair the device with the Matter controller over Bluetooth® LE to get the configuration from the controller to use the device within a Thread or a Wi-Fi network. You can enable the controller after :ref:`building and running the sample <matter_template_network_testing>`.
To pair the device, the controller must get the commissioning information from the Matter accessory device and provision the device into the network.
In Matter, the commissioning procedure takes place over Bluetooth LE between a Matter accessory device and the Matter controller, where the controller has the commissioner role. When the procedure has completed, the device is equipped with all information needed to securely operate in the Matter network.
During the last part of the commissioning procedure (the provisioning operation), the Matter controller sends the Thread or Wi-Fi network credentials to the Matter accessory device. As a result, the device can join the IPv6 network and communicate with other devices in the network.
To start the commissioning procedure, the controller must get the commissioning information from the Matter accessory device. The data payload includes the device discriminator and setup PIN code. The payload is encoded within a QR code, printed to the UART console.
- Button 1:
- If pressed for six seconds, it initiates the factory reset of the device. Releasing the button within the six-second window cancels the factory reset procedure.
Before you start testing the application, you can select one of the Matter template build types, depending on your building method.
Selecting a build type in |VSC|
For example, you can replace the selected_build_type variable to build the release firmware for nrf52840dk_nrf52840 by running the following command in the project directory:
west build -b nrf52840dk_nrf52840 -d build_nrf52840dk_nrf52840 -- -DCONF_FILE=prj_release.conf
The build_nrf52840dk_nrf52840 parameter specifies the output directory for the build files.
Note
If the selected board does not support the selected build type, the build is interrupted.
For example, if the shell build type is not supported by the selected board, the following notification appears:
File not found: ./ncs/nrf/samples/matter/template/configuration/nrf52840dk_nrf52840/prj_shell.confWhen you have built the sample and programmed it to your development kit, it automatically starts the Bluetooth LE advertising and the LED1 starts flashing (Short Flash On). At this point, you can press Button 1 for six seconds to initiate the factory reset of the device.
Note
If you are new to Matter, commission the Matter device using the Mobile Controller for Android (CHIP Tool for Android) when :ref:`setting up the Matter development environment <ug_matter_configuring_mobile>`.
To test the sample in a Matter-enabled Thread network, complete the following steps:
Commission the device into a Matter network by following the guides linked on the :ref:`ug_matter_configuring` page for the Matter controller you want to use. The guides walk you through the following steps:
- Only if you are configuring Matter over Thread: Configure the Thread Border Router.
- Build and install the Matter controller.
- Commission the device.
- Send Matter commands.
At the end of this procedure, LED 1 of the Matter device programmed with the sample starts flashing in the Short Flash Off state. This indicates that the device is fully provisioned, but does not yet have full IPv6 network connectivity.
Press Button 1 for six seconds to initiate the factory reset of the device.
The device reboots after all its settings are erased.
To upgrade the device firmware, complete the steps listed for the selected method in the :doc:`matter:nrfconnect_examples_software_update` tutorial of the Matter documentation.
This sample uses the Matter library that includes the |NCS| platform integration layer:
In addition, the sample uses the following |NCS| components:
The sample depends on the following Zephyr libraries: