This example demonstrates how you can use Bluetooth 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 Light CTL Server models:
For more information about the Light CTL Client and Server models, see the Bluetooth 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 Bluetooth mesh Proxy Service (Server). Read more about the Proxy feature in GATT provisioning and Proxy.
Table of contents
The light CTL client model 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.
The light CTL server model 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.
The light CTL server model example also implements one instance of the Scene Setup 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. The Scene Server model uses the Default Transition Time Server instance instantiated in the Light CTL Setup Server model instance.
For the values stored and recalled by the Scene model, see the Bluetooth Mesh Model Specification (MshMDLv1.0.1), Table 6.123. For more information on how to use the Scene models, see the scene example.
The light CTL server and light LC server models' 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 model example for information about how a light LC server works.
The hardware interface of this example is similar to the light CTL server model example.
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:
More information about the Light CTL models can be found in the Light CTL models documentation.
You need at least two compatible development kits for this example:
One or more compatible development kits for the servers.
On the server boards, you can either run the light CTL server model example or the light CTL server with light LC server models' example, or both of them.
If you choose the light CTL server with light LC server models' example, you also need at least one of the following:
See light LC server model example testing section for more information about how the light switch client and sensor example is used for testing the Light LC Server model.
Additionally, you need one of the following for provisioning:
See Compatibility for information about the compatible development kits.
Depending on the provisioning method:
You can find the source code of this example in the following folder: <InstallFolder>/examples/light_ctl
simple_hal module. Instead of the buttons on the server boards, use the following RTT input: | RTT input | DK Button | Effect |
|---|---|---|
1 | - | The brightness of the LEDs is decreased in a large step. |
2 | - | The brightness of the LEDs is increased in a large step. |
3 | - | The delta UV value is increased in large steps. The value wraps around when maximum value is reached. |
4 | - | All Bluetooth mesh data is erased and the device is reset. |
simple_hal module. Instead of the buttons on the server boards, use the following RTT input: | RTT input | DK Button | Effect |
|---|---|---|
1 | - | Toggles the values of the properties between 0 and the default values. |
2 | - | The color temperature of the LEDs is increased in large steps. The value wraps around when maximum value is reached. |
4 | - | All Bluetooth mesh data is erased and the device is reset. |
When sending the 1 RTT command, the following properties are toggled between 0 and the default values:
See Section 4.1.3 of the Bluetooth Mesh Device Properties (MDPv1.2), Bluetooth mesh device properties XML, and Bluetooth mesh characteristics XML for more information about the properties.
0) as soon as the Light Lightness Status message is published on account of the local state change.| RTT input | DK Button | Effect |
|---|---|---|
1 | Button 1 | The CTL lightness value is increased in large steps and the Light CTL Set Unacknowledged message is sent. |
2 | Button 2 | The CTL lightness value is decreased in large steps and the Light CTL Set Unacknowledged message is sent. |
3 | Button 3 | The CTL temperature value is increased_ in large steps and Light CTL Temperature Set Unacknowledged message is sent. |
4 | Button 4 | The CTL temperature value is decreased in large steps and Light CTL Temperature Set Unacknowledged message is sent. |
5 | - | The CTL delta UV value is increased in large steps and Light CTL Temperature Set Unacknowledged message is sent. |
6 | - | The CTL delta UV value is decreased in large steps and Light CTL Temperature Set Unacknowledged message is sent. |
7 | - | The Light CTL Get message is sent to request the Light CTL state value. |
8 | - | The Light CTL Temperature Get message is sent to request the Light CTL temperature value. |
9 | - | The Light CTL Temperature Range Get message is sent to request the Light CTL temperature range value. |
a | - | The Light Lightness Default Get message is sent to request the Light CTL default values. |
b | - | The CTL lightness value is increased in large steps and the Light Lightness Default Set message is sent. |
c | - | The CTL lightness value is decreased in large steps and the Light Lightness Default Set message is sent. |
d | - | The CTL temperature value is increased in large steps and the Light Lightness Default Set message is sent. |
e | - | The CTL temperature value is decreased in large steps and the Light Lightness Default Set message is sent. |
f | - | The CTL delta UV value is increased in large steps and the Light Lightness Default Set message is sent. |
g | - | The CTL delta UV value is decreased in large steps and the Light Lightness Default Set message is sent. |
h | - | The internal minimum value of light CTL temperature range is increased and the Light CTL Temperature Range Set Unacknowledged message is sent. |
i | - | The internal minimum value of light CTL temperature range is decreased and the Light CTL Temperature Range Set Unacknowledged message is sent. |
j | - | The internal maximum value of light CTL temperature range is increased and the Light CTL Temperature Range Set Unacknowledged message is sent. |
k | - | The internal maximum value of light CTL temperature range is decreased and the Light CTL Temperature Range Set Unacknowledged message is sent. |
l | - | Switches the client instance to be used for sending messages. |
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/light_ctl/ctl_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.
To test the light CTL example, build the examples by following the instructions in Building the Bluetooth mesh stack.
(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:
See provisioner example testing section for detailed steps required to provision and configure the boards using the static provisioner.
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:
nRF5x Mesh Light CTL Setup Server or nRF5x Mesh Light CTL+LC Setup Server.nRF5x Mesh Light CTL Client.The following model instances must be configured in the app for evaluating this example:
nRF5x Mesh CTL Client boards: Light CTL Client.nRF5x Mesh Light CTL Setup Server boards:nRF5x Mesh Light CTL+LC Setup Server boards: Light CTL Setup Server, Light CTL Server, Light LC Server. Refer to light LC example configuration using nRF Mesh mobile app section for configuring nRF5x Mesh Switch and nRF Mesh Sensor Server boards to work with Light LC server instantiated on this example.Once the provisioning is complete, you can start 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.
The following set of message types is 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.
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.
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 Bluetooth 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:
b and c to change the Light Lightness Default state.d and e to change the Light CTL Temperature Default state.f and g to change the Light CTL Delta UV Default state.a to retrieve the current default values of the servers that you use.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.
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.
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 the light lightness example documentation.
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 model 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.