This example is not supported by the nRF52810 SoC.

This example demonstrates how you can use mesh messages and events from the Light Lightness model API to control the brightness of the LED on your board.

The example is composed of two minor examples that use the Light Lightness Client/Setup Server model:

Light Lightness Setup Server
Light Lightness Client

For more information about the Light Lightness Client/Server model, see also the Bluetooth SIG's Mesh Model Overview.

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

Both the Light Lightness Setup Server and Light Lightness Client 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 Lightness example structure

Light Lightness Client example

The Light Lightness Client example has a provisionee role in the network. It implements two instances of the Light Lightness Client model. These instances are used to control the brightness of the LED 1 on the servers, the range of supported lightness levels, and the default lightness value after the servers' boot-up.

Light Lightness Setup Server example

The Light Lightness Setup Server example has a provisionee role in the network. It implements one instance of the Light Lightness Setup Server model.

This model instance is used to receive the lightness level and change the brightness of the LED 1 on the server board, whenever the Light Lightness Actual or Light Lightness Linear state is changed. A change in the Light Lightness Actual state is reflected in the Light Lightness Linear state, and the other way around.

The model instance uses the APP_PWM library of the nRF5 SDK to control the brightness of the LED. To map the lightness level to the allowed range of the PWM ticks, the value of the Light Lightness Actual state is converted to the value of the Generic Level state.

Light Lightness Client/Setup Server model

The Light Lightness Client model is used for manipulating the following states associated with the peer Light Lightness Setup Server model:

Light Lightness Actual
Light Lightness Linear
Light Lightness Default
Light Lightness Last
Light Lightness Range

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

Hardware requirements

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

One nRF52 development kit for the client.
One or more nRF52 development kits for the servers.

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 development kits.

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

Software requirements

Depending on your choice of the provisioning method:

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

Setup

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

LED and button assignments

Server:

LED 1: Reflects the value of the Light Lightness Actual state on the server.

When interacting with the boards:

You cannot use buttons on the server boards, because the Light Lightness Setup Server does not use the 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 LED 1 is decreased in large step.
`2`	-	The brightness of the LED 1 is increased in large step.
`4`	-	All mesh data is erased and the device is reset.

Client:

When interacting with the boards, you can use one of the following options:

RTT input (recommended): Due to a limited number of buttons on the DK board, use the following RTT input when evaluating this example:

RTT input	DK Button	Effect
`1`	Button 1	The actual lightness value is increased in large steps and the Light Lightness Set Unacknowledged message is sent.
`2`	Button 2	The actual lightness value is decreased in large steps and the Light Lightness Set Unacknowledged message is sent.
`3`	Button 3	The actual lightness value in a linear scale is increased in large steps and Light Lightness Linear Set Unacknowledged message is sent.
`4`	Button 4	The actual lightness value in a linear scale is decreased in large steps and Light Lightness Linear Set Unacknowledged message is sent.
`5`	-	The Light Lightness Last Get message is sent to request the last lightness value.
`6`	-	The Light Lightness Default Get message is sent to request the default lightness value.
`7`	-	The Light Lightness Range Get message is sent to request the range of supported lightness levels.
`8`	-	The Light Lightness Get message is sent to request the actual lightness value.
`9`	-	The Light Lightness Linear Get message is sent to request the actual lightness value in linear scale.
`a`	-	The default light lightness value is increased and the Light Lightness Default Set Unacknowledged message is sent.
`b`	-	The internal default light lightness value is decreased and the Light Lightness Default Set Unacknowledged message is sent.
`c`	-	The internal minimum value of lightness levels range is increased and the Light Lightness Range Set Unacknowledged message is sent.
`d`	-	The internal minimum value of lightness levels range is decreased and the Light Lightness Range Set Unacknowledged message is sent.
`e`	-	The internal maximum value of lightness levels range is increased and the Light Lightness Range Set Unacknowledged message is sent.
`f`	-	The internal maximum value of lightness levels range is decreased and the Light Lightness Range Set Unacknowledged message is sent.
`g`	-	The internal actual lightness value in a linear scale is set to 0 and the Light Lightness Linear Set message is sent.
`h`	-	Switches the client instance to be used for sending messages.

- Buttons: If you decide to use the buttons on the DK instead of the RTT input, you can only change the Light Lightness Actual state by sending Light Lightness Set Unacknowledged messages.

Testing the example

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

Note: If you have more than 40 boards for the server and decided to use the static provisioner example, set MAX_PROVISIONEE_NUMBER (in example_network_config.h) to the number of boards available and rebuild the provisioner example.

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:

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.
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 Lightness 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 0x401, 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.
Observe that the LED 1 on the provisioner board is turned ON when provisioner is scanning and provisioning a device.
Observe that the LED 2 on the provisioner board is turned ON when configuration procedure is in progress.
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 the information on the main Examples page 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:

Each server board is nRF5x Mesh Lightness Setup Server.
The client board is nRF5x Mesh Lightness Client.

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

For the nRF5x Mesh Lightness Setup Server server boards: Light Lightness Setup Server, Light Lightness Server.
For the nRF5x Mesh Lightness Client client board: Light Lightness Client.

Note: The Light Lightness Client example allows to control the Light Lightness states. For this purpose, it is enough to configure only the Light Lightness Setup Server and Light Lightness Server model instances. If you want to see how the binding works between the Light Lightness states and the Generic states, configure the generic models instantiated in the Light Lightness Setup Server example 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 Lightness 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 of the LED 1 on the corresponding server boards.

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

Light Lightness Set Unacknowledged
Light Lightness Get
Light Lightness Linear Set
Light Lightness Linear Set Unacknowledged
Light Lightness Linear Get
Light Lightness Default Set Unacknowledged
Light Lightness Default Get
Light Lightness Range Set Unacknowledged
Light Lightness Range Get
Light Lightness Last Get

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 Lightness states. For more information about the flash manager, see Flash manager.

Controlling the lightness value

You can control the lightness value of the LED 1 using the RTT commands 1 - 4 or the buttons 1 - 4 on the board. Use the RTT commands 7 and 8 to retrieve the current lightness value in the perceived (Actual) lightness or the measured (Linear) lightness value accordingly.

To set the lightness value to 0, use the RTT command g.

For more information about the difference between the Actual and the Linear lightness values, see Mesh Model Specification appendix A.2.

Changing behavior on power-up

You can change how the lightness value will be restored during a power-up sequence. This can be done by controlling the Generic OnPowerUp state instantiated by the Light Lightness Setup Server model.

The following table describes how the lightness value will be restored:

On PowerUp value	Lightness value
0	0
1	The value of the Light Lightness Default state is used if it is not a zero. Otherwise, the Light Lightness Last state will be used.
2	Last known value for the Light Lightness Actual before power down.

Use the RTT commands 9 and a to change the Light Lightness Default state, and the RTT commands 4 and 5 to retrieve the current last and default values. 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 Light Lightness Setup Server example. Follow instructions in Testing the example to re-build and re-provision the example.

Restricting the range of the lightness value

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

Use RTT commands c, d, e, and f to change the Light Lightness 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_LIGHTNESS_DEFAULT_RANGE_MIN and LIGHT_LIGHTNESS_DEFAULT_RANGE_MAX values in the nrf_mesh_config_app.h file of the Light Lightness Setup Server example.

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. To do this, redefine the LIGHT_LIGHTNESS_DEFAULT_DTT value of the Generic Default Transition Time state in the nrf_mesh_config_app.h file of the Light Lightness Setup Server example.