Migration notes for Matter add-on v2.0.0

This document describes changes required or recommended for migrating your Matter application from Matter add-on v1.0.0 to v2.0.0.

Required changes

The following changes are mandatory to make your application work in the same way as in previous releases.

Build-time ZAP code generation

The Matter add-on samples no longer include pre-generated ZAP output under zap-generated/ in the sample source tree. By default, ZAP artifacts are generated automatically during the build.

The default Kconfig option is CONFIG_MATTER_ZAP_GENERATION_BUILD_TIME. No other source changes are required when you adopt this mode.

Important

On the first build of a sample, the build system downloads and installs the ZAP tool into the Matter SDK .zap-install directory. This happens automatically when CONFIG_MATTER_ZAP_CLI_INSTALL_PATH is empty and zap-cli is not already available on PATH. The download runs once for each Matter SDK revision. Later builds reuse the installed tool.

You can provide zap-cli in one of the following ways:

• Leave both PATH and CONFIG_MATTER_ZAP_CLI_INSTALL_PATH unset and let the build system install ZAP automatically (recommended for most users).

• Add the Matter SDK .zap-install directory to PATH before building.

• Set CONFIG_MATTER_ZAP_CLI_INSTALL_PATH to the directory that contains zap-cli.

nRF Connect for VS Code extensionCommand line

Build the application as usual. On the first build, the build system downloads and installs the ZAP tool automatically. No extra configuration is required.

See How to work with build configurations in the nRF Connect for VS Code extension documentation for more information.

nRF Connect for VS Code extensionCommand line

Before building, add the Matter SDK .zap-install directory to PATH in the terminal session used by the extension, then build the application as usual.

export PATH="${ZEPHYR_BASE}/../modules/lib/matter/.zap-install:${PATH}"

Alternatively, add the same export to your shell startup file so it applies to every nRF Connect for VS Code extension terminal session.

nRF Connect for VS Code extensionCommand line

Add CONFIG_MATTER_ZAP_CLI_INSTALL_PATH to the build configuration’s Extra CMake arguments, pointing to the directory that contains zap-cli. Rebuild the configuration after adding the argument.

See How to work with build configurations in the nRF Connect for VS Code extension documentation for more information.

Recommended changes

The following changes are not mandatory, but improve your workflow when migrating.

Continue using the legacy static ZAP workflow

If you prefer to keep generating ZAP output manually and checking it into your project, select the legacy mode in Kconfig:

• Set CONFIG_MATTER_ZAP_GENERATION_STATIC to y.

Apart from this Kconfig change, your existing workflow stays the same. You still generate C++ files with the Matter west commands described on the Matter west commands page:

• zap-gui command - Edit the .zap file.

• zap-generate command - Generate the zap-generated/ directory.

nRF Connect for VS Code extensionCommand line

1. Open the Kconfig configuration for your build configuration.

2. Search for MATTER_ZAP_GENERATION and enable CONFIG_MATTER_ZAP_GENERATION_STATIC.

3. Rebuild the application.

4. After editing the .zap file, open a terminal with the toolchain environment and run:

   west zap-generate
   

The generated files are written to zap-generated/ directory next to the .zap file unless you pass the --output parameter.

Note

When using static generation, you are responsible for re-running west zap-generate after every change in the .zap file and for keeping the generated files in version control.

Remove checked-in zap-generated/ directories

If you switch to build-time generation, delete any zap-generated/ directories from your application source tree. They are recreated in the build directory during compilation and no longer need to be stored in the repository.