Configuring Matter development environment

Setting up Matter development environment is all about setting up the Matter network and commissioning your device into it. 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 should be 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 network credentials to the Matter accessory device. As a result, the device can join the Thread network and communicate with other Thread devices in the network.

To start the commissioning procedure, the controller must get the onboarding information from the Matter accessory device. The data payload, which includes the device discriminator and setup PIN code, is encoded within a QR code, printed to the UART console, and can be shared using an NFC tag.

Matter development environment setup depends on how you choose to run the Matter controller. You can either run it on the same device as the Thread Border Router or run the Matter controller and the Thread Border Router on separate devices.

Running Thread Border Router and Matter controller on separate devices

The recommended approach is to run the Thread Border Router and the Matter controller on separate devices. With the Thread Border Router installed on Raspberry Pi, this approach provides support for most functionalities. For example, it allows using a mobile controller by providing connectivity between a Wi-Fi network and a Thread network.

In this setup, Raspberry Pi runs the Thread Border Router, which provides communication between the Thread nodes and the Matter controller. The controller can be installed on a PC or a mobile phone. Both the Thread Border Router and the Matter controller must support IPv6 communication over backbone network, for example Wi-Fi or Ethernet.

Configuring Thread Border Router and the CHIP Tool Matter controller on PC

In this setup, the Matter controller is installed on PC, and a dedicated Wi-Fi Access Point and the CHIP Tool Matter controller are used. This is the recommended setup.

Requirements

To use this setup, you need the following hardware:

• 1x PC with Ubuntu (20.04 or newer)

• 1x Raspberry Pi Model 3B+ or newer (along with an SD card with at least 8 GB of memory)

• 1x Wi-Fi Access Point supporting IPv6 (without the IPv6 Router Advertisement Guard enabled on the router)

• 1x nRF52840 DK or nRF52840 Dongle - for the Radio Co-Processor (RCP) device

• 1x compatible Nordic Semiconductor’s DK - for the Matter accessory device (compatible and programmed with one of Matter samples)

Configuring the environment

To configure and use Thread Border Router and PC Matter controller on separate devices, complete the following steps:

1. Program the development kit for the Matter accessory device with one of available Matter samples.

2. Configure the Thread Border Router on a Raspberry Pi. See Thread Border Router in the nRF Connect SDK documentation for details.

3. Configure the CHIP Tool controller by following the steps in the sections of the Working with the CHIP Tool in the Matter documentation:

   1. Build and run the CHIP Tool by completing the steps listed in “Building and running CHIP Tool”.

   2. Prepare the environment for testing by completing the steps listed in “Using CHIP Tool for Matter device testing”.

4. Depending on which Matter sample you programmed onto the development kit, go to this sample’s documentation page and complete the steps from the Testing section.

Configuring Thread Border Router and mobile Matter controller

In this setup, the Matter controller is installed on mobile, and a dedicated Wi-Fi Access Point and mobile Matter controller for Android are used.

Requirements

To use this setup, you need the following hardware:

• 1x smartphone with Android 8+

• 1x Raspberry Pi Model 3B+ or newer (along with an SD card with at least 8 GB of memory)

• 1x Wi-Fi Access Point supporting IPv6 (without the IPv6 Router Advertisement Guard enabled on the router)

• 1x nRF52840 DK or nRF52840 Dongle - for the Radio Co-Processor (RCP) device

• 1x compatible Nordic Semiconductor’s DK - for the Matter accessory device (compatible and programmed with one of Matter samples)

Configuring the environment

To configure and use Thread Border Router and mobile Matter controller on separate devices, complete the following steps:

1. Program the development kit for the Matter accessory device with one of available Matter samples.

2. Configure the Thread Border Router on a Raspberry Pi. See Thread Border Router in the nRF Connect SDK documentation for details.

3. Configure the mobile Matter controller:

   1. Install the controller using one of the options described in Mobile controller for Android.

   2. Complete the following steps from the Commissioning nRF Connect Accessory using Android CHIPTool user guide in the Matter documentation:

      • Building and installing Android CHIPTool - which prepares the controller for commissioning.

      • Preparing accessory device - which prepares your device programmed with the Matter sample for commissioning and provides you with the commissioning QR code.

        Note

        In the nRF Connect SDK, you can also use NFC tag for Matter commissioning.

      • Commissioning accessory device - which lets you commission your device into the network you created when configuring the Thread Border Router on Raspberry Pi.

      • Sending Matter commands - which checks the IPv6 connectivity.

4. Depending on which Matter sample you programmed onto the development kit, go to this sample’s documentation page and complete the steps from the Testing section.

Configuring Thread Border Router and Python Matter controller on PC

In this setup, the Matter controller is installed on PC, and a dedicated Wi-Fi Access Point and the Python Matter controller are used.

Requirements

To use this setup, you need the following hardware:

• 1x PC with Ubuntu (20.04 or newer)

• 1x Raspberry Pi Model 3B+ or newer (along with an SD card with at least 8 GB of memory)

• 1x Wi-Fi Access Point supporting IPv6 (without the IPv6 Router Advertisement Guard enabled on the router)

• 1x nRF52840 DK or nRF52840 Dongle - for the Radio Co-Processor (RCP) device

• 1x compatible Nordic Semiconductor’s DK - for the Matter accessory device (compatible and programmed with one of Matter samples)

Configuring the environment

To configure and use Thread Border Router and PC Matter controller on separate devices, complete the following steps:

1. Program the development kit for the Matter accessory device with one of available Matter samples.

2. Configure the Thread Border Router on a Raspberry Pi. See Thread Border Router in the nRF Connect SDK documentation for details.

3. Configure the Python Matter controller:

   1. Build the controller using one of the options described in Python controller for Linux.

   2. Complete the following steps from the Working with Python CHIP Controller user guide in the Matter documentation:

      • Building and installing - which prepares the controller for commissioning.

      • Running the tool - which gives you access to Bluetooth interface.

      • Using Python CHIP Controller for Matter accessory testing - which prepares your device programmed with the Matter sample for commissioning and testing.

        Note

        Skip the step about programming the example, as you already have a development kit programmed with a Matter sample.

4. Depending on which Matter sample you programmed onto the development kit, go to this sample’s documentation page and complete the steps from the Testing section.

Running Thread Border Router and Matter controller on the same device

If you only have one device, be it a PC with Linux or a Raspberry Pi, you can set up and test the development environment with both the Thread Border Router and the Matter controller running on this one device.

In this setup, a PC or a Raspberry Pi runs the Thread Border Router and the CHIP Tool Matter controller simultaneously. To simplify enabling the Thread communication with the Matter accessory device, use a Docker container with the OpenThread Border Router image instead of installing the OpenThread Border Router natively.

Setup with OpenThread Border Router and Matter controller on the same device

You can use this setup with both Python Matter controller and the CHIP Tool controller.

Requirements

To use this setup, regardless of whether you use Python Matter controller or CHIP Tool, you need the following hardware:

• One of the following:

  • 1x PC with Ubuntu (20.04 or newer)

  • 1x Raspberry Pi Model 3B+ or newer with Ubuntu (20.04 or newer) instead of Raspbian OS

• 1x Bluetooth LE dongle (can be embedded inside the PC, like it is on Raspberry Pi)

• 1x nRF52840 DK or nRF52840 Dongle - for the Radio Co-Processor (RCP) device

• 1x nRF52840 DK or nRF5340 DK - for the Matter accessory device (programmed with one of Matter samples)

Configuring the environment

Note

The Python Matter controller is currently not supported for building on Raspbian OS. If you use Raspberry Pi to run the controller and the Thread Border Router, replace Raspbian OS with Ubuntu Server.

To configure and use Thread Border Router and Matter controller on the same device, complete the following steps:

1. Program the Matter accessory device with one of available Matter samples.

2. Configure the Thread Border Router on a PC or on a Raspberry Pi, depending on what hardware you are using. For detailed steps, see the Running OTBR using Docker section on the Thread Border Router page in the nRF Connect SDK documentation.

3. Configure the controller, depending on the controller you want to use:

   • CHIP Tool controller:

     1. Complete the following actions by following the steps in the Working with the CHIP Tool user guide in the Matter documentation:

        • Build and run the CHIP Tool by completing the steps listed in “Building and running CHIP Tool”.

        • Prepare the environment for testing by completing the steps listed in “Using CHIP Tool for Matter device testing”.

   • Python Matter controller:

     1. Build the controller using one of the options described in Python controller for Linux.

     2. Complete the following steps from the Working with Python CHIP Controller user guide in the Matter documentation:

        • Building and installing - which prepares the controller for commissioning.

        • Running the tool - which opens the command-line interface.

        • Using Python CHIP Controller for Matter accessory testing - which prepares your device programmed with the Matter sample for commissioning and testing.

        Note

        Skip Step 1, as you have the development kit programmed with a Matter sample.

4. Depending on which Matter sample you programmed onto the development kit, go to this sample’s documentation page and complete the steps from the Testing section.