Bluetooth mesh: Light dimmer and scene selector

The Bluetooth® mesh light dimmer and scene selector sample demonstrates how to set up a light dimmer and scene selector application, and control dimmable LEDs with Bluetooth mesh using the Generic Level models, the Generic OnOff models, and the Scene models. The sample provides the following functionality:

  • On/off and dim up/down using one button

  • Scene recall/store of light levels with a second button

This sample demonstrates how to implement the following Networked Lighting Control profiles:

  • Dimming Control NLC Profile

  • Basic Scene Selector NLC Profile

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

Thingy:53

PCA20053

thingy53_nrf5340

thingy53_nrf5340_cpuapp

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns nrf5340dk_nrf5340_cpuapp

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52833 DK

PCA10100

nrf52833dk_nrf52833

nrf52833dk_nrf52833

nRF21540 DK

PCA10112

nrf21540dk_nrf52840

nrf21540dk_nrf52840

The sample also requires a smartphone with Nordic Semiconductor’s nRF Mesh mobile app installed in one of the following versions:

Note

If you build this application for Thingy:53, it enables additional features. See Thingy:53 application guide for details.

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Overview

This sample can be used to control the state of light sources. In addition to the on/off functionality, it allows changing the light level (brightness) of an LED light, and storing and recalling scenes of light levels. To display any functionality, the sample must be paired with a device with the mesh light fixture sample running in the same mesh network.

The sample instantiates the following models:

Devices are nodes with a provisionee role in a mesh network. Provisioning is performed using the nRF Mesh mobile app. This mobile application is also used to configure key bindings, and publication and subscription settings of the Bluetooth mesh model instances in the sample. After provisioning and configuring the mesh models supported by the sample in the nRF Mesh mobile app, Button 1 on the Mesh Light Dimmer device can be used to control the configured network nodes’ LEDs, while Button 2 can be used to store and restore scenes on the network nodes.

Note

When running this sample on a Thingy:53, the scene selection functionality will not be available as the device only has one button. The Thingy:53’s single button will have the dimming and on/off functionality as described for Button 1 in this documentation.

Provisioning

The provisioning is handled by the Bluetooth mesh provisioning handler for Nordic DKs. It supports four types of out-of-band (OOB) authentication methods, and uses the Hardware Information driver to generate a deterministic UUID to uniquely represent the device.

Models

The following table shows the composition data for the light dimmer sample:

Element 1

Config Server

Health Server

Gen. Level Client

Gen. OnOff Client

Scene Client

The models are used for the following purposes:

  • The first element contains a Config Server and a Health Server. The Config Server allows configurator devices to configure the node remotely. The Health Server provides attention callbacks that are used during provisioning to call your attention to the device. These callbacks trigger blinking of the LEDs.

  • The third model in the first element is the Generic Level Client. The Generic Level Client controls the Generic Level Server in the target devices, deciding on parameters such as fade time and lighting level.

  • The fourth model is the Generic OnOff Client which controls the Generic OnOff Server in the target devices, setting the LED state to ON or OFF.

  • The last model is the Scene Client which controls the Scene Server in the target devices, storing or restoring scenes of the current LED states.

The model handling is implemented in src/model_handler.c, which uses the DK Buttons and LEDs library to control the buttons on the development kit.

User interface

Buttons:

Can be used to input the out-of-band (OOB) authentication value during provisioning. All buttons have the same functionality during this procedure.

Button 1:

On press and release, Button 1 will publish a Generic OnOff Set message using the configured publication parameters of its model instance, and toggle the LED on/off on a mesh light fixture device.

On press and hold, Button 1 will publish a Generic Level move set message using the configured publication parameters of its model instance and will continuously dim the LED lightness state on a mesh light fixture device. On release, the button publishes another Generic Level move set message with the delta parameter set to 0 and stops the continuous level change from the previous message.

Button 2:

On short press and release, Button 2 will publish a Scene Restore message using the configured publication parameters of its model instance, and restore the LED state of all the targets to the values stored under the current scene number. Each press of the button will recall the next scene, meaning, the first press will recall scene 2, the next press will recall scene 3, and so on, before wrapping around back to scene 1.

On long press and release, Button 2 will publish a Scene Store message using the configured publication parameters of its model instance, and store the current LED state of all the targets under the scene with the most recently recalled scene number.

LEDs:

Show the OOB authentication value during provisioning if the “Push button” OOB method is used.

Note

Thingy:53 supports only one RGB LED. Each RGB LED channel is used as separate LED.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

For nRF5340 and Thingy:53, the extended advertiser has to be set manually for the network core, because the Bluetooth® Low Energy does not know that the Bluetooth mesh is enabled when built for this core. This is already done for this sample by setting CONFIG_BT_EXT_ADV=y for the network core.

Source file setup

This sample is split into the following source files:

  • A main.c file to handle initialization.

  • A file for handling mesh models, model_handler.c.

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 FEM is connected to the nRF5 SoC in your device. See Set devicetree overlays 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 SHIELD=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 IDE 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 nRF Connect for VS Code extension pack 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 nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Working with RF 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.

Building and running

This sample can be found under samples/bluetooth/mesh/light_dimmer in the nRF Connect SDK folder structure.

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, you can test it by using a smartphone with nRF Mesh mobile app installed. Testing consists of provisioning the device and configuring it for communication with the mesh models.

Provisioning the device

The provisioning assigns an address range to the device, and adds it to the mesh network. Complete the following steps in the nRF Mesh app:

  1. Tap Add node to start scanning for unprovisioned mesh devices.

  2. Select the Mesh Light Dimmer device to connect to it.

  3. Tap Identify, and then Provision, to provision the device.

  4. When prompted, select an OOB method and follow the instructions in the app.

Once the provisioning is complete, the app returns to the Network screen.

Configuring models

See Configuring mesh models using the nRF Mesh mobile app for details on how to configure the mesh models with the nRF Mesh mobile app.

Configure the first element on the Mesh Light Dimmer node:

  • Bind the following models to Application Key 1: Generic Level Client, Generic OnOff Client and Scene Client.

  • Configure the publication for all models to the same group. This can be any group.

Configure the first element on the target Mesh Light Fixture node:

  • Bind the following models to Application Key 1: Generic Level Server, Generic OnOff Server, Scene Server, and Scene Setup Server.

  • Subscribe all models to the same group as set for publication for the Mesh Light Dimmer.

You should now be able to perform the following actions:

  • Press and release Button 1 to see the LED on the target Mesh Light Fixture device toggle on and off.

  • Press and hold Button 1 to see the light level of the LED on the target Mesh Light Fixture device slowly decrease or increase.

  • Short press and release Button 2 to rotate through scenes, recalling each of them in turn.

  • Long press and release Button 2 to store the current LED states as a scene with the current scene number.

Note

When controlling a Mesh Light Fixture device using the Mesh Light Dimmer device, the Light LC Server control will be temporarily disabled for the Mesh Light Fixture device. The control will be re-enabled after a certain time which can be configured using the CONFIG_BT_MESH_LIGHT_CTRL_SRV_TIME_MANUAL option.

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following Zephyr libraries:

The sample also uses the following secure firmware component: