ESP Matter Thread Border Router

Overview

The ESP Matter Thread Border Router example from Espressif's SDK for Matter demonstrates how to build firmware for a Matter-compliant Thread Border Router device running on Espressif's hardware.

The firmware creates a Matter node and configures a Thread Border Router endpoint. If Thread support is enabled, it configures the OpenThread platform with default radio, host, and port settings. Finally, it starts the Matter stack with an event callback to handle network events and initializes the diagnostic console if enabled.

When the ESP32 connects to Wi-Fi and gets an IP, it sets up Wi-Fi as the backbone for OpenThread and starts the Thread Border Router to enable communication between Thread and Wi-Fi. A static variable stops it from running more than once.

Build and Run

This section demonstrates how to build and run the ESP Matter Thread Border Router example from Espressif's SDK for Matter.

Prerequisites:

ESP-IDF development environment is set up.
ESP-Matter development environment is set up.
ESP THREAD BR-ZIGBEE GW board

Step 1: Build and Configure the RCP Image

The build process is similar to the Basic Thread Border Router example. The following steps from the Basic Thread Border Router example are required if not already completed:

Follow Step 1: Build the RCP Image.
Follow optional Step 3: Configure the Device.

Step 2: Set Up Environment

Set up the environment and navigate to the ESP Matter Thread Border Router example directory:

get_idf
get_matter
cd $ESP_MATTER_PATH/examples/thread_border_router

Step 3: Set target to ESP32-S3

idf.py set-target esp32s3

Step 4: Connect the ESP Thread Border Router Board

Follow Step 4: Connect the ESP Thread Border Router Board from the Basic Thread Border Router example.

Step 5: Build and Flash

idf.py build 
idf.py -p <PORT> flash monitor

Matter CLI

This section demonstrates how to use the Matter CLI on the ESP Matter Thread Border Router.

The device automatically starts BLE advertising when powered on. The following command can be used to check the state:

matter ble adv state

The following command prints the Matter configuration, including the PIN code and Discriminator, needed for commissioning:

matter config

CHIP-Tool

The Thread Border Router management cluster allows provisioning of the Thread interface using a Matter commissioner.

Commissioning to Wi-Fi over BLE

Refer to Commissioning to Wi-Fi over BLE using CHIP Tool.

Joining a Thread Network

After commissioning, a fail-safe timer must be armed:

./chip-tool generalcommissioning arm-fail-safe <TIMEOUT_IN_SEC> 1 <NODE_ID> 0
./chip-tool generalcommissioning arm-fail-safe 120 1 0x1122 0

Provision the Border Router using an active dataset in HEX TLV format (the same format used for commissioning a Matter over Thread device via the ble-thread command). The Thread Border Router Management Cluster should be used:

./chip-tool threadborderroutermanagement set-active-dataset-request hex:<ACTIVE_DATASET> <NODE_ID> 1

If the active dataset command succeeds, complete the commissioning process by disarming the fail-safe timer and committing the configuration to non-volatile storage:

./chip-tool generalcommissioning commissioning-complete <NODE_ID> 1

Verify the configuration by retrieving the active dataset:

./chip-tool threadborderroutermanagement get-active-dataset-request <NODE_ID> 1

The response includes a DatasetResponse containing the active dataset in hex-encoded format.

References

ESP-Matter Thread Border Router

Last modified: 09 March 2025