Application Architecture

Overview

This guide explains the architecture of NXP Matter applications with CMake build system for FreeRTOS platforms, using an in-tree example to illustrate core concepts. It also provides insights into customization options for developers working on out-of-tree applications.

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.

Note: All file paths referenced in this document are relative to the Matter repository root, which is typically installed under mcuxsdk/middleware/matter/ in your NXP MCUX SDK installation.

Application build system architecture

NXP Matter applications rely on two main build systems: GN and CMake. The architecture is designed to streamline the integration and the customization of Matter into different applications.

  • GN build system : GN is used to compile the Matter stack and platform libraries, and generates the CHIP libraries that will be linked to the application.

  • CMake build system : CMake is used to configure and compile the application and the NXP SDK, and link the libraries to generate the final executable. The CMake build system uses Kconfig to configure system options. All related information can be found in NXP MCUX Build And Configuration System.

Matter stack and NXP platform port libraries

Below is a detailed description of CMake/Kconfig files used to generate the Matter stack & NXP port libraries.

  • config/nxp/chip-cmake-freertos/CMakeLists.txt : CMake wrapper which will map CMake configuration on GN configuration and generate the CHIP libraries for NXP FreeRTOS platforms. With this CMake file, Matter can be integrated as an external module of NXP MCUX SDK.

  • config/nxp/cmake/common.cmake : CMake file common to Zephyr and FreeRTOS platforms, used to configure GN arguments based on CMake configuration.

  • config/nxp/chip-cmake-freertos/Kconfig : Kconfig file which defines Matter Kconfig symbols common to NXP FreeRTOS platforms.

  • config/nxp/chip-cmake-freertos/Kconfig.defaults : The role of this Kconfig is to override default values of Kconfig symbols. These values are tuned for Matter requirements.

  • config/nxp/cmake/Kconfig.matter.common : Kconfig file used to define Matter Kconfig symbols common across Matter platforms.

  • config/nxp/cmake/Kconfig.matter.nxp : Kconfig file used to define Matter Kconfig symbols common to NXP platforms.

Application

To describe the CMake architecture for the NXP applications, the thermostat example is provided as a reference application.

  • examples/thermostat/nxp/CMakeLists.txt : Application CMake list file common to NXP FreeRTOS platforms. This CMakeLists.txt is used as the entry-point to build the application.

  • examples/thermostat/nxp/Kconfig : Application Kconfig file used as the entry-point Kconfig. This file can be used to define application specific Kconfig symbols.

  • examples/thermostat/nxp/prj.conf : Application prj.conf used to set or unset Kconfig symbols specific to the application. This file is automatically loaded by the application’s CMakeLists.txt.

  • examples/platform/nxp/common/app_common.cmake : Application CMake file for building files that are common across applications. This file can be included from the application CMakeLists.txt, this will add common application files to the build based on the Kconfig enabled.

  • examples/platform/nxp/common/Kconfig : Application Kconfig file used to define Kconfig symbols common across applications.

  • examples/platform/nxp/config/prj_<flavour>.conf : A custom prj.conf file used to set or unset Kconfig symbols for a specific application configuration. The name of the prj_<flavour>.conf can be provided in the build command line with the -DCONF_FILE_NAME variable, to add the configuration file to the build. To view the full list of supported prj_<flavour>.conf and how to use them, you can refer to the List the project information section.

Overview on application CMakeLists.txt

Below are the key points on how the NXP application CMakeLists.txt is designed. This architecture is common to both in-tree and out-of-tree applications.

  • CHIP libraries are loaded as an external module of the NXP MCUX SDK. This is done by appending to the EXTRA_MCUX_MODULES list the path to the config/nxp/chip-cmake-freertos/CMakeLists.txt. This will enable the build system to automatically load and link the module library to the application.

  • NXP MCUX SDK is loaded by the application using the find_package CMake function, which enables CMake to automatically find the location where the SDK was installed. More information can be found in McuxSDK CMake Package.

  • The application includes examples/platform/nxp/common/app_common.cmake to add common application files.

  • The application includes third_party/nxp/nxp_matter_support/examples/platform/<platform_family>/nxp_sdk_reconfig.cmake. This CMake file is used to reconfigure the SDK to adapt to Matter requirements. In order for it to be correctly processed by CMake, this file must be included before creating the CMake project().

  • When creating the CMake project(), the build system will automatically create the application target app and link Matter libraries and the SDK libraries (McuxSDK) to it.

  • Application source files and include directories are directly added to the target app with target_sources and target_include_directories.