Getting Started with Matter examples on NXP MCU platforms (MCUX SDK/FreeRTOS)

This guide walks you through building, flashing and testing Matter examples on NXP MCU platforms, step by step.

Important: This guide covers Matter development for FreeRTOS-based platforms using MCUX SDK only.

For Zephyr-based Matter development, please refer to the Matter Zephyr documentation.

VSCode Integration: All the build, flash, and debug described in this guide can also be performed through the MCUXpresso for VSCode Extension, which provides a graphical interface with automated setup.

Prerequisites

Before proceeding, make sure all required software tools are installed and the MCUX SDK with the Matter environment is properly set up. Follow the installation guide for detailed instructions.

You will also need an NXP MCU board that supports Matter. You can refer to the supported platforms for the complete list.

Build Matter example

List the project information

Use the west list_project command to view supported boards and their available configurations. The command can be used following this structure :

west list_project -p examples/matter_examples/<example_name>/mcux

You can further filter the output by board or use a glob pattern to list all Matter examples supported by a specific board.

For instance, the following command will list all the Matter examples and configurations supported by the FRDM-RW612 board :

west list_project -p examples/matter_examples/**/mcux -b frdmrw612

Note : For multicore boards, make sure to specify the target core ID using the syntax : -b <board>@<core_id>. For example “-b evkbmimxrt1170@cm7”.

Build the project

Before building a Matter example, make sure the Matter virtual environment is activated. You can do this using the activate script as shown below. If you’ve already run the bootstrap script in the same terminal session, you can skip this step.

For Unix-type systems (Linux/MacOS):

user@ubuntu:~/sdk-next/mcuxsdk$ source middleware/matter/third_party/nxp/nxp_matter_support/scripts/activate.sh

For Windows systems :

C:\sdk-next\mcuxsdk> .\middleware\matter\third_party\nxp\nxp_matter_support\scripts\activate.bat

Next, export the ARMGCC toolchain path using the environment variable ARMGCC_DIR. For example :

export ARMGCC_DIR=/home/Desktop/.matter_tools/arm-gnu-toolchain-14.2.Rel1-x86_64-arm-none-eabi/

To build Matter examples, use the west build command with the following syntax :

west build -d <build_dir> -b <board> examples/matter_examples/<example_name>/mcux

Additional arguments that can be passed to the west build command line :

--config release : This parameter can be added to build in release mode. The default build type is debug.
-DCONF_FILE : This variable can be used to provide a custom project configuration file. When used, the specified configuration files will be merged and used as the application configuration. Note that this variable must be provided with an absolute path of the custom prj.conf.
-Dcore_id : If the board is multi-core, this parameter can be used to specify the core ID targeted for the build.

Note about debug configuration: While the default build type is debug, this only enables debug options for the SDK and application layers. To enable debug symbols for the Matter (chip) module libraries as well, add -DCONFIG_DEBUG=y to your build command.

For instance, the following command will build Matter Thermostat example with Matter-over-WiFi and OTA enabled for RW612 platform :

west build -d build_matter -b frdmrw612 examples/matter_examples/thermostat/mcux -DCONF_FILE=middleware/matter/examples/platform/nxp/config/prj_wifi_ota.conf

If you would like to further configure your build, you can either edit the Matter application prj.conf, or provide your custom prj.conf in the build command line using the -DCONF_FILE.

Tu use multiple custom prj.conf files, separate them with semicolons as shown below :

west build -d <build_directory> -b <board> examples/matter_examples/<example_name>/mcux -DCONF_FILE="/path/to/prj_<custom1>.conf;/path/to/prj_<custom2>.conf;/path/to/prj_<custom3>.conf"

You can also set Kconfig symbols directly in the build command using -DCONFIG_<symbol>=<value>. For example, adding to the build command line -DCONFIG_CHIP_DEVICE_DISCRIMINATOR=3841 will set the discriminator Kconfig CONFIG_CHIP_DEVICE_DISCRIMINATOR to 3841.

You can also modify the configuration using the Kconfig GUI; however, these changes are temporary and will be lost after wiping the build directory. For more information about how to configure the project with Kconfig GUI, you can refer to the config project section in MCUX documentation.

Flashing Matter example

To flash a Matter example to your board, use the west flash command. For example:

west flash -d build_matter -r jlink

Use west flash -h to view all supported arguments, and west flash --context for runner-specific options.

To enable the west flash support in your environment, refer to the Flash and Debug The Example.

Platform-specific requirements

NBU image (for MCXW71 and MCXW72 platforms)

For MCXW71 and MCXW72 platforms, you must flash the NBU image before flashing the Matter application. Normally the NBU image should be written/updated only when migrating to a new NXP SDK or to a new Matter release.

Prerequisites:

Install NXP LinkServer for Microcontrollers

Steps:

Locate the NBU image in your Matter source code tree:
```
mcuxsdk/middleware/wireless/ieee-802.15.4/bin/<platform>/<platform>_nbu_ble_full_15_4_dyn.bin
```
Where <platform> is either mcxw71 or mcxw72 depending on your target platform.
Use the blhost tool from the NXP LinkServer for Microcontrollers to write the image on the board:

blhost -p <assigned_port> write-memory 0x48800000 <platform>_nbu_ble_full_15_4_dyn.bin

Replace <assigned_port> with the port assigned to your board and <platform> with your specific platform (mcxw71 or mcxw72).

Additional binaries for OTA and Factory Data

When building Matter examples with specific features enabled, additional binaries may need to be flashed before flashing the main application:

MCUboot bootloader (when OTA is enabled - RT1060, RT1170, and RW61x platforms)

If you built your Matter example with OTA support enabled (e.g., using prj_wifi_ota.conf) on RT1060, RT1170, or RW61x platforms, you must flash the MCUboot bootloader binary before flashing the main application. The MCUboot binary can be found in your build directory at:

<build_dir>/modules/chip/mcuboot/mcuboot_opensource.elf

Flash the MCUboot bootloader first, you can use JLink:

loadfile <build_dir>/modules/chip/mcuboot/mcuboot_opensource.elf

Note for MCXW platforms: For OTA functionality on MCXW71 and MCXW72 platforms, refer to the dedicated Matter OTA guide on MCXW7x for platform-specific instructions.

For detailed information about OTA functionality and MCUBoot on supported platforms, refer to the Matter OTA guide on NXP RW/RT.

Factory Data (when factory data is enabled)

If factory data is enabled in your build configuration, you need to flash the factory data binary. You can automatically generate your factory data during build by adding the extra argument -DCONFIG_CHIP_FACTORY_DATA_BUILD=y to your west build command.

The factory data binary can be found at:

<build_dir>/factory_data/factory_data.bin

For detailed information about factory data provisioning, refer to the NXP FreeRTOS platforms documentation.

Important note for MCUXpresso for VSCode Extension users

When using the MCUXpresso for VSCode Extension, the extension’s flash buttons only handle flashing the main application binary. If your project uses additional features or specific platforms, you must manually flash the required binaries as shown above before using the extension’s flash functionality. This is required for the application to boot properly and for debugging to work correctly within the VSCode environment.

The typical flashing sequence when using VSCode extension with OTA enabled would be:

For MCXW71/MCXW72 platforms:

Manually flash NBU image (required for all MCXW71/MCXW72 applications)
Manually flash factory data (if factory data enabled)
Use VSCode extension flash button for the main application

For RT1060/RT1170/RW61x platforms:

Manually flash MCUboot bootloader (if OTA enabled)
Manually flash factory data (if factory data enabled)
Use VSCode extension flash button for the main application

Testing Matter example

To test Matter examples on NXP MCU platforms, we recommend to follow the guide provided in the connectedhomeip repository : Testing the example.