Matter and Zigbee: Light bulb

##

This sample demonstrates a combined Matter and Zigbee application on a single SoC. It implements a Zigbee Dimmable Light (Router) and a Matter Dimmable Light endpoint that serves the On/Off and Level Control clusters and drives the same LED through PWM.

You can use this sample with the Network coordinator and Light switch samples from the Zigbee R23 add-on to set up a basic Zigbee network, or pair it directly with the Matter and Zigbee: Light switch using Touchlink commissioning.

The ZBOSS stack and OpenThread (used by Matter) share the same 802.15.4 radio between the ZBOSS stack and OpenThread. For Thread networking in Matter mode, the light bulb acts as an OpenThread Full Thread Device (FTD).

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

Developing with nRF54L Series

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp

Developing with nRF54L Series

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

To test this sample, you also need to program the following samples:

Alternatively, if both light bulb and light switch devices support Touchlink, you can use it for Zigbee commissioning without a Zigbee Coordinator.

Overview

The sample-specific behavior is:

  • On first boot, the device starts on the protocol selected by CONFIG_MATTER_ZIGBEE_PROTOCOL_STATE_DEFAULT_PROTOCOL (Zigbee by default). When Zigbee is active, it is a standard Zigbee Router exposing the Dimmable Light device, while the Matter stack advertises for commissioning over Bluetooth LE (CHIPoBLE).

  • After successful Matter commissioning, the device is converted to a Matter Dimmable Light endpoint that serves the On/Off and Level Control clusters and drives the same LED through PWM. It can then be controlled by any device on the Matter fabric bound to it (for example, the Matter and Zigbee: Light switch).

  • On subsequent boots, the device resumes the persisted protocol. When Matter was selected, it starts directly as a Matter Dimmable Light. A Matter factory reset resets the persisted protocol to the configured default and wipes Matter commissioning data.

The radio hand-over, persistent protocol state, user-triggered protocol switch, factory-reset behavior and onboarding-data generation are common to both combined samples and are described in detail in the Matter and Zigbee: Light switch documentation.

Limitations

The combined Matter and Zigbee application has the following limitations:

  • The 802.15.4 radio is time-shared, never concurrent: once the device runs on Matter, Zigbee is torn down until the active protocol changes again. To switch back to Zigbee, ensure the CONFIG_MATTER_ZIGBEE_COEXISTENCE_BUTTON_SWITCH Kconfig option is enabled, then long-press the button. Removing all Matter fabrics or triggering a Matter factory reset wipes Matter storage and resets the persisted protocol to the value selected by the CONFIG_MATTER_ZIGBEE_PROTOCOL_STATE_DEFAULT_PROTOCOL Kconfig option.

  • The memory footprint is tuned empirically for nrf54lm20dk/nrf54lm20a/cpuapp and nrf54lm20dk/nrf54lm20b/cpuapp; porting to other targets requires revisiting the libc heap, ZBOSS thread, system work queue and partition sizes used by prj.conf.

Configuration

See Configuring and building in the nRF Connect SDK documentation for information about how to permanently or temporarily change the configuration.

Source file setup

This sample is split into the following source files:

  • The main file is the application entry point only.

  • The app_task_zigbee file manages the application task flow, user input handling, and Zigbee-specific startup and control logic. It also implements the dimmable light device behavior, including cluster handling and PWM-based brightness control.

  • The app_task_matter file implements the Matter application task flow, button input, and On/Off and Level Control cluster state for the dimmable light endpoint.

Build variants

The sample provides predefined configuration files in the samples/light_bulb directory.

The samples in this add-on are combined Matter and Zigbee builds by default. The default prj.conf enables Matter (CONFIG_CHIP), the CONFIG_MATTER_ZIGBEE_COEXISTENCE orchestration layer, and the matching static partition layout with the MCUboot secondary slot in internal RRAM.

west build samples/light_bulb -b nrf54l15dk/nrf54l15/cpuapp --sysbuild

The same configuration is supported on nrf54lm20dk/nrf54lm20a/cpuapp and nrf54lm20dk/nrf54lm20b/cpuapp.

On the nRF54L15 DK, the combined Matter and Zigbee image requires external flash for the MCUboot secondary slot due to the available internal slot size. To place the MCUboot secondary slot on external SPI NOR flash instead, pass the ext_flash snippet.

west build samples/light_bulb -b nrf54l15dk/nrf54l15/cpuapp -S ext_flash --sysbuild
west build samples/light_bulb -b nrf54lm20dk/nrf54lm20a/cpuapp -S ext_flash --sysbuild

To produce a size-optimized release build (no logging, console or shell), add release.conf as an extra overlay:

west build samples/light_bulb -b nrf54l15dk/nrf54l15/cpuapp -S ext_flash --sysbuild -DEXTRA_CONF_FILE='release.conf'

Use nrf54lm20dk/nrf54lm20b/cpuapp as the board target for the nRF54LM20B SoC variant.

Over-the-air firmware upgrade

You can update your device’s firmware over the air using three methods.

  • Matter OTA – Updates your device through MCUboot, satisfying the Matter specification’s requirement to support at least one over-the-air software update method. Enable it with the SB_CONFIG_MATTER_OTA sysbuild Kconfig option, which sets CONFIG_CHIP_OTA_REQUESTOR on the application image. Both options are enabled by default when building with sysbuild.

  • Zigbee Firmware-Over-the-Air (FOTA) - Updates the device over the Zigbee network using the Zigbee Cluster Library (ZCL) OTA upgrade cluster. MCUboot then applies the downloaded image. Enable this feature with the CONFIG_ZIGBEE_FOTA Kconfig option or by using the dedicated zigbee_fota.conf configuration file. The feature is disabled by default.

  • Device Firmware Upgrade (DFU) over Bluetooth LE - Updates the device using the Simple Management Protocol (SMP). Enable this feature with the CONFIG_CHIP_DFU_OVER_BT_SMP Kconfig option. The feature is disabled by default in Kconfig but enabled for this sample through its prj.conf file.

Matter OTA, Zigbee FOTA, and SMP DFU are independent transports. SMP is not part of the Matter specification. Use mcumgr or nRF Connect Device Manager to perform SMP updates. For Zigbee FOTA, use an OTA Upgrade Server on the network, or see the Zigbee FOTA library documentation in the Zigbee R23 add-on.

For step-by-step instructions on testing the update process, see Testing DFU over Bluetooth SMP.

See Limitations for supported board targets and incompatible options.

For the board name to use instead of the board_target, see Programming board names.

See Providing CMake options in the nRF Connect SDK documentation for instructions on how to add flags to your build.

User interface

All the Matter and Zigbee combined samples share button and status-LED handling through the matter_zigbee_ui library (include/matter_zigbee_ui_config.h). Sample-specific buttons and LEDs are defined in each sample’s include/app_ui_config.h.

The descriptions below apply while the device runs either protocol. Sample-specific controls are active only for the persisted active protocol (see the sample overview).

LED 0 (Matter):

Matter connectivity and commissioning readiness.

  • Matter active: Solid on when the device is provisioned on Thread. Slow blink while waiting for commissioning; fast blink while a Bluetooth LE commissioning connection is active.

  • Zigbee active: Off when Matter is already provisioned. Otherwise mirrors Bluetooth LE commissioning advertising (slow or fast blink) so you can commission over CHIPoBLE while Zigbee owns the 802.15.4 radio.

LED 1 (Zigbee):

Zigbee network status when Zigbee is the active protocol.

  • Off when Matter is active.

  • Blinks while Zigbee is active but not joined to a network (even when paired using Zigbee touchlink)

  • Solid on when joined.

LED 2 (Identify):

Blinks during Identify mode (Zigbee Identify cluster or Matter Identify cluster / TriggerEffect).

Button 0:

Multiplexed factory reset and (optionally) SMP DFU entry.

  • Short press (when CONFIG_MATTER_ZIGBEE_UI_SMP_DFU is enabled): Starts Bluetooth LE advertising for SMP firmware update. If the device is not commissioned to a Matter fabric, Matter commissioning advertising is started as well; if already commissioned, only the SMP server is enabled.

  • Long press — factory reset:

    • Zigbee active: Uses the Zigbee application utilities factory-reset gesture on Button 0 (CONFIG_FACTORY_RESET_PRESS_TIME_SECONDS from the Zigbee R23 add-on).

    • Matter active: Two-step gesture on Button 0 controlled by CONFIG_MATTER_ZIGBEE_UI_FACTORY_RESET_PRESS_TIME_SECONDS (5 s by default): hold for the first half of the timeout, then either release to cancel or keep pressed through the cancel window to confirm.

Button 1:

Long press (when CONFIG_MATTER_ZIGBEE_COEXISTENCE_BUTTON_SWITCH is enabled): Switches the active protocol after CONFIG_MATTER_ZIGBEE_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS (5 s by default). Ignored during Zigbee join or Matter commissioning.

Button 3:

Zigbee active: Short press and release toggles local Identify mode (LED 2 blinks).

Matter active: Identify is driven by the Matter Identify cluster (controller or binding peer); Button 3 is not used for local identify.

Sample-specific (light bulb)

LED 3:

Both Matter and Zigbee: Main light output (PWM when CONFIG_PWM is enabled). Reflects on/off and brightness from Zigbee Level Control / On/Off clusters or from Matter On/Off and Level Control clusters.

Button 2:

Matter active: Short press toggles locally the main light (LED 3). Zigbee active: Not used for light control (use the light switch or another Zigbee controller).

Building and running

Make sure the Zigbee R23 add-on is included in your workspace and configured before building and testing this sample.

This sample can be found under samples/light_bulb in the Matter and Zigbee add-on folder structure.

To build the sample, follow the instructions in Building an application in the nRF Connect SDK documentation for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the Matter and Zigbee add-on which is an SDK repository, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing

After programming the sample to your development kits, complete the following steps to test basic Zigbee operation:

  1. Turn on the development kit that runs the Network coordinator sample.

    When LED 2 turns on, this development kit has become the Coordinator of the Zigbee network and the network is established.

  2. Turn on the development kit that runs the Light bulb sample.

    When LED 1 turns on, the light bulb has become a Router inside the network.

    Note

    If LED 1 does not turn on, press Button 0 on the Coordinator to reopen the network.

  3. Turn on the development kit that runs the Light switch sample.

    When LED 1 turns on, the light switch has become an End Device, connected directly to the Coordinator.

  4. Wait until LED 3 on the development kit that runs the Light switch sample turns on.

    This LED indicates that the switch found a light bulb to control.

  5. Use the buttons on the development kit that runs the Matter and Zigbee: Light switch to control the light bulb.

    The result of using the buttons is reflected on the light bulb’s LED 3.

Testing the full Zigbee-to-Matter flow

To test the full combined application flow, you need:

  • A light bulb built as described in Build variants.

  • A Zigbee test setup to verify Zigbee operation before Matter commissioning. You can use either the standard setup (a Network coordinator and a Zigbee light switch) or, alternatively, only a Touchlink-capable light switch (for example, the Matter and Zigbee: Light switch), in which case the Zigbee Coordinator is not needed.

  • A Matter controller that can commission a Thread device over Bluetooth LE, for example CHIP Tool or an ecosystem app (Apple Home, Google Home, Amazon Alexa).

  • A Thread Border Router reachable by the Matter fabric.

  • Optionally, a Matter switch on the same Thread fabric to be bound to the light bulb (for example, the Matter and Zigbee: Light switch).

Complete the following steps:

  1. Verify Zigbee operation in one of the following ways:

    • Follow the standard Testing procedure with a Zigbee Network coordinator and a Zigbee light switch.

    • Or, skip the Zigbee Coordinator and pair the light bulb directly with a Touchlink-capable light switch:

      1. Power the light bulb (Touchlink target).

      2. Power the light switch and press its Touchlink button (see Touchlink commissioning). The two devices form a distributed-security Zigbee network without a Zigbee Coordinator, and the light switch finds and controls the light bulb.

    While the device is still a Zigbee Router, it also advertises for Matter commissioning over Bluetooth LE.

  2. Optionally, long-press Button 1 for CONFIG_MATTER_ZIGBEE_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS to switch to Matter. The Zigbee stack is stopped and the radio is handed to OpenThread. Skip the next step if you use this path and Matter was already commissioned in a previous session.

  3. Commission the device using the onboarding payload produced by the Matter factory data build (QR code or manual pairing code). After the Matter CASE session is established, the light bulb hands the radio over to Thread and stops participating in the Zigbee network.

  4. Drive the light bulb from a Matter peer:

    • From the controller directly, with chip-tool onoff toggle … or chip-tool levelcontrol move-to-level ….

    • Or by binding a Matter switch to the light bulb and using the switch’s dimmer button.

  5. To return the device to Zigbee operation, use one of the following:

    • Long-press Button 1 for CONFIG_MATTER_ZIGBEE_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS. The device reboots and resumes as a Zigbee Router.

    • Or trigger a Matter factory reset from the controller (for example, chip-tool pairing unpair …). The device reboots as a fresh Zigbee Router with Matter Bluetooth LE advertising active again, and Matter storage is cleared.

Testing DFU over Bluetooth SMP

To test DFU over Bluetooth LE SMP, complete the following steps:

  1. Build and flash the sample (see Build variants).

  2. Confirm the device is running the Matter stack (see Testing).

  3. Briefly press Button 0 to start Bluetooth LE advertising for SMP.

    The behavior depends on the device’s commissioning state:

    • If the device is not commissioned to a Matter fabric, this starts both Matter commissioning advertising and the SMP server.

    • If the device is already commissioned, this re-enables only the SMP server for firmware transfer. Firmware transfer over SMP works with both Matter and Zigbee.

    On the Matter and Zigbee: Light switch and matter_zigbee_light_bulb_sample, Button 0 also activates factory reset, when pressed for few seconds (5 s by default). Make sure to short click to start Bluetooth LE advertising for SMP and to avoid accidentally performing a factory reset.

    LED 0 blinks while Bluetooth LE advertising for SMP is active. The advertised device name is MatterZigbeeLb, set by the CONFIG_BT_DEVICE_NAME Kconfig option in the prj.conf file.

  4. Perform the update using one of the following methods:

    1. Install nRF Connect Device Manager.

    2. Use the dfu_application.zip file from the build directory.

    For detailed instructions, see FOTA updates on nRF54L Series devices.

After the update completes, MCUboot applies the new image on the next reboot.

Dependencies

This sample uses the following nRF Connect SDK libraries and components:

  • The Matter stack (CONFIG_CHIP) shipped with the nRF Connect SDK, including the On/Off, Level Control and Identify clusters and the Matter factory data module.

  • OpenThread (used by Matter on 802.15.4) and the SoftDevice Controller (used for CHIPoBLE commissioning).

  • The matter_zigbee_coexistence and matter_zigbee_protocol_state libraries, which orchestrate the 802.15.4 radio hand-over and persist the selected protocol.

  • The nrf_802154_callbacks_dispatcher (CONFIG_NRF_802154_CALLBACKS_DISPATCHER) with runtime re-init (CONFIG_NRF_802154_DRV_REINIT_ENABLED).

  • The Zigbee R23 add-on for ZBOSS stack support, Zigbee application utilities, and error handling.

  • DK Buttons and LEDs

  • Pulse Width Modulation (PWM)