Matter tools

Use tools listed on this page to test Matter samples and develop Matter applications in the nRF Connect SDK.

GN tool

To build and develop Matter applications, you need the GN meta-build system. This system generates the Ninja files that the nRF Connect SDK uses.

The GN is automatically installed with the nRF Connect SDK’s toolchain when you install the nRF Connect SDK. If you are updating from the nRF Connect SDK version earlier than v1.5.0, see the following GN installation instructions.

If you want to build Matter applications with the nRF Connect SDK version earlier than v1.5.0, install the GN meta-build system. This system generates the Ninja files that the nRF Connect SDK uses.

To install the GN tool, complete the following steps:

  1. Download the latest version of the GN binary archive for Windows from the GN website.

  2. Extract the zip archive.

  3. Ensure that the GN tool is added to your PATH environment variable. For the exact instructions, see Environment Variables.

Matter controller tools

The following figure shows the available Matter controllers in the nRF Connect SDK.

Controllers used by Matter

Controllers used by Matter

You can read more about the Matter controller on the Matter network topologies page. For information about how to build and configure the Matter controller, see the pages in the Testing Matter in the nRF Connect SDK section.

CHIP Tool for Linux or macOS

The CHIP Tool for Linux or macOS is the default implementation of the Matter controller role, recommended for the nRF Connect platform. You can read more about it on the Working with the CHIP Tool page in the Matter documentation.

Depending on your system, you can install the CHIP Tool in one of the following ways:

  • For Linux only - Use the prebuilt tool package from the Matter nRF Connect releases GitHub page. Make sure that the package is compatible with your nRF Connect SDK version.

  • For both Linux and macOS - Build it manually from the source files available in the modules/lib/matter/examples/chip-tool directory and using the building instructions from the Working with the CHIP Tool page in the Matter documentation.

Note

To use CHIP Tool for macOS you need to have the appropriate Apple profile installed on your macOS machine. To learn how to install the profile and work with Apple devices see the Testing with Apple Devices user guide in the Matter documentation.

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.

You can use the ZAP tool for the following Matter use cases:

  • Enabling and disabling clusters, cluster commands, attributes, and events.

  • Configuring attributes’ default values.

  • Configuring attributes’ properties, such as storage type (RAM storage, non-volatile storage, application-managed).

All the relevant data for these use cases is stored in the ZAP file of your Matter application, which you can edit using the ZAP tool GUI. A ZAP file is a JSON file that contains the data model configuration of clusters, commands, and attributes that are enabled for a given application. It is not used directly by the application, but it is used to generate global and customized source files for handling requests enabled by the user. In the nRF Connect SDK, the ZAP file is provided in the src directory for each Matter sample.

For an example of how to use the ZAP tool to edit a ZAP file, see the Edit clusters using the ZAP tool in the Adding clusters to Matter application user guide. For more information about the ZAP tool, see the official ZCL Advanced Platform documentation.

Installing the ZAP tool

To install the ZAP tool using the recommended method, complete the following steps:

  1. Download the ZAP package containing pre-compiled executables and libraries and extract it:

    1. Open your installation directory for the nRF Connect SDK in a command line.

    2. Navigate to modules/lib/matter.

    3. Run the helper script to download and extract the ZAP package:

      python scripts/setup/nrfconnect/get_zap.py -l zap_location -o

      In this command:

      • zap_location corresponds to the directory where the ZAP tool package is to be extracted.

      • The -o argument in the command is used to allow overwriting files, if they already exist in the given location. Otherwise the script will display prompt during download and ask for user consent to overwrite the files directly.

  2. Verify the ZAP tool version by comparing the script output with the following possible cases:

    • Case 1: If your currently installed ZAP version matches the recommended one, you will see a message similar to the following one:

      Your currently installed ZAP tool version: 2022.12.20 matches the recommended one.

      This means that your ZAP version is correct and the tool executable can be accessed from the operating system environment, so you can skip the following step about adding the ZAP tool to the system PATH environment variable.

    • Case 2: If your currently installed ZAP version does not match the recommended one or no ZAP version is installed on your device, you will see a message similar to the following one:

      Your currently installed ZAP tool version 2022.12.19 does not match the recommended one: 2022.12.20.

      Alternatively, this message can look like the following one:

      No ZAP tool version was found installed on this device.

      In this case, the package download process will start automatically:

      Trying to download ZAP tool package matching your system and recommended version.
100% [......................................................................] 150136551 / 150136551
ZAP tool package was downloaded and extracted in the given location.

      Depending on your operating system, the download will conclude with the following message, with updated zap_cli_location and zap_location paths, which you will need in the following step:

      #######################################################################################
# Please add the following location(s) to the system PATH:                            #
# zap_location                                                                      #
#######################################################################################

  3. Add the ZAP packages location to the system PATH environment variables. This is not needed if your currently installed ZAP version matches the recommended one (case 1 from the previous step).

    For the detailed instructions for adding PATH environment variables on Windows, see Environment Variables.

Alternative installation methods

You can also install the ZAP tool using one of the following methods:

Both these methods still require adding the ZAP tool location to the system PATH environment variables, as detailed in the step 3 above.

CHIP Certificate Tool

Matter’s CHIP Certificate Tool, in short chip-cert, is a command-line utility tool for generating and editing Matter certificates such as Certificate Declarations (CD), Device Attestation Certificates (DAC), Product Attestation Intermediate (PAI) certificates, and Product Attestation Authority (PAA) certificate, alongside their related keys. You can use it for integration testing purposes while working on a Matter end product.

For more information about the chip-cert tool, see how to generate custom certification declarations for integration testing in the nRF Connect SDK. You can also take a look at the CHIP Certificate Tool source files.

Installing CHIP Certificate Tool

To install the chip-cert tool, complete the following steps:

  1. Navigate to the connectedhomeip root directory.

  2. In a terminal, run the following command to build the tool executable file:

    cd src/tools/chip-cert && gn gen out && ninja -C out chip-cert

  3. Add the chip-cert tool to the system PATH environment variable when built.

Generating custom certificates in factory data

Adding the chip-cert tool to the system PATH allows you to build Matter samples, the Matter weather station, and the Matter bridge applications with custom certificates included in the factory data. This lets you for example change the test Vendor ID, Product ID, or other data.

To build a Matter application in the nRF Connect SDK with custom certification data, make sure to set the CONFIG_CHIP_FACTORY_DATA_USE_DEFAULT_CERTS to n when building an example with factory data.

SPAKE2+ Python tool

SPAKE2+ Python Tool is a Python script for generating SPAKE2+ protocol parameters. The protocol is used during Matter commissioning to establish a secure session between the commissioner and the commissionee.

Note

Currently, the tool only supports generating Verifier parameters.

For usage examples, see the SPAKE2+ Python Tool page in the Matter SDK official documentation.

Matter over Thread tools

You can use the following Thread tools when working with Matter in the nRF Connect SDK using the Matter over Thread setup.

Thread Border Router

The Thread Border Router is a specific type of Border Router device that provides connectivity from the IEEE 802.15.4 network to adjacent networks on other physical layers (such as Wi-Fi or Ethernet). Border Routers provide services for devices within the IEEE 802.15.4 network, including routing services for off-network operations.

See the Thread Border Router documentation for configuration instructions.

nRF Sniffer for 802.15.4

The nRF Sniffer for 802.15.4 is a tool for learning about and debugging applications that are using protocols based on IEEE 802.15.4, like Thread or Zigbee. It provides a near real-time display of 802.15.4 packets that are sent back and forth between devices, even when the link is encrypted.

See nRF Sniffer for 802.15.4 for documentation.

nRF Thread Topology Monitor

nRF Thread Topology Monitor is a desktop application that connects to a Thread network through a serial connection to visualize the topology of Thread devices. It allows you to scan for new devices in real time, check their parameters, and inspect network processes through the log.

See nRF Thread Topology Monitor for documentation.