Application Customization#

Overview#

This guide covers how to customize Matter applications for NXP MCU platforms, and how to create freestanding applications, which provide the most flexibility for custom development.

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

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

Prerequisites#

Before customizing Matter applications, ensure that you have :

Completed the installation guide
Successfully built a basic Matter example, see getting started guide
Familiarity with CMake and MCUX build and configuration system

Create a freestanding example from an existing Matter example#

A freestanding application is a self-contained project that can be built and modified independently of the main SDK. This section provides step-by-step guidance on creating and customizing your freestanding Matter application.

How to create a freestanding example#

You can create a freestanding application based on any existing Matter example from the mcuxsdk/examples/matter_examples directory.

You can use the west export_app command like follow :

~/sdk-next/mcuxsdk$ west export_app -b <board> examples/matter_examples/<example_name>/mcux -o <path_to_freestanding_app>

This command exports the selected Matter example to the specified destination path, copy the necessary files to be customized by the user, and updates the build system to recognize the new paths of the copied files.

For example, to create a freestanding application from the Thermostat example for the FRDM-RW612 board, the command would look like:

~/sdk-next/mcuxsdk$ west export_app -b frdmrw612 examples/matter_examples/thermostat/mcux -o ~/Desktop/freestanding_thermostat_app

For multicore boards, you must specify the core ID using the -Dcore_id=<core> parameter. For example, to create a freestanding application from the lighting-app example for the FRDM-MCXW72 board:

~/sdk-next/mcuxsdk$ west export_app -b frdmmcxw72 examples/matter_examples/lighting-app/mcux -Dcore_id=cm33_core0 -o ~/Desktop/freestanding_lighting_app

The exported application is located at the specified destination path. For example, ~/Desktop/freestanding_thermostat_app or ~/Desktop/freestanding_lighting_app) and will have the following structure:

common/main folder containing application source files and main logic.
ldscripts folder containing linker scripts for memory layout configuration.
zap folder containing the application ZAP files.
CMakeLists.txt, Kconfig and prj.conf application entry-level files.
nxp_sdk_reconfig.cmake CMake file to reconfigure the MCUX SDK and adapt it for Matter application requirements.
Custom prj_<flavour>.conf configuration files for different application variants.

How to build a freestanding example#

To build the Matter freestanding example, follow these steps. As a prerequisite, ensure the tools from the installation guide are available in your PATH.

# 1. Navigate to your exported application directory:
$ cd ~/Desktop/freestanding_thermostat_app

# 2. Set up the Matter environment
$ source <path_to_mcuxsdk>/mcuxsdk/middleware/matter/third_party/nxp/nxp_matter_support/scripts/bootstrap.sh <path_to_mcuxsdk>

# 3. Set up the MCUX environment
$ source <path_to_mcuxsdk>/mcuxsdk/mcux-env.sh

# 4. Export your ARMGCC toolchain path
$  export ARMGCC_DIR=<path_to_armgcc>

# 5. Build the application
$ west build -d build_matter -b frdmrw612

For additional information about the build configuration you can refer to the Build the project section.

Now that you have created and built a freestanding application, let’s explore the various customization options available.

Customization options#

The section provides ways to customize your Matter application and adapt it to suit your specific project requirements.

Customize `nxp_sdk_reconfig.cmake`#

mcuxsdk/middleware/matter/third_party/nxp/nxp_matter_support/examples/platform/<platform_family>/nxp_sdk_reconfig.cmake is provided as an example of how to reconfigure the NXP MCUX SDK to suit the Matter application requirements, such as compiler options, linker settings, board-specific files.

The structure of this file can be extended by users and adapted to suit the specific needs of their applications.

To achieve this for a custom application, the former file can be copied under the application environment, modified to suit its requirements, and included in the application CMakeLists.txt.

Note : If the freestanding example was created from an existing Matter example with the west export_app command, a default nxp_sdk_reconfig.cmake exists in the application directory. You can modify this file directly.

Customize the application `prj.conf`#

mcuxsdk/middleware/matter/examples/platform/nxp/config/prj_<flavour>.conf are provided as an example of configuration of the application.

Users can provide their custom prj.conf that could be adapted to their application.

The custom file could either be included in the application CMakeLists.txt by appending its path to the CONF_FILE CMake variable, or by providing the absolute path directly in the west build command line using -DCONF_FILE.

Example :

west build -d build_matter -b frdmrw612 . -DCONF_FILE=/absolute/path/to/prj_custom.conf

Customize SDK middleware configuration#

Matter enablement on NXP platforms defines a set of default mbedtls / PSA configuration files to ensure compatibility with both Matter and platform requirements. These are provided per platform through the following build definitions:
- -DMBEDTLS_CONFIG_FILE=\"nxp_matter_mbedtls_config.h\"
- -DMBEDTLS_PSA_CRYPTO_CONFIG_FILE=\"rw61x_matter_mbedtls_config.h\" (dedicated per platform, rw61x_matter_mbedtls_config.h shown here as an example)
If a particular application requires additional crypto operations, the recommended approach is to define new user configuration files rather than modifying the platform defaults:
- MBEDTLS_USER_CONFIG_FILE
- MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE
- Add the additional flags in these user configuration files and reference them from the application’s dedicated nxp_sdk_reconfig.cmake file.
LWIP_USER_CONFIG_FILE macro may be used by the application to add or override lwIP configurations used by Matter by default.
- This can be done by defining LWIP_USER_CONFIG_FILE macro as the path of the application’s lwIP config file, in the application’s version of nxp_sdk_reconfig.cmake file.
WIFI_USER_CONFIG_FILE macro may be used by the application to add or override Wi-Fi configurations used by Matter by default.
- This can be done by defining WIFI_USER_CONFIG_FILE macro as the path of the application’s WiFi config file, in the application’s version of nxp_sdk_reconfig.cmake file.
FreeRTOS configuration is generated with Kconfig and can be found under <build_directory>/FreeRTOSConfig_Gen.h. The default values of FreeRTOS Kconfig symbols, required by Matter, are defined in mcuxsdk/middleware/matter/third_party/nxp/nxp_matter_support/cmake/<platform>/Kconfig.defconfig. These values can be overridden by the application from the prj.conf, to be adapted to its specific needs.

Customize Matter Device Configuration with ZAP#

A ZAP (ZCL Advanced Platform) configuration file is a template that defines the Matter device’s clusters, endpoints, attributes, and capabilities. ZAP tool is a graphical configuration tool used to configure the .zap file and generate the code files that integrate to the Matter application. We recommend to check the ZAP Intro documentation to learn more about ZAP and how to use the tool.

We provide for each of our Matter examples a template .zap file that can be used as a starting point for customization. When creating a Matter freestanding example the .zap file is also exported.

Using ZAP Tool Script#

You can customize the .zap file with the ZAP tool by following these steps:

# 1. Navigate to your exported application directory:
$ cd ~/Desktop/freestanding_thermostat_app

# 2. Set up or activate your Matter environment
# Note : if the bootstrap was already done, you can run the activate.sh script instead to activate the environment
$ source <path_to_mcuxsdk>/mcuxsdk/middleware/matter/third_party/nxp/nxp_matter_support/scripts/bootstrap.sh <path_to_mcuxsdk>

# 3. Run ZAP tool with the .zap file
$ ./<path_to_mcuxsdk>/mcuxsdk/middleware/matter/scripts/tools/zap/run_zaptool.sh zap/thermostat_matter_wifi.zap

Using ZAP Tool Directly#

Alternatively, you can use the ZAP tool directly (useful for Windows OS). The ZAP executable is at the root where you previously ran the bootstrap.sh script:

# 1. Navigate to your exported application directory:
$ cd ~/Desktop/freestanding_thermostat_app

# 2. Set up or activate your Matter environment
# Note : if the bootstrap was already done, you can run the activate.sh script instead to activate the environment
$ source <path_to_mcuxsdk>/mcuxsdk/middleware/matter/third_party/nxp/nxp_matter_support/scripts/bootstrap.sh <path_to_mcuxsdk>

# 3. Run ZAP tool with required arguments:
$ .zap/zap-<version>/zap zap/thermostat_matter_wifi.zap --zcl <path_to_mcuxsdk>/mcuxsdk/middleware/matter/src/app/zap-templates/zcl/zcl.json --gen <path_to_mcuxsdk>/mcuxsdk/middleware/matter/src/app/zap-templates/app-templates.json

Note: The --zcl and --gen arguments are required because the ZAP files in NXP Matter examples use symbolic links or copied files when exported as freestanding, where the relative paths inside the .zap file are no longer accurate. These arguments ensure that the ZAP tool loads the correct template files. The paths shown above are the default paths for Matter examples - if you plan to customize them for your applications, use your custom paths instead.

This will open the ZAP GUI tool for editing the device configuration. Make your desired changes to clusters, endpoints, and attributes, then save the file. After saving the configuration with the ZAP tool, it will automatically update the paths in the .zap file.

Note: When launching the ZAP tool without a .zap file specified, you may be presented with an interface to select the ZCL metadata and generation templates to use. In this case, make sure to select the templates with “matter” category to ensure compatibility with Matter applications.

Generating Code After ZAP Changes#

After changing the ZAP file, regenerate the .matter file and associated code: :

$ ./<path_to_mcuxsdk>/mcuxsdk/middleware/matter/scripts/tools/zap/generate.py zap/thermostat_matter_wifi.zap --zcl <path_to_mcuxsdk>/mcuxsdk/middleware/matter/src/app/zap-templates/zcl/zcl.json

Note: The --zcl argument is required for generating .matter files to ensure that the correct ZCL templates are used, similar to the reasoning explained above for the ZAP tool.

Finally, rebuild your application to incorporate the changes. See how to build a freestanding example for details.

Updating the Certification Declaration via OTA#

In some use cases a certified product requires a new Certification Declaration (CD) to be embedded in the firmware — for example when the vendor ID, product ID array, or certificate ID changes after an initial certification. This can be achieved by embedding the new CD bytes directly in the OTA update image at build time, without relying on factory data stored in flash.

How it works#

The NXP legacy FactoryDataProvider::GetCertificationDeclaration() implementation checks the compile-time flag CHIP_USE_DEVICE_CONFIG_CERTIFICATION_DECLARATION. When that flag is set to 1, the provider returns the CD bytes defined by CHIP_DEVICE_CONFIG_CERTIFICATION_DECLARATION from the firmware image itself, ignoring any CD stored in the factory data region of flash.

Note: Once CHIP_USE_DEVICE_CONFIG_CERTIFICATION_DECLARATION is set to 1, the CD stored in the factory data flash region is ignored on every boot of that firmware build — not only after an OTA update. Ensure the compile-time CD bytes are correct before shipping the OTA image, as there is no runtime fallback to the flash CD. If the device rolls back to a firmware version without this flag, it will revert to reading the CD from flash.

Step 1 - Create or update the application CHIPProjectConfig.h#

Define both required macros:

/* Enable the use of the compile-time CD bytes instead of flash factory data. */
#define CHIP_USE_DEVICE_CONFIG_CERTIFICATION_DECLARATION 1

/* Replace the byte array below with the DER-encoded CMS SignedData blob of
 * your new Certification Declaration. */
#define CHIP_DEVICE_CONFIG_CERTIFICATION_DECLARATION                           \
    {                                                                          \
        0x30, 0x81, 0xe8, /* ... rest of CD bytes ... */                       \
        0xcc, 0x81, 0xf8, 0x36, 0xfa, 0xdd, 0xd8                              \
    }

To update the CD for a new certification, replace the byte array with the DER-encoded CMS SignedData blob of the new CD obtained from the CSA certification process.

Step 2 - Pass the config file to the build#

CMake build (west)#

Add the -DCONFIG_CHIP_PROJECT_CONFIG argument to the west build command, pointing to the application config header relative to the example source root:

west build -d <build_dir> -b <board> <example_path> -- \
    -DCONFIG_CHIP_PROJECT_CONFIG="<CHIPProjectConfig.h>"

Application Customization

Contents