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:
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.
Common API¶
This section lists the API common to the Light HSL mesh models.
include/bluetooth/mesh/light_hsl.h-
group
bt_mesh_light_hsl API for the Light HSL models.
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.
- Return
The value of the chosen RGB channel for the given HSL value.
- Parameters
[in] hsl: HSL value.[in] ch: RGB color channel.
-
struct
bt_mesh_light_hsl¶ - #include <light_hsl.h>
Common Light HSL parameters
-
struct
bt_mesh_light_hue_sat¶ - #include <light_hsl.h>
Light Hue and Saturation parameters
-
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.
-
struct bt_mesh_light_hsl
-
struct
bt_mesh_light_hue_delta¶ - #include <light_hsl.h>
Hue delta set parameters
Public Members
-
int32_t
delta¶ Translation from original value.
-
bool
new_transaction¶ Whether this is a new transaction. If true, the delta should be relative to the current value. If false, the delta should be relative to the original value in the previous delta_set command.
-
const struct bt_mesh_model_transition *
transition¶ Transition time parameters for the state change.
-
int32_t
-
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.
delayindicates time until the move should start,timeindicates the amount of time eachdeltastep should take.
-
int16_t
-
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_hsl
-
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.
-
uint16_t
-
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.
-
uint16_t
-
struct
bt_mesh_light_hue_status¶ - #include <light_hsl.h>
Common Light Hue status message parameters.
-
struct
bt_mesh_light_sat_status¶ - #include <light_hsl.h>
Common Light Saturation status message parameters.
-
struct
bt_mesh_light_hsl_range¶ - #include <light_hsl.h>
Light HSL range parameters.
-
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_hue_sat
-
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
-
enum bt_mesh_model_status
-
uint16_t