Dimming examples

nRF5 SDK for Mesh v5.0.0
You can test this example on the following devices: nRF52840, nRF52833, and nRF52832.
This example is not compatible with the nRF52810 and nRF52820 devices.

This example demonstrates the interaction between a Bluetooth mesh dimmable light and a dimmer. The mesh dimmer controls the brightness of the mesh dimmable light. The example consists of two minor examples:

  • Dimming server
  • Dimming client

Both these minor examples use the Generic Level Client/Server model.

For provisioning purposes, the example requires either the provisioner example that is provided in the Provisioner example or the nRF Mesh mobile app.

Table of contents

Dimming client

The dimming client has a provisionee role in the network. The client accepts RTT inputs from 1 to 7 to control the state of LED 1 on the servers. It instantiates two instances of the Generic Level Client model. It can either be provisioned and configured by the provisioner device or by a GATT-based provisioner. The provisioner configures this client model instances to communicate with the servers.

Dimming server

The dimming server has a provisionee role in the network. It instantiates one instance of the Generic Level Server model to control the state of LED 1. It uses the nRF5 SDK's APP_PWM library, which is controlled by the lightness value and which controls the brightness of the LED. It can either be provisioned and configured by the provisioner device or by a GATT-based provisioner. The provisioner configures this server model instance to communicate with the client model on the client board and to publish a message when the value of the Level state changes.

The examples are based on the Generic Level model, which works with signed 16-bit level values. Therefore, the dimming server maps this range on the allowed range of PWM tick values. As a consequence, sending a level model message that sets the target level to 0x0000 results in a 50% duty cycle on the PWM output when the target level is reached.

Scene model

The dimming server example implements one instance of the Scene Setup Server model and the associated root Default Transition Time Server model. The Scene Setup Server instance can be used together with the Scene Client, although both model instances are optional and can be excluded.

For the value stored and recalled by the Scene model, see the Bluetooth Mesh Model Specification (MshMDLv1.0.1), Table 3.87. For more information on how to use the Scene models, see the Scene example.

The Default Transition Time Server instance can be used only when evaluating the example using mobile app.

Generic Level Client/Server model

The Generic Level Client model is used for manipulating the Level state associated with peer Generic Level Server model.

Note
When the server has a publish address set (as in this example), the server publishes information about the state changes to its publish address once the final state is reached.

More information about the Generic Level model can be found in the Generic Level model documentation and the Generic Level server behaviour documentation.

Hardware requirements

You need at least two compatible development kits for this example:

  • One compatible development kit for the client.
  • One or more compatible development kits for the servers.

Additionally, you need one of the following for provisioning:

See Compatibility for information about the compatible development kits.

Software requirements

Depending on the provisioning method:

Setup

You can find the source code of this example in the following folder: <InstallFolder>/examples/dimming

LED and button assignments

  • Provisioner:
    • Button 1: Start provisioning.
    • LED 1: Reflects the state of the provisioning.
      • LED ON: Provisioning of the node is in progress.
      • LED OFF: No ongoing provisioning process.
    • LED 2: Reflects the state of the configuration.
      • LED ON: Configuration of the node is in progress.
      • LED OFF: No ongoing configuration process.
  • Dimming client:
    • When interacting with the boards, you can use one of the following options:
      • RTT input (recommended): Due to limited number of buttons on the DK board, use RTT input when evaluating this example.
        RTT inputs DK Buttons Effect
        1 Button 1 The internal target level variable value is decreased in large steps and Generic Level Set message is sent.
        2 Button 2 The internal target level variable value is increased in large steps and Generic Level Set message is sent.
        3 Button 3 The internal target delta level variable value is decreased in large steps and Generic Level Delta Set message is sent.
        4 Button 4 The internal target delta level variable value is increased in large steps and Generic Level Delta Set message is sent.
        5 - The internal target move level variable value is decreased in large steps and Generic Level Move Set message is sent.
        6 - The internal target move level variable value is increased in large steps and Generic Level Move Set message is sent.
        7 - The client switches between Odd or Even group nodes.
      • Buttons: If you decide use the buttons on the DK instead of the RTT input, you can only send Set and Delta Set messages. You cannot send Move message or switch between Odd or Even groups.
  • Dimming server:
    • When interacting with the boards:
      • You cannot use buttons on the server boards since dimming server does not use the simple_hal module.
      • Use the following RTT input:
        RTT inputs DK Buttons Effect
        1 - The lightness value for LED 1 (and its brightness) is decreased in large step.
        2 - The lightness value for LED 1 (and its brightness) is increased in large step.
        4 - Clear all the states to reset the node.

        Scene model integration

Scene Setup Server model instance is used by default by this example. You can exclude it by setting SCENE_SETUP_SERVER_INSTANCES_MAX to 0 (from the default value of 1) in examples/dimming/dimming_server/include/nrf_mesh_config_app.h.

If you decide to exclude the Scene Setup Server model instance, exclude it also from the Provisioner example if you want to evaluate using the static provisioner.

Testing the example

To test the dimming example, build the examples by following the instructions in Building the Bluetooth mesh stack.

After building is complete, use one of the following methods, depending on the preferred provisioning approach:

Evaluating using the static provisioner

See provisioner example testing section for detailed steps required to provision and configure the boards using the static provisioner.

Evaluating using the nRF Mesh mobile app

See Evaluating examples using the nRF Mesh mobile application for detailed steps required to provision and configure the boards using the nRF Mesh mobile app.

When using the nRF Mesh app with this example, the following naming convention is used in the app:

  • The server board is nRF5x Mesh Dimmable Light.
  • The client board is nRF5x Mesh Dimmer.

The following model instances must be configured in the app for this example:

  • For the nRF5x Mesh Dimmable Light server board:
  • For the nRF5x Mesh Dimmer client board: Generic Level Client.

Interacting with the boards

When provisioning and configuration of the client node and at least one of the server nodes are complete, you can send command numbers using the RTT viewer and see the dimming action on the LED 1 on each of the server boards.

To evaluate this interaction, connect the RTT viewer to the dimming client.

There are three message types available for this demonstration:

  • Set
  • Delta Set
  • Move Set

Dimming client interaction
The RTT input is used to emulate the button numbers 1 to 7 to send level messages. You can send numbers from 1 to 7 via the RTT viewer and observe the changes in the brightness of the LED 1 on the corresponding server boards.

See the LED and button assignments for the list of available commands.

Dimming-server interaction
See the LED and button assignments for the list of available commands.

If you send the commands to the server board, observe the corresponding status printed in the RTT log of the client board.

If any of the devices are powered off and back on, they remember their configuration in flash and rejoin the network. For more information about the flash manager, see Flash manager.