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, please refer to the Matter Zephyr documentation.

Prerequisites

Before customizing Matter applications, ensure you have :

Create 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 will export the selected Matter example to the specified destination path, copy the necessary files to be customized by the user, and will update 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

The exported application will be located at ~/Desktop/freestanding_thermostat_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 specfic 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 will already exist 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

  • MBEDTLS_USER_CONFIG_FILE macro may be used by the application to add or override MbedTLS configurations defined by default.

    • This can be done by defining MBEDTLS_USER_CONFIG_FILE macro as the path of the application’s MbedTLS config file, in the application’s version of nxp_sdk_reconfig.cmake file.

    • To ensure proper functionality, the application’s MbedTLS user configuration file needs to include the necessary mbedtls macros for Matter. This can be achieved by adding #include "nxp_matter_mbedtls_config.h" in the user config file and ensuring that the include path for the mcuxsdk/middleware/matter/third_party/nxp/nxp_matter_support/gn_build/mbedtls/config/nxp_matter_mbedtls_config.h is correctly set.

  • 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, which are 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 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 located 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 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 making changes in 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 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.