Light LC server model example

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 how the light controller uses the data coming from sensors and switches to control the lightness level of lights. After configuring and running this example, triggering Light On, Light Off, and occupancy events will change the brightness of the LED on your board.

This examples uses the Light LC Setup Server model. For more information about the Light LC Setup Server model, see also the Bluetooth SIG's Bluetooth 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.

Table of contents

The example instantiates the following models:

The model instance uses the Light On and Light Off events and the data coming from occupancy and ambient sensors to adjust the lightness output, which is used to control the brightness of the LED using the APP_PWM library of the nRF5 SDK.

Light LC server model example structure

This example has the provisionee role in the network. It supports provisioning over Advertising bearer (PB-ADV) and GATT bearer (PB-GATT), and the Bluetooth mesh Proxy Service (Server).

Light LC Setup Server model

The Light LC Server model collects the data from occupancy and ambient sensors. When the light controller is enabled (see LIGHT_LC_DEFAULT_MODE), this model controls the lightness output. The Light Lightness Setup Server model is used to reflect the changes in the lightness output on the lightness level of lights through the binding between the Light LC Linear Output and Light Lightness Linear states of these two models.

The Light Lightness Setup Server model can be still controlled with the Light Lightness Client model. However, the light controller is switched off automatically by the Light LC Server as soon any Bluetooth mesh message to change the lightness value is received (for example, the Light Lightness Set 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.

Note
This example does not provide the light LC client model example.

For more information about the Light Lightness Setup Server model, see the light lightness example page.

The Light LC Setup Server supports Bluetooth mesh Occupancy and Ambient Lux Level sensors – whose values are received through the Sensor Status messages. Sensors use the Sensor Server model to publish Sensor Status messages.

The Light LC Setup Server model uses the Proportional Integral (PI) Feedback Regulator to control the lightness output. The PI Feedback Regulator reads the ambient light sensors' data at regular intervals.

For more information about the Light LC models, see Light LC models documentation.

Scene model

The light LC 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 LC 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.144. The Light LC Server model overrides some of the Scene Store/Recall behaviors. For details, see the Bluetooth Mesh Model Specification (MshMDLv1.0.1), Section 6.5.1.3. For more information on how to use the Scene models, see the scene example.

Hardware requirements

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

  • One compatible development kit for the light switch client.
  • One or more compatible development kits for the light LC servers.
  • One or more compatible development kits for the sensor server.

Additionally, you need one of the following for provisioning:

See Compatibility for information about the compatible development kits.

Note
This example uses the PWM peripheral to control the brightness of the LED.

Software requirements

To test this example, you need to use the following additional software:

  • The client example from the light switch example folder: <InstallFolder>/examples/light_switch/client
  • The server example from the sensor example folder: <InstallFolder>/examples/sensor/server for use as an emulated occupancy sensor.
  • Depending on the provisioning method:
Note
The sensor server example implements an emulated Motion Detect sensor. It does not implement an ambient light sensor.

Setup

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

LED and button assignments

The following LED and button assignments are defined for this example:

  • Light LC 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 LC server model example does not use the simple_hal module.

      • Instead of the buttons on the server boards, use the following RTT input:

        RTT input DK Buttons Effect
        1 - Toggles the values of the properties between 0 and the default values.
        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:

        • Light Control Time Fade
        • Light Control Time Fade On
        • Light Control Time Fade Standby Auto
        • Light Control Time Fade Standby Manual
        • Light Control Time Run On

        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.

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/light_lc/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 light LC server model example, first build this example, the light switch client example, and the sensor server example by following the instructions in Building the Bluetooth mesh stack.

Note
The Bluetooth mesh model specification mentions that the default value of the mode of the light controller to 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 example does not provide the light LC client model 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

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.

The following naming convention is used in the app:

  • Each server board is nRF5x Mesh Light LC Setup Server.
  • The Light switch client board is nRF5x Mesh Switch.
  • The Occupancy sensor board is nRF5x Mesh Sensor Setup Server.

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

  • For the nRF5x Mesh Light LC Setup Server server boards:
    • Mandatory on the first element: Light LC Setup Server, Light LC Server
    • Optional on the first element (with Scene model integration included): Scene Setup Server, Scene Server
    • Mandatory on the second element: Generic OnOff Server
  • For the nRF5x Mesh Switch client board: Generic OnOff Client.
  • For the nRF5x Mesh Sensor Setup Server server board or boards: Sensor Server.

When setting publication with nRF Mesh mobile app:

  • For the light switch client example, set the publication address of the second Generic OnOff Client model instance to the second element address of the light LC server model example.
  • For the sensor server example, set the publication address of the Sensor Server model instance to the second element address of the light LC server model example.

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

Interacting with the boards

Once the Light LC server board is started after provisioning, the light controller will be turned on. The example starts in the Standby state, and the LED 1 is driven to the lowest light level (either determined by the LIGHT_LC_SERVER_LIGHTNESS_STANDBY_PID propety or a higher level, because of the light feedback from the ambient light sensor that attempts to keep the light at a minimum illuminance determined by the LIGHT_LC_SERVER_AMBIENT_LUXLEVEL_STANDBY_PID property).

At this stage, you can interact with the light LC server model example by using the following options:

  • Press Button 1 on the Light switch client board to send the Light On event.
    • Even though this example does not provide the Light LC Client example, you can still send Light On and Light Off events to the light LC setup server example, because the Light LC Light OnOff state of the Light LC Server is bound with the Generic OnOff state of the Generic OnOff Server model extended by the Light LC Server model instance.
  • Press Button 3 or Button 4 on the Sensor Server board to trigger the Occupancy On event.

Issuing the Occupancy On event or the Light On event triggers the following chain of events, as shown on the Figure 6.4 of the Bluetooth mesh model specification:

  • The Light LC server's state machine transitions to the Fade On state. The LED 1 starts increasing in brightness to the Run level.
    • The time it takes to reach the Run state depends upon the Light On message that was sent. If the message was sent with a non-zero transition time, the specified transition time is used; otherwise, the time determined by LIGHT_LC_SERVER_TIME_FADE_ON_PID property is used.
  • After reaching the Run state, the light stays at the Run level for the time determined by the LIGHT_LC_SERVER_TIME_RUN_ON_PID property.
  • The light then transitions to the Fade state. The light starts decreasing to the Prolong level for the time determined by the LIGHT_LC_SERVER_TIME_FADE_PID property.
  • After reaching the Prolong state, the light stays at the Prolong level for the time determined by the LIGHT_LC_SERVER_TIME_PROLONG_PID property.
  • The light then transitions through the Fade Standby Auto state back to the Standby state. The amount of time this takes is determined by the LIGHT_LC_SERVER_TIME_FADE_STANDBY_AUTO_PID property.

You can issue new events at any time. This includes pressing Button 2 (or 4) on the Light switch client board to send a Light Off event. In such case, the state machine will start transition depending on its current state machine state and will set the brightness of the LED 1 according to the lightness level defined for the current state.

Note
For the testing purposes, the default time values for the various states are very short (between 2 and 10 seconds). When the Light LC Setup Server is running in a production environment, these values can be set to minutes or hours. For more the information about the format, units and allowed values of the properties representing these values, see Section 4.1.3 of Bluetooth mesh device properties, Bluetooth mesh device properties XML and Bluetooth mesh characteristics XML.

Lightness, illuminance, and transition time properties

The properties' values are controlled through the Light LC Client model.

The minimum lightness value at any state is determined by the following properties:

The illuminance value at any state is determined by the following properties:

If the values for these properties are not being detected by the PI Feedback Regulator, it will attempt to drive the LED 1 to a higher brightness.

If there were no reports from an ambient light sensor, the PI Feedback Regulator will not attempt to drive the LED 1, and the LED 1 will be driven by the state machine to the lightness values defined by the properties values specified for each state.

The factory default values of the lightness and illuminance properties are controlled through the corresponding defines:

The transition time is determined by the following properties:

You can make the state machine to transition instantly between the Standby and Run states. To do that, use RTT command 1 to toggle the properties of the state machine. After setting the corresponding properties to 0 you should notice the immediate transition between these states, when Occupancy On or Light On event is reported.

The factory default values of the time properties are controlled through the corresponding defines:

If you want to edit the factory default values, do this in nrf_mesh_config_app.h of the light LC server model example. Follow instructions in Testing the example to re-build and re-provision the example.

Delaying occupancy report transition

By default, when occupancy has been reported by the Sensor Server model through Sensor Status messages, the transition will start immediately. You can postpone the transition by setting a delay time in LIGHT_LC_DEFAULT_PR_TIME_OCCUPANCY_DELAY_MS in nrf_mesh_config_app.h of the LC server example.