Matter All-Devices App for Zephyr#

The All-Devices App is a Matter application for Zephyr. It uses the Matter code-driven data model and can contain one or more device types. The enabled device types are selected at build time. The default device is an on/off light.

Setup#

1. Install GN#

Matter’s build uses GN. Either download a binary from https://chrome-infra-packages.appspot.com/p/gn/gn and put it in your PATH, or build it from source:

git clone https://gn.googlesource.com/gn ~/gn
cd ~/gn
python3 build/gen.py
ninja -C out gn
install -m 755 out/gn /usr/local/bin

2. Set up Zephyr#

Follow the generic Zephyr setup:

https://docs.zephyrproject.org/latest/develop/getting_started/index.html

3. Add Matter to the West workspace#

Matter ships a zephyr/module.yml at its repository root, so it is a Zephyr module: add it to the manifest of your west workspace and Zephyr registers it as the module connectedhomeip and builds it.

Create ~/zephyrproject/zephyr/submanifests/matter.yaml:

manifest:
    projects:
        - name: matter
          url: https://github.com/project-chip/connectedhomeip
          revision: master
          path: modules/lib/matter
          submodules:
              - path: third_party/editline/repo
              - path: third_party/jsoncpp/repo
              - path: third_party/nlassert/repo
              - path: third_party/nlio/repo
              - path: third_party/uriparser/repo
              - path: third_party/pigweed/repo

west update

4. Stub `pigweed_environment.gni`#

build_overrides/pigweed_environment.gni is generated by Matter’s own scripts/activate.sh/bootstrap.sh. That bootstrap is never run in the Zephyr/west-only workflow. As a workaround, create a minimal stub manually:

echo > ~/zephyrproject/modules/lib/matter/build_overrides/pigweed_environment.gni

Build#

Within the west workspace, build the app with West and sysbuild:

west build -p always -b xg26_rb4118a --sysbuild \
	modules/lib/matter/examples/all-devices-app/zephyr \
	-d build/all-devices-zephyr-xg26 -- -DUSE_CCACHE=0

Flash the resulting images with:

west flash -d build/all-devices-zephyr-xg26

The app supports MCUboot through Zephyr sysbuild. For debugging, use west debug. Use west attach when debugging an image that is already signed.

OTA is supported through the Matter OTA Requestor and the Zephyr platform OTA integration.

Build Profiles#

prj.conf is applied by default. Select another profile with FILE_SUFFIX:

# Debug profile
west build ... -- -DFILE_SUFFIX=debug

# Release profile
west build ... -- -DFILE_SUFFIX=release

Network Transport Selection#

The application builds a Matter root node with exactly one operational network transport: Wi-Fi or Thread. BLE is used for commissioning in both cases (CONFIG_BT=y by default).

Matter’s Wi-Fi support does not follow Zephyr’s CONFIG_WIFI automatically. Select the transport explicitly, and set both options so the result does not depend on platform or vendor defaults:

Transport	Matter / Zephyr options	Board requirements
Wi-Fi	`CONFIG_CHIP_WIFI=y` `CONFIG_NET_L2_OPENTHREAD=n`	A Zephyr Wi-Fi driver for the board (`CONFIG_WIFI=y` and its driver)
Thread	`CONFIG_NET_L2_OPENTHREAD=y` `CONFIG_CHIP_WIFI=n`	An IEEE 802.15.4 radio (`zephyr,ieee802154` chosen node) or a vendor RCP

CONFIG_NET_L2_OPENTHREAD selects CONFIG_OPENTHREAD, which enables Matter’s Thread support. The OpenThread device type defaults to FTD (CONFIG_OPENTHREAD_FTD).

Supported combinations:

`CONFIG_CHIP_WIFI`	`CONFIG_NET_L2_OPENTHREAD`	Result
y	n	Wi-Fi root node
n	y	Thread root node
y	y	Not supported (build error: Thread + Wi-Fi root node)
n	n	Not supported (build error: no network technology enabled)

Ethernet-only (CONFIG_CHIP_ETHERNET) is not supported by this application.

Put the options in a .conf file and pass it with EXTRA_CONF_FILE, for example:

west build ... -- -DEXTRA_CONF_FILE=my_thread.conf

Device Selection#

Device types are Kconfig options (CONFIG_ALL_DEVICES_DEVICE_*, see Kconfig.devices). Pick them in menuconfig under “Matter device types”, or in a .conf file:

CONFIG_ALL_DEVICES_DEVICE_ON_OFF_LIGHT=y
CONFIG_ALL_DEVICES_DEVICE_OCCUPANCY_SENSOR=y

The CMake variable still overrides Kconfig when set:

west build ... -- \
	-DALL_DEVICES_ENABLED_DEVICES="on-off-light;occupancy-sensor"

An empty list (-DALL_DEVICES_ENABLED_DEVICES="", or no device selected in Kconfig) enables every device type.

Factory Data#

Vendor boards can provide factory data through a custom AppTask (see Custom AppTask). For example, NXP boards use boards/nxp/NxpAppTask.h, which registers the NXP factory data providers. To read the device attestation credentials and commissionable data from the factory_partition, build with:

west build ... -- -DEXTRA_CONF_FILE="nxp/prj_fdata.conf;nxp/frdm_rw612_fdata.conf"

Factory Reset#

Press and hold button 0 for 5 seconds to factory reset the device. Button 0 is defined as sw0 in a board overlay.

Custom AppTask#

AppTaskBase<Derived> uses CRTP: Run() dispatches each init step through the final type, so a product replaces a step by declaring a method of the same name. Layers can stack (generic -> vendor -> product) as long as the chain ends in a non-template AppTask.

#include "AppTaskBase.h"

namespace chip::app::AllDevices {

template <class Derived>
class MyAppTask : public AppTaskBase<Derived>
{
public:
    CHIP_ERROR InitCredentials(); // replaces the generic step
};

class AppTask final : public MyAppTask<AppTask>
{
};

} // namespace chip::app::AllDevices

Point APP_TASK_IMPL_HEADER at that header:

west build ... -- -DAPP_TASK_IMPL_HEADER=MyAppTask.h

Call AppTaskBase<Derived>::Step() to also run the generic behavior.

Matter All-Devices App for Zephyr

Contents