Zigbee: Light switch

Note

Support for Zigbee R22 has been deprecated in nRF Connect SDK v2.8.0 and it will be removed in one of the future releases, following the deprecation policy. As a result, the nRF52833, nRF52840 and nRF5340 SoCs are not recommended for new Zigbee designs. Experimental support for Zigbee R23 is available for the nRF54L Series as an nRF Connect SDK Add-on.

You can use the Zigbee Light switch sample to change the state of light sources on other devices within the same Zigbee network.

You can use it together with the Zigbee Network coordinator and the Zigbee Light bulb samples to set up a basic Zigbee network.

This sample supports the optional Sleepy End Device behavior and Multiprotocol Bluetooth LE extension. It also supports Zigbee FOTA. See Configuration files for sample extensions for details about how to enable these variants.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpuapp

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

nRF52833 DK

PCA10100

nrf52833dk

nrf52833dk/nrf52833

nRF21540 DK

PCA10112

nrf21540dk

nrf21540dk/nrf52840

You can use one or more of the development kits listed above and mix different development kits.

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

Multiprotocol Bluetooth LE extension requirements

If you enable the Multiprotocol Bluetooth LE extension, make sure you have a phone or a tablet with the nRF Toolbox application installed.

Note

The Testing instructions refer to nRF Toolbox, but you can also use similar applications, for example nRF Connect for Mobile.

Overview

The Light switch sample demonstrates the Zigbee End Device role and implements the Dimmer Switch device specification, as defined in the Zigbee Home Automation public application profile.

Once the light switch is successfully commissioned, it sends a broadcast message to find devices with the implemented Level Control and On/Off clusters. The light switch remembers the device network address from the first response. At this point, you can start using the buttons on the development kit to control the clusters on the newly found devices.

Additionally, the light switch sample powers down unused RAM sections to lower power consumption in the sleep state.

Sleepy End Device behavior

The light switch supports the Sleepy End Device behavior that enables the sleepy behavior for the end device, for a significant conservation of energy.

To enable the sleepy behavior, press Button 3 while the light switch sample is booting. This is required only when device is joining the network for the first time. After restarting the device, it will boot with the sleepy behavior enabled.

Multiprotocol Bluetooth LE extension

This optional extension demonstrates dynamic concurrent switching between two protocols, Bluetooth® LE and Zigbee. It uses the Nordic UART Service (NUS) library.

When this extension is enabled, you can use:

  • Buttons on the light switch device to operate on the Zigbee network

  • Nordic UART Service to operate on the Bluetooth LE network

Both networks are independent from each other.

To support both protocols at the same time, the Zigbee stack uses the IEEE 802.15.4 radio during the inactive time of the Bluetooth LE radio (using the Timeslot API of the Multiprotocol Service Layer). Depending on the Bluetooth LE connection interval, the nRF52 development kits can spend up to 99% of the radio time on the Zigbee protocol.

Transmitting and receiving data when using this example does not break connection from any of the used radio protocols, either Bluetooth LE or Zigbee.

For more information about the multiprotocol feature, see Multiprotocol support.

Configuration

See Configuring and building 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 to handle initialization and light switch basic behavior.

  • An additional nus_cmd file for handling NUS commands.

Configuration files for sample extensions

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

Activating optional extensions

To activate the Zigbee FOTA, use the prj_fota.conf configuration file. For example, when building from the command line, use the following command:

west build samples/zigbee/light_switch -b nrf52840dk/nrf52840 -- -DFILE_SUFFIX=fota

Alternatively, you can configure Zigbee FOTA manually.

Note

You can use the prj_fota.conf file only with a development kit that contains the nRF52840 or nRF5340 SoC.

To activate the Multiprotocol Bluetooth LE extension, set EXTRA_CONF_FILE to the overlay-multiprotocol_ble.conf. For example, when building from the command line, use the following command:

west build samples/zigbee/light_switch -b nrf52840dk/nrf52840 -- -DEXTRA_CONF_FILE='overlay-multiprotocol_ble.conf'

For the board name to use instead of the nrf52840dk/nrf52840, see Board names.

See Providing CMake options for instructions on how to add flags to your build. For more information about configuration files in the nRF Connect SDK, see Build and configuration system.

FEM support

You can add support for the nRF21540 front-end module to this sample by using one of the following options, depending on your hardware:

  • Build the sample for one board that contains the nRF21540 FEM, such as nrf21540dk/nrf52840.

  • Manually create a devicetree overlay file that describes how the nRF21540 FEM is connected to the SoC. See Configuring devicetree for different ways of adding the overlay file.

  • Provide nRF21540 FEM capabilities by using a shield, for example the nRF21540 EK shield that is available in the nRF Connect SDK. In this case, build the project for a board connected to the shield you are using with an appropriate variable included in the build command, for example -DSHIELD=nrf21540ek. This variable instructs the build system to append the appropriate devicetree overlay file.

    To build the sample in the nRF Connect for VS Code extension for an nRF52840 DK with the nRF21540 EK attached, add the shield variable in the build configuration’s Extra CMake arguments and rebuild the build configuration. For example: -DSHIELD=nrf21540ek.

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

    See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example the nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Developing with Front-End Modules for more information about FEM in the nRF Connect SDK.

To add support for other front-end modules, add the respective devicetree file entries to the board devicetree file or the devicetree overlay file.

Configurable transmission power

To achieve a lower power consumption of the light switch, you can configure the transmission power using the CONFIG_LIGHT_SWITCH_CONFIGURE_TX_POWER Kconfig option. You can select per-channel transmission power (in dBm) with the CONFIG_LIGHT_SWITCH_TX_POWER Kconfig option. This affects to all frames sent by the device, even in the network scan phase.

Note

The CONFIG_LIGHT_SWITCH_CONFIGURE_TX_POWER Kconfig option is enabled by default and this sample’s transmission power is set to 0 dBm.

When the CONFIG_ZIGBEE_CHANNEL_SELECTION_MODE_MULTI Kconfig option is set to y, the CONFIG_ZIGBEE_APP_CB_QUEUE_LENGTH Kconfig option must be increased depending on the channel mask. For example, in case 16 channels are active, a proper value for CONFIG_ZIGBEE_APP_CB_QUEUE_LENGTH would be 17. Similar consideration applies to the ZB_CONFIG_IOBUF_POOL_SIZE and ZB_CONFIG_SCHEDULER_Q_SIZE values configured in the include/zb_mem_config_custom.h file.

User interface

LED 3:

Lit and solid when the device is connected to a Zigbee network.

LED 4:

Lit and solid when the light switch has found a light bulb to control.

Button 1:

When the light bulb is turned off, turn it back on.

Pressing this button for a longer period of time increases the brightness of the light bulb.

Button 2:

Turn off the light bulb connected to the network (light bulb’s LED 4). This option is available after the successful commissioning (light switch’s LED 3 turned on).

Pressing this button for a longer period of time decreases the brightness of the LED 4 of the connected light bulb.

Button 4:

When 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.

Note

If the brightness level is at the minimum level, you may not notice the effect of turning on the light bulb.

FOTA behavior assignments

LED 2:

Indicates the OTA activity. Used only if the FOTA support is enabled.

Sleepy End Device behavior assignments

Button 3:

When pressed while resetting the kit, enables the Sleepy End Device behavior.

Multiprotocol Bluetooth LE extension assignments

LED 1:

Lit and solid when a Bluetooth LE Central is connected to the NUS service. Available when using Nordic UART Service (NUS) in the multiprotocol configuration.

UART command assignments:

The following command assignments are configured and used in nRF Toolbox when Testing multiprotocol Bluetooth LE extension:

  • n - Turn on the Zigbee Light bulb.

  • f - Turn off the Zigbee Light bulb.

  • t - Toggle the Zigbee Light bulb on or off.

  • i - Increase the brightness level of the Zigbee Light bulb.

  • d - Decrease the brightness level of the Zigbee Light bulb.

If more than one light bulb is available in the network, these commands apply to all light bulbs in the network. See Testing multiprotocol Bluetooth LE extension for details.

Building and running

Make sure to configure the Zigbee stack before building and testing this sample. See Configuring Zigbee in nRF Connect SDK for more information.

This sample can be found under samples/zigbee/light_switch in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application 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 SDK repositories, 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 3 turns on, this development kit has become the Coordinator of the Zigbee network.

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

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

    Note

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

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

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

  4. Wait until LED 4 on the light switch node turns on.

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

You can now use buttons on the development kit to control the light bulb, as described in User interface.

Testing multiprotocol Bluetooth LE extension

To test the multiprotocol Bluetooth LE extension, complete the following steps after the standard Testing procedure:

  1. Set up nRF Toolbox by completing the following steps:

    Tap UART to open the UART application in nRF Toolbox.

    UART application in nRF Toolbox

    UART application in nRF Toolbox

  2. In nRF Toolbox, tap the buttons you assigned:

    1. Tap the n and f command buttons to turn the LED on the Zigbee Light bulb node on and off, respectively.

    2. Tap the t command button two times to toggle the LED on the Zigbee Light bulb node on and off.

    3. Tap the i and d command buttons to make adjustments to the brightness level.

You can now control the devices either with the buttons on the development kits or with the NUS UART command buttons in the nRF Toolbox application.

Sample output

You can observe the sample logging output through a serial port after connecting with a terminal emulator (for example, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

Dependencies

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib libraries:

In addition, it uses the following Zephyr libraries:

  • include/zephyr.h

  • include/device.h

  • Logging

The following dependencies are added by the multiprotocol Bluetooth LE extension: