Matter: Manufacturer-specific

This sample demonstrates an implementation of custom manufacturer-specific clusters used by the application layer. This sample uses development kit’s buttons and LEDs to demonstrate the functionality of the custom NordicDevkit cluster.

This device works as a Matter accessory device, meaning it can be paired and controlled remotely over a Matter network built on top of a low-power 802.11ax (Wi-Fi® 6) or 802.15.4 (Thread) protocol. Support for both Thread and Wi-Fi is mutually exclusive and depends on the hardware platform, so only one protocol is supported for a specific Manufacturer-specific device. In case of Thread, this device works as a Minimal End Device.

You can use this sample as a reference for creating your own application. See the Adding clusters to Matter application page for an overview of the process you need to follow.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target	Shields
nRF54LM20 DK	PCA10184	nrf54lm20dk	nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp	nrf7002eb2
nRF54L15 DK	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l15/cpuapp/ns nrf54l15dk/nrf54l15/cpuapp
nRF54L15 DK (emulating nRF54L10)	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l10/cpuapp
nRF5340 DK	PCA10095	nrf5340dk	nrf5340dk/nrf5340/cpuapp
nRF52840 DK	PCA10056	nrf52840dk	nrf52840dk/nrf52840

If you want to commission the Manufacturer-specific device and control it remotely through a Thread or Wi-Fi network, you need to set-up the Thread Border Router (Matter over Thread only) and control it with the chip-tool, or use a commercial ecosystem controller. When this happens, you will also be able to control it through a Matter controller device configured on PC or smartphone. This requires additional hardware depending on the setup you choose.

Note

Matter requires the GN tool. If you are updating from the nRF Connect SDK version earlier than v1.5.0, see the GN installation instructions.

IPv6 network support

The following development kits for this sample offer IPv6 network support for Matter:

• Matter over Thread is supported for the nrf52840dk/nrf52840, nrf5340dk/nrf5340/cpuapp, nrf54l15dk/nrf54l15/cpuapp, nrf54lm20dk/nrf54lm20b/cpuapp, and nrf54lm20dk/nrf54lm20a/cpuapp board targets.

• Matter over Wi-Fi is supported for the nrf54lm20dk/nrf54lm20b/cpuapp and nrf54lm20dk/nrf54lm20a/cpuapp board targets with the nrf7002eb2 shield attached.

Overview

nRF52, nRF53 and nRF70 DKsnRF54 DKs

Button 2 is used to set the state of the NordicDevkit cluster’s attribute, UserButton. LED 2 reflects the state of the UserLED.

The Matter command SetLED is used to control the state of UserLED. It takes one argument - the action to be performed (0 to turn the LED off, 1 to turn it on, 2 to toggle the state). The UserLED attribute is persistent and stored across the reboots. The UserButtonChanged event is generated when the UserButton attribute is changed.

The NordicDevkit cluster introduces a writable DevKitName attribute, of string type as well. The DevKitName attribute is persistent and stored across the reboots.

The sample additionally extends the Basic Information cluster with a RandomNumber attribute and GenerateRandom command that updates the RandomNumber with a random value. The RandomNumberChanged event is generated when the RandomNumber attribute is changed. The RandomNumber attribute value is not persistent and it is generated on each application’s boot.

Custom manufacturer-specific cluster

The sample provides a custom NordicDevkit cluster, configured in the src/default_zap/NordicDevKitCluster.xml file. To learn more about adding custom clusters to your Matter application, see the Creating manufacturer-specific clusters in Matter application section.

Configuration

This section describes the configuration options for the sample.

See Configuring and building for information about how to permanently or temporarily change the configuration.

The sample uses a prj.conf configuration file located in the sample root directory for the default configuration. It also provides additional files for different custom configurations. When you build the sample, you can select one of these configurations using the FILE_SUFFIX variable.

See Custom configurations and Providing CMake options for more information.

Note

If you are working with multiple devices, set a unique discriminator for each one, or commission them one at a time. See Matter device identification for more information.

The sample supports the following build configurations:

Manufacturer-specific build configurations

Configuration	File name	FILE_SUFFIX	Supported board	Description
Debug (default)	prj.conf	No suffix	All from Requirements	Debug version of the application. Enables additional features for verifying the application behavior, such as logs.
Release	prj_release.conf	release	All from Requirements	Release version of the application. Enables only the necessary application functionalities to optimize its performance.
Internal memory only	—	internal	nRF54LM20 DK	Debug version of the application with external flash disabled. Enables the Manufacturer-specific to work using internal memory only.

Advanced configuration options

This section describes advanced configuration options that you can apply in this sample. Use the click to show toggle to expand the content.

Support for Trusted Firmware-M

The sample supports using Trusted Firmware-M on the nrf54l15dk/nrf54l15/cpuapp board target. The memory map of the sample has been aligned to meet the TF-M partition alignment requirements.

To build the sample with Trusted Firmware-M support, add the ns suffix to the nrf54l15dk/nrf54l15/cpuapp board target board target, and use the FILE_SUFFIX=tfm variable:

nRF Connect for VS CodeCommand line

When building with nRF Connect for VS Code, complete the following steps:

1. set the board target to include the ns suffix (for example nrf54l15dk/nrf54l15/cpuapp/ns) in your build configuration.

2. Add -DFILE_SUFFIX=tfm to Extra CMake arguments in your build configuration.

Device firmware upgrade support

The sample supports device firmware upgrade (DFU) over-the-air (OTA) using the following protocols:

• Matter OTA update protocol that uses the Matter operational network for querying and downloading a new firmware image.

• Simple Management Protocol (SMP) over Bluetooth® LE. In this case, the DFU can be done either using a smartphone application or a PC command-line tool. This protocol is not part of the Matter specification.

In both cases, the MCUboot secure bootloader is used to apply the new firmware image.

The DFU over Matter is enabled by default. Additionally, you can enable the DFU over SMP by using the -DCONFIG_CHIP_DFU_OVER_BT_SMP=y build flag.

See Providing CMake options for instructions on how to add these options to your build.

The following platforms require external flash memory to perform the DFU:

• nRF52840 DK

• nRF5340 DK

• nRF54L10 DK

You can run DFU without external flash memory on the nRF54L15 and nRF54LM20 DKs using the MCUboot image compression feature. To see if the sample supports this feature, check whether the internal build configuration is available in the build configuration table.

nRF Connect for VS CodeCommand line

When building with nRF Connect for VS Code, add your desired dfu_build_flag to Extra CMake arguments. For example add -DCONFIG_CHIP_DFU_OVER_BT_SMP=y to enable DFU over BT SMP.

Factory data support

In this sample, factory data support specific to the nRF Connect SDK is enabled by default for all configurations. This means that a new factory data set will be automatically generated when building for the target board.

To disable factory data support, set the following Kconfig options to n:

• CONFIG_CHIP_FACTORY_DATA

• SB_CONFIG_MATTER_FACTORY_DATA_GENERATE

To learn more about factory data, read the Factory provisioning in Matter user guide.

Custom board with Nordic SoC

To prepare the sample to work with a custom board, complete the following steps:

1. Refer to the Create your board directory Zephyr guide and create your board directory.

2. Modify the contents of the board.yaml file according to the Write your board YAML user guide.

3. Update the Write your devicetree (all .dts and .dtsi files) to match your board’s requirements.

4. Write Kconfig files to enable all required Kconfig options for your board.

5. If you want to build your custom board with nRF70 Wi-Fi support, set the CONFIG_CHIP_WIFI and SB_CONFIG_WIFI_NRF70 Kconfig options to y.

6. If your device uses external flash, add its devicetree definition under the board/<board_name>_<soc_name>.overlay file, and set nordic,pm-ext-flash in the devicetree’s chosen configuration.

7. Refer to the Advanced Matter Kconfig options user guide, create your list of advanced configurations for your board, and apply the selected Kconfig options in the prj.conf file.

8. See the list of threads used in Matter application and adjust stack sizes according to your board and project requirements.

9. A custom board does not have support for LEDs and buttons by default. Therefore, you need to provide your own implementation of the nrf/samples/matter/common/src/board/board.cpp board file.

For more information, see the following guides:

• Board Porting Guide and Custom Board, Devicetree and SOC Definitions to learn how to create a custom board directory.

• Optimizing memory usage in Matter applications to learn how to optimize memory on your board.

• Advanced Matter Kconfig options to learn about Matter configuration.

• Matter hardware and memory requirements to learn about hardware requirements for Nordic Development Kits and to use as a reference when planning your custom board.

Internal memory only

For the nRF54LM20 DK, you can configure the sample to use only the internal RRAM for storage. It applies to the DFU as well, which means that both the currently running firmware and the new firmware to be updated will be stored within the device’s internal RRAM memory.

The DFU image fits in the internal flash memory if you use MCUboot image compression.

This configuration is disabled by default for the Matter Manufacturer-specific sample. To enable it, set the FILE_SUFFIX CMake option to internal.

To build the sample for the nRF54LM20 DK with support for Matter OTA DFU and DFU over Bluetooth SMP, and using internal RRAM only:

nRF Connect for VS CodeCommand line

Add -DCONFIG_CHIP_DFU_OVER_BT_SMP=y -DFILE_SUFFIX=internal to Extra CMake arguments in your build configuration.

To build the sample for the same purpose in the release configuration:

nRF Connect for VS CodeCommand line

Add -DCONFIG_CHIP_DFU_OVER_BT_SMP=y -DFILE_SUFFIX=internal -D<sample_name>_EXTRA_CONF_FILE=prj_release.conf to Extra CMake arguments in your build configuration, replacing <sample_name> with the actual sample name (for example light_bulb or matter_bridge).

In this case, the size of the MCUboot secondary partition used for storing the new application image is approximately 30-40% smaller than it would be when using a configuration with external flash memory support.

User interface

This section describes the user interface available on the development kit in this sample.

Buttons and LEDs map

This section explains the names of Buttons and LEDs visible on a board depending on the development kits that are used in this sample user guide.

Buttons and LEDs map

DK family	First LED	Second LED	Third LED	Fourth LED	First Button	Second Button	Third Button	Fourth Button
nRF52 and nRF53 DKs	LED 1	LED 2	LED 3	LED 4	Button 1	Button 2	Button 3	Button 4
nRF54 DKs	LED 0	LED 1	LED 2	LED 3	Button 0	Button 1	Button 2	Button 3
nRF70 DKs	LED 1	LED 2	Not available	Not available	Button 1	Button 2	Not available	Not available

Development kit interface

This sample implements the following interface available on a development kit. While reading the names, refer to the Buttons and LEDs map.

First LED:

Shows the overall state of the device and its connectivity. The following states are possible:

• Short Flash On (50 ms on/950 ms off) - The device is in the unprovisioned (unpaired) state and is waiting for a commissioning application to connect.

• Rapid Even Flashing (100 ms on/100 ms off) - The device is in the unprovisioned state and a commissioning application is connected over Bluetooth LE.

• Solid On - The device is fully provisioned.

Second LED:

Reflects the state of UserLED attribute in the NordicDevkit cluster.

First Button:

Depending on how long you press the button:

• If pressed for less than three seconds:

  • If the device is not provisioned to the Matter network, it initiates the Simple Management Protocol (SMP) server and Bluetooth LE advertising for Matter commissioning. After that, the Device Firmware Update (DFU) over Bluetooth Low Energy can be started. Bluetooth LE advertising makes the device discoverable over Bluetooth LE for the predefined period of time (1 hour by default).

  • If the device is already provisioned to the Matter network, it re-enables the SMP server. After that, the DFU over Bluetooth Low Energy can be started.

  • If pressed for more than three seconds, it initiates the factory reset of the device. Releasing the button within three seconds of the initiation cancels the factory reset procedure.

Second Button:

Sets the state of UserButton attribute in the NordicDevkit cluster to true on press and false on release.

SEGGER J-Link USB Port:

Used for getting logs from the device or for communicating with it through the command-line interface.

NFC port with antenna attached:

Optionally used for obtaining the onboarding information from the Matter accessory device to start the commissioning the device procedure while using a commercial ecosystem. See the Testing with commercial ecosystem section.

Building and running

This section describes how to build the sample and commission it to the Matter network.

This sample can be found under samples/matter/manufacturer_specific in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build. The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device. If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.

Before starting the commissioning procedure, make sure that the device is discoverable over Bluetooth LE. The device becomes discoverable automatically upon the device startup, but only for a predefined period of time (one hour by default). If the Bluetooth LE advertising times out, enable it again.

Advanced building options

This section describes advanced building options that you can use with this sample. Use the click to show toggle to expand the content.

Building the Matter over Wi-Fi variant on nRF54LM20 DK with nRF7002-EB II shield

To build the Matter over Wi-Fi sample variant on nRF54LM20 DK with nRF7002-EB II attached, perform the following actions depending on the build tool:

nRF Connect for VS CodeCommand line

1. When building an application as described in the nRF Connect for VS Code documentation, follow the steps for setting up the build configuration.

2. In the Add Build Configuration screen, click the Add argument button under the Extra CMake argument section.

3. Add the following Kconfig options:

   -DSHIELD=nrf7002eb2 -DSB_CONFIG_WIFI_NRF70=y -DCONFIG_CHIP_WIFI=y
   

Flashing the Matter over Wi-Fi sample variant

In the Matter over Wi-Fi variant of this sample, the portion of the application code related to the nRF70 Series Wi-Fi firmware is stored in the external memory. When you program the sample onto your development kit, the build process automatically includes the Wi-Fi firmware patch and programs it into the external memory.

By default, using the west flash command erases the entire external flash memory before writing the new Wi-Fi firmware patch. This full-chip erase ensures that the patch is written to a clean memory area, but it can significantly increase the programming time - sometimes taking several minutes, especially if the external flash is large.

To optimize the programming process and reduce the time required, you can instruct west flash to erase only the specific memory ranges that will be overwritten by the Wi-Fi firmware patch. This is done by adding the --ext-erase-mode=ranges argument to the command. With this option, only the necessary sections of external memory are erased, making the programming process faster.

nRF Connect for VS CodeCommand line

To speed up programming, use the Flash button instead of Erase and Flash to Board in the Actions View. Using Erase and Flash to Board erases the entire external flash and can take several minutes.

To disable storing the Wi-Fi firmware patch in the external memory, complete the following steps:

1. Remove the Wi-Fi firmware patch partition from the partition list.

2. Set the SB_CONFIG_WIFI_PATCHES_EXT_FLASH_STORE Kconfig option to n.

3. Set the SB_CONFIG_DFU_MULTI_IMAGE_PACKAGE_WIFI_FW_PATCH Kconfig option to n.

4. Set the SB_CONFIG_MCUBOOT_UPDATEABLE_IMAGES Kconfig option to 2.

To learn more about the Wi-Fi firmware patch, see the Adding nRF70 Series firmware patch partitions user guide.

Testing

This section shows how to test the sample. You can test it using your PC and the CHIP Tool for Linux or macOS or commercial ecosystem that supports Matter.

Testing with CHIP Tool

Complete the following steps to test the Manufacturer-specific device using CHIP Tool:

Prepare Matter network

To set up the Matter network, configure your environment according to the protocol you are using. Choose the appropriate tab below and follow the corresponding steps to prepare your Matter network.

Matter over ThreadMatter over Wi-Fi

1. Configure the Thread Border Router. See the Running OTBR using Docker section on the Thread Border Router page.

2. Download the prebuilt CHIP tool package from the Matter nRF Connect releases GitHub page. Make sure that the package is compatible with your nRF Connect SDK version.

Prepare your DK

To flash your DK with the sample and prepare it for testing, complete the following steps:

1. Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.

2. Open a serial port connection to the kit using a terminal emulator that supports VT100/ANSI escape characters (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

3. If the device was not erased during the programming, perform the factory reset procedure.

   To restore the device settings and state to its factory set press the First Button for six seconds to initiate the factory reset of the device.

Commission to Matter network

To commission the device to the Matter network complete the following steps:

Matter over ThreadMatter over Wi-Fi

1. Obtain a Thread active dataset from OTBR:

   OTBR on Raspberry PiOTBR on PC using Docker

   1. Connect to the Raspberry Pi through USB or SSH.

   2. Run the following commands:

   sudo ot-ctl
   > dataset active -x
   

   The output should look like:

   080000000000000000000300001735060004001fffe00208deadbeefcafe12340708fd123456789abc00000510112233445566778899aabbccddeeff00030a54657374576f726b3031010211220410aabbccddeeff00112233445566778899aa0c0402a0f7f8
   Done
   

2. Run the following command and fill the <thread dataset> argument obtain in the previous step:

   chip-tool pairing ble-thread 1 hex:<thread dataset> 20202021 3840

Run CHIP Tool interactive mode

Enter the interactive mode by running the following command:

chip-tool interactive start

Read the NordicDevkit cluster’s attributes by index

any read-by-id 0xFFF1FC01 attribute-id 1 1

Where:

• attribute-id is the attribute’s ID, equal to 0xFFF10000 for DevKitName, 0xFFF10001 for UserLED and 0xFFF10002 for UserButton attributes for the NordicDevkit cluster in this sample.

Verify all the attributes

In the interactive mode, search the logs received by CHIP Tool and verify that all attributes have been read correctly and are equal to the default values defined in cluster’s configuration.

Write the DevkitName attribute

any write-by-id 0xFFF1FC01 0xFFF10000 "NewName" 1 1

Where:

• NewName is the new name to be set for the DevkitName attribute.

Read the DevkitName attribute again

In the interactive mode, read the DevkitName attribute again by running the following command, and check if it has changed:

any read-by-id 0xFFF1FC01 attribute-id 1 1

Send the SetLED command to control the LED state

In the interactive mode, send the SetLED command to control the LED state by running the following command:

any command-by-id 0xFFF1FC01 0xFFF10000 '{ "0x0": "u:action" }' 1 1

• action is the action that should be performed on LED attribute: 0 to turn the LED off, 1 to turn it on, 2 to toggle the state.

The LED state has changed and the attribute value is updated.

Subscribe to the UserButton attribute

In the interactive mode, subscribe to the UserButton attribute to monitor the button state by running the following command:

any subscribe-by-id 0xFFF1FC01 0xFFF10002 0 120 1 1

Press the button assigned to the UserButton

Being subscribed to the UserButton attribute, press the button assigned to the UserButton and wait for the attribute state to be updated. You should see the attribute state updated in the CHIP Tool interactive mode.

Read the UserButtonChanged event

In the interactive mode, read the UserButtonChanged event to check that events were generated on UserButton attribute changes by running the following command:

any read-event-by-id 0xFFF1FC01 0xFFF10000 1 1

Read the Basic Information cluster’s RandomNumber attribute

In the interactive mode, read the Basic Information cluster’s RandomNumber attribute by running the following command:

any read-by-id 0x0028 0x17 1 0

Send the GenerateRandom command

In the interactive mode, send the GenerateRandom command to update the RandomNumber attribute by running the following command:

any command-by-id 0x0028 0 '{}' 1 0

Verify that the random value

In the interactive mode, read the Basic Information cluster’s RandomNumber attribute again by running the following command:

any read-by-id 0x0028 0x17 |node_id| 0

You should see the random value updated in the CHIP Tool logs.

Read the Basic Information cluster’s RandomNumberChanged event

In the interactive mode, read the Basic Information cluster’s RandomNumberChanged event to check that events were generated on RandomNumber attribute changes by running the following command:

any read-event-by-id 0x0028 0x4 |node_id| 0

Testing with commercial ecosystem

Note

The sample sample, in its default configuration, is not recognized or supported by any major Matter ecosystem. This is because it does not use a standard Matter device type that ecosystem controllers expect or can interact with. To make your implementation compatible with a specific ecosystem, you must add an endpoint and assign a device type that is officially supported by that ecosystem. For detailed instructions on how to add supported clusters and device types, refer to the Adding clusters to Matter application user guide.

Before starting testing, ensure that the ecosystem supports the device types enabled in this sample. See the ecosystem manual page for instructions on how to use it.

When you start the commissioning procedure, the ecosystem controller must get the onboarding information from the Matter accessory device. The onboarding information representation depends on your commissioner setup.

For this sample, you can use one of the following onboarding information formats to provide the commissioner with the data payload that includes the device discriminator and the setup PIN code:

Manufacturer-specific sample onboarding information

QR Code	QR Code Payload	Manual pairing code
Scan the following QR code with the app for your ecosystem:	MT:K.K9042C00KA0648G00	34970112332

When the factory data support is enabled, the onboarding information will be stored in the build directory in the following files:

• The factory_data.png file includes the generated QR code.

• The factory_data.txt file includes the QR code payload and the manual pairing code.

This data payload also includes test Device Attestation, with test Certification Declaration, Product ID, and Vendor ID. These are used for Device Attestation within commissioning, and you can generate your own test Certification Declaration when you work on Matter end product.

Dependencies

This sample uses the Matter library that includes the nRF Connect SDK platform integration layer:

• Matter

In addition, the sample uses the following nRF Connect SDK components:

• DK Buttons and LEDs

• URI messages and records

• Type 2 Tag

The sample depends on the following Zephyr libraries:

• Logging

• Kernel Services