nRF5 SDK for Mesh v4.1.0
Light CTL example
This example is not supported by the nRF52810 SoC.

This example demonstrates how you can use mesh messages and events from the Light CTL models API to implement a tunable white light.

The example is composed of three minor examples that use the Light CTL client and server models:

For more information about the Light CTL Client/Server models, see the Mesh Model Overview from Bluetooth SIG.

For provisioning purposes, the example requires either the provisioner example or the nRF Mesh mobile app.

All the minor examples have the provisionee role in the network. They support provisioning over Advertising bearer (PB-ADV) and GATT bearer (PB-GATT) and also support Mesh Proxy Service (Server). Read more about the Proxy feature in GATT provisioning and Proxy.

Table of contents

Light CTL Client example

The Light CTL Client example has a provisionee role in the network. It implements two instances of the Light CTL Client model. These instances are used to control the brightness of the LEDs on the servers, the range of supported CTL temperature levels, and the CTL lightness, temperature, and delta UV values after the servers' boot-up.

Light CTL Server example

The Light CTL Server example has a provisionee role in the network. It implements one instance of the Light CTL Setup Server model, and Light Lightness Setup Server model. These instances in-turn initialize other necessary models.

The Light Lightness Server model is used by Light CTL Server to control the lightness value. The Light CTL Server model is used to receive the lightness, temperature and delta UV values. The received values are used to demonstrate a tunable white light by means of the two LEDs on the DK board. The LED 1 represents a warm light, while LED 2 represents a cool white light. These two LEDs are controlled with different PWM duty cycles corresponding to the given color temperature. Also, the overall light output is scaled by the given lightness level to achieve dimming. The photometrically accurate implementation of the tunable white light is out of scope of this example.

The model instance uses the APP_PWM library from the nRF5 SDK to control the brightness of the LEDs. To demonstrate a tunable white light, the lightness and the temperature values are converted to appropriate brightness level for each LED. These are then converted to the generic level values to map them to the PWM tick values for each LED.

ctl_example_structure.svg
Light CTL example structure

Light CTL Server and Light LC Server example

The Light CTL Server and Light LC Server example has a provisionee role in the network. It implements one instance of the Light CTL Setup Server model, a Light LC Setup Server model, and other necessary models in such a way that Light LC server is able to control the lightness output. This shows how a tunable white light can be implemented to have a feature of automated lighting control.

The Light CTL Server model instance is used to receive the CTL lightness, temperature, and delta UV values and change the brightness and color temperature of the lights. The LC model adds the capability for automated lightness control handled by the LC FSM and PI regulator, based on predefined settings and sensor inputs. Refer to Light LC server example for information about how a Light LC server works.

The hardware interface of this example is similar to the Light CTL Server example.

Light CTL models

The Light CTL Client model is used for manipulating the following states associated with the peer Light CTL Server, Light CTL Setup Server, and Light CTL Temperature Server models:

Note
The Light CTL Lightness is bound with Light Lightness Actual state. The received Light Lightness state value is represented in the form of Light CTL Lightness value as a result of this binding.

More information about the Light CTL models can be found in the Light CTL models documentation.

Hardware requirements

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

Additionally, you need one development kit for the provisioner if you decide to use the static provisioner example. For details, see software requirements.

See Compatibility for the supported kits.

Note
This example uses the PWM peripheral to control the brightness of the LEDs. For this reason, it cannot be run on nRF51 devices.

Software requirements

Depending on your choice of the provisioning method:

Setup

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

If you decide to use the static provisioner example, you need the provisioner example: <InstallFolder>/examples/provisioner

See the Provisioner example page for more information about the provisioner example.

If you decide to provision using the mobile application, you need to download and install nRF Mesh mobile app (available for iOS and Android).

LED and button assignments

Testing the example

To test the light CTL example, build the examples by following the instructions in Building the mesh stack.

Using 40+ servers with static provisioner
If you have more than 40 boards for the servers and decided to use the static provisioner example:
  1. Set MAX_PROVISIONEE_NUMBER (in example_network_config.h) to the number of boards available.
  2. Rebuild the provisioner example.
  3. Set MAX_AVAILABLE_SERVER_NODE_NUMBER in nrf_mesh_config_app.h of the client example to the value set for MAX_PROVISIONEE_NUMBER.
Note
The Mesh Model Specification mentions that the default value of the mode of the light controller should be set to (0x0). This means that the light controller is turned off by default. To enable the light controller, the Light LC Client model is used. However, this SDK does not provide the Light LC Client example. For this reason, in this example the light controller is switched on by default. This has been done by changing the default value of the LIGHT_LC_DEFAULT_MODE in nrf_mesh_config_app.h to (0x1).

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

Evaluating using the static provisioner

Complete the following steps:

  1. Flash the examples by following the instructions in Running examples, including:
    1. Erase the flash of your development boards and program the SoftDevice.
    2. Flash the provisioner and the client firmware on individual boards and the server firmware on other boards.
  2. After the reset at the end of the flashing process, press Button 1 on the provisioner board to start the provisioning process:
    1. The provisioner provisions and configures the client and assigns the address 0x100 to the client node.
    2. The two instances of the Light Lightnes client models are instantiated on separate secondary elements. For this reason, they get consecutive addresses starting with 0x101.
    3. The provisioner also provisions and configures the servers at random. It assigns them consecutive addresses starting with 0x601 for Light CTL servers and with 0x701 for Light CTL Server with Light LC servers, and adds them to odd and even groups.
      Note
      - The sequence of provisioned devices depends on the sequence of received unprovisioned beacons.
      - You can use RTT viewer to view the RTT output generated by the provisioner. The provisioner prints details about the provisioning and the configuration process in the RTT log.
  3. Observe that the LED 1 on the provisioner board is turned on when provisioner is scanning and provisioning a device.
  4. Observe that the LED 2 on the provisioner board is turned on when configuration procedure is in progress.
  5. Wait until LED 1 on the provisioner board remains lit steadily for a few seconds, which indicates that all available boards have been provisioned and configured.

If the provisioner encounters an error during the provisioning or configuration process for a certain node, you can reset the provisioner to restart this process for that node.

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.

The following naming convention is used in the app:

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

Note
The Light CTL Client example allows to control the Light CTL states. For this purpose, it is enough to configure only the Light CTL Setup Server and Light CTL Server model instances. If you want to see how the binding works between the Light CTL Lightness states and the Generic states, configure the Generic models instantiated in the server examples and use the appropriate clients to control the generic states.

Once the provisioning is complete, you can start interacting with the boards.

Note
You can also configure the publish address of the second Light CTL client model instance. To do this, repeat step 3 from binding nodes and all steps from setting publication.

Interacting with the boards

Once the provisioning and the configuration of the client node and of at least one of the server nodes are complete, you can press buttons on the client or send command numbers using the RTT Viewer to observe the changes in the brightness and emulated color temperature of the LEDs on the corresponding server boards.

There is a set of message types available for this demonstration:

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

If any of the devices is powered off and then back on, it will remember its flash configuration and rejoin the network. It will also restore values of the Light CTL states. For more information about the flash manager, see Flash manager.

Controlling CTL lightness, CTL temperature, and CTL delta UV values

You can control the Lightness and the Color Temperature states on the server using the RTT commands 1 - 4 or the buttons 1 - 4 on the client board. Use the RTT commands 7,8,9, and a on the client board to retrieve the current CTL state values from the servers.

Note
If you are using the Light CTL server with LC server example, the light controller is switched off automatically by the Light LC Server as soon any mesh message to change the lightness value is received (for example, the Light CTL Set (that can change the lightness) or any other message that can change the bound lightness state value). Use a Light LC Client model to turn the light controller on again.

Changing behavior on power-up

You can change how the light CTL lightness value and the light CTL temperature value are restored during a power-up sequence.

The Light CTL Lightness state is bound to Light Lightness Actual state to reflect each other's values when these states are changed (see section 6.1.3.6.1 of Mesh Model Specification). Therefore, the power-up behavior of the light CTL lightness, temperature, and delta UV values can be changed by controlling the Generic OnPowerUp state instantiated by the Light Lightness Setup Server model.

See Changing behavior on power-up section in the light lightness example documentation to check how light CTL lightness value is restored upon a power-up.

The following table demonstrates how the light CTL temperature and delta UV values are restored:

Value (power-up) Temperature value Delta UV value
0 or 1 The value of the Light CTL Temperature Default state is used. The value of the Light CTL Delta UV Default state is used.
2 Last known value for the light CTL temperature before power-down. Last known value for the light CTL delta UV before power-down.

Use the Light CTL Client model board to change the Light CTL Temperature Default and the Light CTL Delta UV Default state:

See LED and button assignments for additional commands.

The factory default values for these states are controlled through the following defines:

If you want to edit the factory default values, do this in nrf_mesh_config_app.h of the server example you are using. Follow the instructions in Testing the example to rebuild and reprovision the example.

Restricting the range of the CTL temperature value

You can restrict the range of the CTL temperature value by changing the Light CTL Temperature Range state. The new value of the Light CTL Range state will be reflected in the Light CTL Lightness state at the next lightness value change.

Use RTT commands h, i, j, and k on the client board to change the Light CTL Temperature Range state, and the RTT command 6 to retrieve the current range. See LED and button assignments for additional commands.

The factory default values for the minimum and maximum possible range values are controlled through LIGHT_CTL_DEFAULT_ALLOWED_TEMPERATURE_MIN and LIGHT_CTL_DEFAULT_ALLOWED_TEMPERATURE_MAX values in the nrf_mesh_config_app.h file of the server examples.

Restricting the range of the CTL lightness value

As the Light CTL Lightness state is bound with the Light Lightness Actual state, you can restrict the range of the light CTL lightness values by changing the Light Lightness Range state using the Light Lightness Client. See Restricting the range of the lightness value section in light lightness example documentation.

Other factory default configuration

In addition to the parameters described in the previous sections, you can also set the factory default transition time in milliseconds when changing the lightness levels.

The transition time used by the Light CTL Server model uses the Default Transition Time state instance that belongs to the the Light Lightness Server model. For this reason, to change the factory default transition time for the server example, redefine the LIGHT_LIGHTNESS_DEFAULT_DTT value of the Generic Default Transition Time state in the nrf_mesh_config_app.h file of the server examples.

Documentation feedback | Developer Zone | Subscribe | Updated