Light HSL models

The Hue Saturation Lightness (HSL) models allow remote control of colored lights. While the CTL and xyL models operate in color spaces designed specifically for illumination, the HSL color space is most commonly used in computer imagery and television broadcasts. While easy to visualize and explain to end users, the HSL does not map well to common illumination properties such as color temperature, and does not take variation in the human perception of color into account.

The HSL models are best suited for applications where the color of the light is a primary function, such as decorative lighting. For applications where illumination is the primary function of the light, and its color and temperature is secondary, the CTL and xyL models might be better alternatives. However, neither the Bluetooth® Mesh model specification nor the nRF Connect SDK put any restrictions on the application areas for the different models. Developers may freely use the model best suited for their application.

On the light fixture side, the HSL Server models are separated into three independent models:

• Light Hue Server

• Light Saturation Server

• Light Lightness Server

Each of these models can be instantiated independently, or be combined using the Light HSL Server. See the documentation of each individual model for details.

The Light HSL models have a set of common types, listed below. For types common to all models, see Bluetooth Mesh models.

Conversion from HSL to RGB

The theoretical conversion from HSL to RGB is well-defined, and the bt_mesh_light_hsl_to_rgb() function provides an easy conversion between the two color spaces, for use with RGB LED hardware. While the conversion between HSL and RGB is universal, the properties of the light emitting hardware will influence the perceived linearity of transitions in the color space. For instance, although changing the hue of the light should only affect its color, the perceived lightness and saturation may also fluctuate if the light emitting hardware has a non-linear response, as perceived by the human eye. These fluctuations cannot be modeled efficiently in the model code, and must be accounted for and calibrated in the driver.

Subpages:

• Light HSL Client
• Light HSL Server
• Light Hue Server
• Light Saturation Server

Common API

This section lists the API common to the Light HSL mesh models.

Header file: include/bluetooth/mesh/light_hsl.h

group bt_mesh_light_hsl

API for the Light HSL models.

Defines

BT_MESH_LIGHT_HSL_MIN

BT_MESH_LIGHT_HSL_MAX

BT_MESH_LIGHT_HSL_OP_RANGE_DEFAULT

Functions

uint16_t bt_mesh_light_hsl_to_rgb(const struct bt_mesh_light_hsl *hsl, enum bt_mesh_rgb_ch ch)

Convert HSL to a 16 bit RGB channel value.

Uses the standard conversion formula to convert HSL to RGB, as described in https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_RGB. Note that the accuracy of the conversion depends on the characteristics of the light source hardware, and may need correction for each channel.

Parameters:

• hsl – [in] HSL value.

• ch – [in] RGB color channel.

Returns:

The value of the chosen RGB channel for the given HSL value.

struct bt_mesh_light_hsl

#include <light_hsl.h>

Common Light HSL parameters

Public Members

uint16_t lightness

Lightness level

uint16_t hue

Hue level

uint16_t saturation

Saturation level

struct bt_mesh_light_hue_sat

#include <light_hsl.h>

Light Hue and Saturation parameters

Public Members

uint16_t hue

Hue level

uint16_t saturation

Saturation level

struct bt_mesh_light_hsl_params

#include <light_hsl.h>

Common Light HSL set message parameters.

Public Members

struct bt_mesh_light_hsl params

HSL set parameters

const struct bt_mesh_model_transition *transition

Transition time parameters for the state change, or NULL.

When sending, setting the transition to NULL makes the receiver use its default transition time parameters, or 0 if no default transition time is set.

struct bt_mesh_light_hue_move

#include <light_hsl.h>

Hue move set parameters

Public Members

int16_t delta

Translation to make for every transition step.

const struct bt_mesh_model_transition *transition

Transition parameters. delay indicates time until the move should start, time indicates the amount of time each delta step should take.

When sending, setting the transition to NULL makes the receiver use its default transition time parameters, or 0 if no default transition time is set.

struct bt_mesh_light_hsl_status

#include <light_hsl.h>

Common Light HSL status message parameters.

Public Members

struct bt_mesh_light_hsl params

Status parameters

int32_t remaining_time

Remaining time for the state change (ms).

struct bt_mesh_light_hue

#include <light_hsl.h>

Common Light Hue set message parameters.

Public Members

uint16_t lvl

Level to set

const struct bt_mesh_model_transition *transition

Transition time parameters for the state change, or NULL.

When sending, setting the transition to NULL makes the receiver use its default transition time parameters, or 0 if no default transition time is set.

int direction

Direction of the Hue state change, if transition is present.

If positive, the current value should be incremented even if the target value is less than the current value. If negative, the current value should be decremented even if the target value is greater than the current value. The application is responsible for wrapping the Hue state around when the value reaches the end of the type range.

Note

Set by the Light Hue Server model.

struct bt_mesh_light_sat

#include <light_hsl.h>

Common Light Saturation set message parameters.

Public Members

uint16_t lvl

Level to set

const struct bt_mesh_model_transition *transition

Transition time parameters for the state change, or NULL.

When sending, setting the transition to NULL makes the receiver use its default transition time parameters, or 0 if no default transition time is set.

struct bt_mesh_light_hue_status

#include <light_hsl.h>

Common Light Hue status message parameters.

Public Members

uint16_t current

Current level

uint16_t target

Target level

int32_t remaining_time

Remaining time for the state change (ms).

struct bt_mesh_light_sat_status

#include <light_hsl.h>

Common Light Saturation status message parameters.

Public Members

uint16_t current

Current level

uint16_t target

Target level

int32_t remaining_time

Remaining time for the state change (ms).

struct bt_mesh_light_hsl_range

#include <light_hsl.h>

Light HSL range parameters.

Public Members

uint16_t min

Minimum range value

uint16_t max

Maximum range value

struct bt_mesh_light_hue_sat_range

#include <light_hsl.h>

Light HSL range set message parameters.

Public Members

struct bt_mesh_light_hue_sat min

Minimum hue and saturation

struct bt_mesh_light_hue_sat max

Maximum hue and saturation

struct bt_mesh_light_hsl_range_status

#include <light_hsl.h>

Light HSL range status message parameters.

Public Members

enum bt_mesh_model_status status_code

Range set status code

struct bt_mesh_light_hue_sat_range range

Hue and saturation range