Light HSL Server

The Light HSL Server represents a single colored light. It should be instantiated in the light fixture node.

The Light HSL Server provides functionality for working on the individual hue, saturation and lightness channels in a combined message interface, controlled by a Light HSL Client.

The Light HSL Server adds the following new model instances in the composition data:

• Light HSL Server

• Light HSL Setup Server

These model instances share the states of the Light HSL Server, but accept different messages. This allows for a fine-grained control of the access rights for the Light HSL states, as these model instances can be bound to different application keys:

• The Light HSL Server only provides write access to the HSL state for the user, in addition to read access to all the meta states.

• The Light HSL Setup Server provides write access to the corresponding Light Hue Server and Light Saturation Server models’ meta states. This allows the configurator devices to set up the range and the default value for the various HSL states.

The extended Light Lightness Server model should be defined and initialized separately, and the pointer to this model should be passed to the Light HSL Server initialization macro.

Model composition

The Light HSL Server requires a Light Hue Server and a Light Saturation Server model to be instantiated in any of the following elements. As each of the Light Hue, Saturation and Lightness Server models extend the Generic Level Server model, they cannot be instantiated on the same element.

The recommended configuration for the Light HSL Server model is to instantiate the Light HSL Server (with its extended Light Lightness Server model) on one element, then instantiate the corresponding Light Hue Server model on the subsequent element, and the corresponding Light Saturation Server model on the next element after that:

Element N	Element N+1	Element N+2
Light Lightness Server	Light Hue Server	Light Saturation Server
Light HSL Server

In the application code, this would look like this:

static struct bt_mesh_lightness_srv lightess_srv =
   BT_MESH_LIGHTNESS_SRV_INIT(&lightness_cb);

static struct bt_mesh_light_hsl_srv hsl_srv =
     BT_MESH_LIGHT_HSL_SRV_INIT(&lightness_srv, &hue_cb, &sat_cb);

static struct bt_mesh_elem elements[] = {
     BT_MESH_ELEM(
             1, BT_MESH_MODEL_LIST(
         BT_MESH_MODEL_LIGHTNESS_SRV(&lightness_srv),
         BT_MESH_MODEL_LIGHT_HSL_SRV(&hsl_srv)),
             BT_MESH_MODEL_NONE),
     BT_MESH_ELEM(
             2, BT_MESH_MODEL_LIST(BT_MESH_MODEL_LIGHT_HUE_SRV(&hsl_srv.hue)),
             BT_MESH_MODEL_NONE),
     BT_MESH_ELEM(
             3, BT_MESH_MODEL_LIST(BT_MESH_MODEL_LIGHT_SAT_SRV(&hsl_srv.sat)),
             BT_MESH_MODEL_NONE),
};

Note

The bt_mesh_light_hsl_srv contains the memory for its corresponding Light Hue Server and Light Saturation Server. When instantiating these models in the composition data, the model entries must point to these substructures. The bt_mesh_light_hsl_srv also contains a pointer to the Light Lightness Server model. Pointer to this model should be passed to the Light HSL Server initialization macro.

The Light HSL Server does not contain any states on its own, but instead operates on the underlying Light Hue, Saturation and Lightness Server models’ states. Because of this, the Light HSL Server does not have a message handler structure, but will instead defer its messages to the individual submodels’ handler callbacks.

It’s also possible to combine the Light HSL Server model with a Light xyL Server. See Usage with the Light HSL Server for details.

States

None.

Extended models

The Light HSL Server extends the following models:

• Light Lightness Server

Additionally, the Light HSL Server model requires a Light Hue Server and a Light Saturation Server to be instantiated on any of the following elements, using the bt_mesh_light_hsl_srv.hue and bt_mesh_light_hsl_srv.sat structures.

Persistent storage

The Light HSL Server does not store any data persistently, but will control the underlying Light Hue Server and Light Saturation Server models’ state when the device is powered up.

API documentation

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

Source file: subsys/bluetooth/mesh/light_hsl_srv.c

group bt_mesh_light_hsl_srv

API for the Light HSL Server model.

Defines

BT_MESH_LIGHT_HSL_SRV_INIT(_lightness_srv, _hue_handlers, _sat_handlers)

Initialization parameters for a Light HSL Server model instance.

Parameters

• _lightness_srv – [in] Pointer to the Lightness Server instance.

• _hue_handlers – [in] Hue Server model handlers.

• _sat_handlers – [in] Saturation Server model handlers.

BT_MESH_MODEL_LIGHT_HSL_SRV(_srv)

Light HSL Server model composition data entry.

Parameters

• _srv – [in] Pointer to a Light HSL Server model instance.

Functions

int bt_mesh_light_hsl_srv_pub(struct bt_mesh_light_hsl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_status *status)

Publish the current HSL status.

Asynchronously publishes a HSL status message with the configured publish parameters.

Note

This API is only used publishing unprompted status messages. Response messages for get and set messages are handled internally.

Parameters

• srv – [in] Server instance to publish on.

• ctx – [in] Message context to send with, or NULL to send with the configured publish parameters.

• status – [in] Status parameters.

Return values

• 0 – Successfully sent the message.

• -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

• -EAGAIN – The device has not been provisioned.

struct bt_mesh_light_hsl_srv

#include <light_hsl_srv.h>

Light HSL Server instance.

Public Members

struct bt_mesh_light_hue_srv hue

Light Hue Server instance.

struct bt_mesh_light_sat_srv sat

Light Saturation Server instance.

struct bt_mesh_lightness_srv *lightness

Pointer to Lightness Server instance.

struct bt_mesh_model *model

Model entry.

struct bt_mesh_model_pub pub

Publish parameters.

struct net_buf_simple buf

Publish message buffer

uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_LIGHT_HSL_OP_STATUS, BT_MESH_LIGHT_HSL_MSG_MAXLEN_STATUS)]

Publish message buffer data

bool pub_pending

A publication is pending, and any calls to bt_mesh_light_hsl_srv_pub will return successfully without sending a message.

struct bt_mesh_tid_ctx prev_transaction

Transaction ID tracker for the set messages.