Zigbee: Light bulb

This sample demonstrates a simple light bulb whose brightness can be adjusted by another device.

You can use this sample with the Zigbee Network coordinator and Zigbee Light switch samples to set up a basic Zigbee network.

As a proof of concept, the sample also supports the optional Matter extension, which lets the same firmware start as a Zigbee Router and migrate to a Matter Dimmable Light after Matter commissioning. This combined Matter build also enables Touchlink target support, so it can be commissioned by a nearby Touchlink initiator without a Zigbee Coordinator on the network.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Board target

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

nRF5340 DK

PCA10095

nrf5340dk
nrf5340dk/nrf5340/cpuapp

nRF54L10 emulation on the nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l10/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

nRF54LM20 DK

PCA10184

nrf54lm20dk
nrf54lm20dk/nrf54lm20a/cpuapp
nrf54lm20dk/nrf54lm20b/cpuapp

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

Overview

The Zigbee light bulb sample takes the Zigbee Router role and implements the Dimmable Light device specification, as defined in the Zigbee Home Automation public application profile. This profile allows changing the brightness level of the light bulb’s LED.

Matter extension

This optional extension is a proof of concept of a combined Matter and Zigbee build on a single SoC, sharing the 802.15.4 radio between the ZBOSS stack and OpenThread (used by Matter). For Thread networking in Matter mode, the light bulb acts as an OpenThread Full Thread Device (FTD). It is supported on the nrf54l15dk/nrf54l15/cpuapp, nrf54lm20dk/nrf54lm20a/cpuapp and nrf54lm20dk/nrf54lm20b/cpuapp board targets.

The sample-specific behavior is:

  • On first boot, the device starts on the protocol selected by CONFIG_ZIGBEE_MATTER_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 Zigbee: Light switch built with the Matter extension).

  • 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 extension section of the Light switch sample.

Matter extension limitations

As a proof of concept, the Matter extension 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_ZIGBEE_MATTER_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_ZIGBEE_MATTER_PROTOCOL_STATE_DEFAULT_PROTOCOL Kconfig option.* The Matter extension cannot be combined with the Multiprotocol Bluetooth LE extension (overlay-multiprotocol_ble.conf) or with the Zigbee-only FOTA build (FILE_SUFFIX=fota).

  • You cannot combine the Matter extension with the Multiprotocol Bluetooth LE extension (overlay-multiprotocol_ble.conf) or with the Zigbee-only FOTA build (FILE_SUFFIX=fota).

  • 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_matter_fota.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 is used in the Matter extension build only. It implements the Matter application task flow, button input, and On/Off and Level Control cluster state for the dimmable light endpoint.

Configuration files for sample extensions

The sample provides predefined configuration files for optional extensions. You can find the configuration files in the samples/light_bulb directory.

Activating optional extensions

To activate the Zigbee FOTA, use the prj_fota.conf configuration file together with the zigbee_fota_ext_flash snippet. The snippet provides external-flash partition layouts, sysbuild MCUboot settings, and the matching MCUboot configuration (through zigbee_fota_mcuboot_ext_flash). For example, when building from the command line, use the following command:

west build samples/light_bulb -b board_target -- -DFILE_SUFFIX=fota -DSNIPPET=zigbee_fota_ext_flash

The FOTA variant enables MCUboot image compression. The generated Zigbee update file contains a compressed MCUboot image, and MCUboot decompresses it while applying the update. This setting reduces the size of the update image. However, it requires MCUboot to run in overwrite-only mode, which means the device cannot revert to the previous image after an update is applied.

Alternatively, you can configure Zigbee FOTA manually.

Note

The decompression support increases the size of the MCUboot image. When adapting this FOTA configuration to a custom board or application, make sure that the MCUboot partition is large enough for the generated bootloader image. The FOTA variant uses devicetree-based partitioning with Partition Manager disabled; see Upgrading Zigbee application for the partition layout requirements.

Device firmware upgrade over Bluetooth SMP (Zigbee-only builds)

To additionally enable Device Firmware Upgrade (DFU) over Bluetooth LE using the Simple Management Protocol (SMP) in a Zigbee-only build, add CONFIG_ZIGBEE_BT_DFU=y to the FOTA build command:

west build samples/light_bulb -b board_target -- -DFILE_SUFFIX=fota -DSNIPPET=zigbee_fota_ext_flash -DCONFIG_ZIGBEE_BT_DFU=y

This option enables the MCUmgr SMP server over Bluetooth LE alongside Zigbee FOTA. It cannot be combined with the Matter extension (CONFIG_CHIP). For Matter extension builds, SMP DFU is provided through CONFIG_CHIP_DFU_OVER_BT_SMP instead.

See Testing Zigbee FOTA DFU over Bluetooth SMP for step-by-step testing instructions.

To activate the Matter extension, build the sample with FILE_SUFFIX=matter_fota. This selects the prj_matter_fota.conf configuration, which enables Matter (CONFIG_CHIP), the CONFIG_ZIGBEE_MATTER_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 -- -DFILE_SUFFIX=matter_fota

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

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

west build samples/light_bulb -b nrf54l15dk/nrf54l15/cpuapp -S matter_fota_ext_flash -- -DFILE_SUFFIX=matter_fota
west build samples/light_bulb -b nrf54lm20dk/nrf54lm20a/cpuapp -S matter_fota_ext_flash -- -DFILE_SUFFIX=matter_fota

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

west build samples/light_bulb -b nrf54l15dk/nrf54l15/cpuapp -S matter_fota_ext_flash -- -DFILE_SUFFIX=matter_fota -DEXTRA_CONF_FILE='matter_fota_release.conf'

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

Device firmware upgrade over Bluetooth SMP

You can update your device’s firmware over the air using two methods, both enabled by default in the Matter extension builds:

  • Matter OTA – Updates your device through MCUboot, satisfying the Matter specification’s requirement to support at least one over-the-air software update method.

  • Device Firmware Upgrade (DFU) over Bluetooth LE – Updates your device using the Simple Management Protocol (SMP). To enable this method, select the prj_matter_fota.conf configuration by setting the FILE_SUFFIX=matter_fota option.

Matter OTA and SMP DFU are independent transports. SMP is not part of the Matter specification. Use mcumgr or nRF Connect Device Manager to perform the update.

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

See Matter extension limitations for supported board targets and incompatible options.

User interface

LED 0:

Blinks to indicate that the main application thread is running.

LED 1:

Indicates the dimmable light option, that is changes to the light bulb brightness. It can be controlled by another Zigbee device in the network, for example a light switch. Blinks when the light bulb is in Identify mode.

LED 2:

Turns on when the light bulb joins the network.

Button 2:

If CONFIG_ZIGBEE_MATTER_COEXISTENCE_BUTTON_SWITCH is enabled (default), it triggers a protocol switch after a long press (CONFIG_ZIGBEE_MATTER_COEXISTENCE_SWITCH_BUTTON_PRESS_TIME_SECONDS, 5 s by default).

Button 3:

Depending on how long the button is pressed:

  • If pressed for less than five seconds, it starts or cancels the Identify mode.

  • If pressed for five seconds, it initiates the factory reset of the device. The length of the button press can be edited using the CONFIG_FACTORY_RESET_PRESS_TIME_SECONDS Kconfig option from Zigbee application utilities. Releasing the button within this time does not trigger the factory reset procedure.

Building and running

Make sure to configure the Zigbee stack before building and testing this sample. See Configuring Zigbee R23 add-on for more information.

This sample can be found under samples/light_bulb in the Zigbee R23 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 Zigbee R23 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 it:

  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 2 turns on, the light bulb has become a Router inside the network.

    Note

    If LED 2 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 2 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 Zigbee: Light switch sample to control the light bulb.

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

You can now use buttons on the light switch to control the light bulb, as described in the User interface section of the Light switch sample page.

Testing the Matter extension

See Matter extension for the runtime behavior driving the steps below.

To test the extension, you need:

  • A light bulb built with the Matter extension (see Configuration files for sample extensions).

  • 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 Zigbee: Light switch built with the Matter extension), 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 Zigbee: Light switch built with the Matter extension).

Complete the following steps to exercise the full Zigbee-to-Matter flow:

  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 2 for CONFIG_ZIGBEE_MATTER_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 2 for CONFIG_ZIGBEE_MATTER_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 Matter extension DFU over Bluetooth SMP

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

  1. Build and flash the sample with the Matter extension (see Configuration files for sample extensions).

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

  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.

    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_matter_fota.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 (nRF54L15 and nRF54LM20 DKs) or FOTA updates with nRF5340 DK (nRF5340 DK) depending on the device you are using.

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

Testing Zigbee FOTA DFU over Bluetooth SMP

To test DFU over Bluetooth SMP in a Zigbee-only build, complete the following steps:

  1. Build and flash the sample with the CONFIG_ZIGBEE_BT_DFU=y Kconfig option (see Configuration files for sample extensions).

  2. Wait for the device to boot.

    After booting, the device automatically starts Bluetooth LE connectable advertising for the SMP server. The advertised device name is Zigbee_Bulb, set by CONFIG_BT_DEVICE_NAME when CONFIG_ZIGBEE_BT_DFU is enabled.

  3. 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 (nRF54L15 and nRF54LM20 DKs) or FOTA updates with nRF5340 DK (nRF5340 DK).

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

Note

Zigbee OTA and SMP DFU are independent transports, and SMP is not part of the Zigbee specification. You can use either mcumgr or nRF Connect Device Manager to perform the update over Bluetooth LE.

Dependencies

This sample uses the following nRF Connect SDK libraries:

It uses the ZBOSS stack:

In addition, it uses the following Zephyr libraries:

If you are using the optional Matter extension, this sample requires the following dependencies:

  • 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 zigbee_matter_coexistence and zigbee_matter_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).