Migrating Matter projects from sdk-nrf to Matter add-on
The nRF Connect SDK v3.4.0 was the last major release with Matter samples, shared sample code, board partition devicetree files, and Matter-specific snippets integrated in the sdk-nrf repository.
In later releases, the Matter reference applications and their supporting assets are maintained in the separate Matter add-on repository (ncs-matter).
This guide describes the changes required when migrating a Matter project that was based on paths under sdk-nrf to the ncs-matter add-on structure.
It covers workspace setup, repository layout, build system updates, Kconfig symbol renames, devicetree and snippet changes, and documentation references.
Note
If you only use Matter samples without custom modifications, the simplest approach is to create a new workspace from the ncs-matter add-on and copy over your application-specific source files, configuration overlays, and factory data.
Use this guide when you maintain a custom Matter application that was forked from an nRF Connect SDK v3.4.0 (or earlier) Matter sample or application.
Overview
The ncs-matter add-on is a Zephyr module that extends the nRF Connect SDK with:
Matter reference samples (formerly under
nrf/samples/matter)Matter bridge and weather station reference applications (formerly under
nrf/applications, now underncs-matter/samples)Shared Matter sample infrastructure (formerly under
nrf/samples/matter/common, now underncs-matter/subsys)Matter partition devicetree include files (formerly under
nrf/dts/samples/matter, now underncs-matter/dts)Matter build and data-model CMake helpers (formerly under
nrf/samples/matter/common/cmake, now underncs-matter/cmake)Matter-specific Zephyr snippets (formerly under
nrf/snippets/matter, now underncs-matter/snippets)
The add-on manifest (ncs-matter/west.yml) imports a fixed nRF Connect SDK release together with the matching sdk-connectedhomeip revision.
Setting up the workspace
To work with Matter samples and applications from the add-on, set up a west workspace that includes the ncs-matter repository.
Initialize from the add-on manifest
Complete the following steps to create a new workspace with the Matter Add-on as the manifest repository:
west init -m https://github.com/nrfconnect/ncs-matter --mr <release>
cd ncs-matter
west update
Replace <release> with the add-on release tag that matches your target nRF Connect SDK version (see the add-on release notes).
Alternatively, if you already cloned the add-on repository locally:
west config manifest.path ncs-matter
west update
To get back to the nRF Connect SDK manifest, run:
west config manifest.path nrf
west update
Building Matter samples
Build commands must point to sample paths under the add-on repository. The board target and sysbuild configuration options remain the same as in the nRF Connect SDK Matter samples.
For example, to build the Matter template sample for the nrf54l15dk/nrf54l15/cpuapp board target:
west build -b nrf54l15dk/nrf54l15/cpuapp ncs-matter/samples/template
Compare this with the former path:
west build -b nrf54l15dk/nrf54l15/cpuapp nrf/samples/matter/template
You can also create a workspace application by copying a sample from ncs-matter/samples/ into your workspace application folder.
Follow the instructions in Creating application from add-ons for add-on based application creation in nRF Connect for VS Code.
Repository layout changes
The repository layout has been changed in comparison to the nRF Connect SDK repository structure. See the following sections to learn about the changes.
Sample and application paths
All Matter reference code moves from sdk-nrf to ncs-matter.
The matter subdirectory is removed from sample paths, and former applications are relocated under ncs-matter/samples/.
Former path in |
New path in |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Devicetree partition files
Base Matter partition layouts move from nrf/dts/samples/matter/ to ncs-matter/dts/.
The add-on registers this directory as a devicetree root (dts_root in zephyr/module.yml), so partition files are included by filename only.
Former include in board overlay |
New include in board overlay |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Update every board-specific .overlay file in your project that references the old samples/matter/ devicetree path.
Snippets
Matter snippets move from nrf/snippets/matter/ to ncs-matter/snippets/.
Snippet names are shortened because the add-on registers ncs-matter/snippets as a snippet root.
Former snippet path |
Former snippet name |
New snippet name |
|---|---|---|
|
|
|
|
|
|
Update build commands and sample.yaml definitions that reference the old snippet names.
For example, replace template_SNIPPET="matter-diagnostic-logs;matter-debug" with template_SNIPPET="diagnostic-logs;debug".
Build system changes
To align the Matter Add-on with the nRF Connect SDK build system, the CMake, Sysbuild and Kconfig files have been created. The Zephyr module configuration points to the new files instead of the alternatives in the nRF Connect SDK repository.
CMake updates
Replace references to ZEPHYR_NRF_MODULE_DIR Matter sample paths with ZEPHYR_NCS_MATTER_MODULE_DIR add-on paths.
In application CMakeLists.txt files, make the following changes:
Remove the explicit
enable-gnu-std.cmakeinclude. GNU standard support is enabled globally by the add-on module (ncs-matter/CMakeLists.txt).Replace separate includes of
source_common.cmake,data_model.cmake, andzap_helpers.cmakewith a single include ofsample.cmake:# Before (sdk-nrf) include(${ZEPHYR_CONNECTEDHOMEIP_MODULE_DIR}/config/nrfconnect/app/enable-gnu-std.cmake) include(${ZEPHYR_NRF_MODULE_DIR}/samples/matter/common/cmake/source_common.cmake) include(${ZEPHYR_NRF_MODULE_DIR}/samples/matter/common/cmake/data_model.cmake) include(${ZEPHYR_NRF_MODULE_DIR}/samples/matter/common/cmake/zap_helpers.cmake) # After (ncs-matter add-on) include(${ZEPHYR_NCS_MATTER_MODULE_DIR}/cmake/sample.cmake)
Update explicit source file paths. For example, in the Matter bridge application, replace:
${ZEPHYR_NRF_MODULE_DIR}/samples/matter/common/src/binding/binding_handler.cpp
with:
${ZEPHYR_NCS_MATTER_MODULE_DIR}/subsys/binding/binding_handler.cpp
The shared Matter sample sources under ncs-matter/subsys/ are linked automatically for all applications that enable CONFIG_CHIP through the add-on module CMake entry point.
You no longer need to include source_common.cmake manually unless you have a non-standard build layout.
Kconfig updates
Removed the following line from sample Kconfig files:
source "$(ZEPHYR_NRF_MODULE_DIR)/samples/matter/common/src/Kconfig"
The add-on Kconfig tree (ncs-matter/Kconfig and ncs-matter/subsys/Kconfig) is loaded automatically when the ncs-matter Zephyr module is present in the workspace.
Kconfig symbol renames
All CONFIG_NCS_SAMPLE_MATTER_* options are renamed to CONFIG_MATTER_* in the add-on.
Update every prj.conf, prj_release.conf, *.conf overlay, and sample.yaml reference.
Former symbol ( |
New symbol ( |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Removed Kconfig options
The following options from nrf/samples/matter/common/src/Kconfig are no longer available in the add-on:
CONFIG_NCS_SAMPLE_MATTER_ZAP_GENERATION_STATICCONFIG_NCS_SAMPLE_MATTER_ZAP_GENERATION_BUILD_TIME
The add-on uses pre-generated ZAP output checked into each sample’s src/default_zap/zap-generated/ directory.
Regenerate ZAP files using the Matter west commands documented in the add-on tooling section.
Sysbuild configuration
Matter samples in the add-on use a sysbuild_internal.conf file at the sample root to hold sysbuild image options that were previously embedded in sample-specific sysbuild configuration.
If your custom project relied on the same sysbuild defaults (for example, MCUboot overwrite-only mode with compressed image support), copy the relevant options from the corresponding add-on sample’s sysbuild_internal.conf file.
The add-on sysbuild Kconfig (ncs-matter/sysbuild/Kconfig.sysbuild) disables the Partition Manager globally for Matter builds, consistent with the devicetree-based partitioning introduced in nRF Connect SDK v3.4.0.
See also Matter for partition migration details that still apply after moving to the add-on.
Documentation and tooling
Documentation
Matter sample documentation, getting started guides, and protocol documentation that previously lived under nrf/doc/nrf/protocols/matter/ and nrf/doc/nrf/samples/matter.rst are published from the ncs-matter add-on documentation set.
After migrating your project, use the add-on documentation as the primary reference for building, configuring, and testing Matter samples.
The nRF Connect SDK documentation retains high-level Matter integration information and links to the add-on, similar to how Zigbee samples references the Zigbee add-on repositories.
Note
Documentation cross-references that use the |sample path| substitution now point to paths under ncs-matter/samples/ instead of nrf/samples/matter/.
Update any custom documentation or internal wikis that hard-code the old paths.
Validation scripts
If you use the Matter sample validation tooling locally, switch to the add-on copy under ncs-matter/scripts/matter_sample_checker/.
The checker configuration expects the add-on directory layout - for example, partition #include directives without the samples/matter/ prefix, and snippet paths under ncs-matter/snippets/.
West ZAP tooling
The Matter west extension commands (west zap-gui, west zap-generate, and related commands) remain part of the Connected Home IP module in the nRF Connect SDK.
When working in an add-on workspace, make sure your ZAP_INSTALL_PATH environment variable is set and run west commands from the workspace root that contains both ncs-matter and modules/lib/matter.
What remains in sdk-nrf
The following Matter-related components stay in the core nRF Connect SDK (sdk-nrf and imported modules):
The Connected Home IP stack itself (
modules/lib/matter, imported throughsdk-nrf)Matter Kconfig and GN integration under
modules/lib/matter/config/nrfconnect/Shared nRF Connect SDK infrastructure used by Matter (OpenThread, MCUboot integration, IPC radio, factory data generation in
sdk-nrf)Core nRF Connect SDK documentation links and software maturity information for Matter platform features
Only the Matter reference samples, their shared sample code, snippets, and partition devicetree assets move to ncs-matter.
Migration checklist
Use this checklist when migrating a custom Matter application:
Set up a west workspace that includes the
ncs-matteradd-on at a release matching your target nRF Connect SDK version.Move or copy your application sources to a path under your workspace (or use an add-on sample as the new base).
Update
CMakeLists.txt:Include
ncs-matter/cmake/sample.cmakeinstead of the formersamples/matter/common/cmake/*files.Replace
ZEPHYR_NRF_MODULE_DIRMatter paths withZEPHYR_NCS_MATTER_MODULE_DIR.
Update
Kconfigfiles: remove thesamples/matter/common/src/Kconfigsource line.Rename all
CONFIG_NCS_SAMPLE_MATTER_*symbols toCONFIG_MATTER_*in configuration files.Update devicetree board overlays: replace
#include <samples/matter/...>with#include <...>using the filenames fromncs-matter/dts/.Update snippet names in build commands (
matter-debug→debug,matter-diagnostic-logs→diagnostic-logs).Update
west buildpaths to point to the new sample location.Copy or merge
sysbuild_internal.confdefaults from the matching add-on sample if needed.Rebuild from a pristine build directory and verify commissioning, DFU, and factory data workflows.