Light Saturation Server

The Light Saturation Server controls the saturation of the light color. It should be instantiated in the light fixture node.

The Light Saturation Server adds a single model instance to the composition data, in addition to the extended Generic Level Server. Although the Light Saturation Server contains range and default states like other lighting models, the states cannot be accessed directly by other nodes without a Light HSL Server.

States

Saturation: uint16_t

The Saturation controls the light’s color saturation. If the Saturation of a light is 0, the light’s color is a completely gray scale, that is, white light. If the Saturation of a light is the maximum value of 65535, the color should be fully saturated.

The Saturation state power-up behavior is determined by the On Power Up state of the extended Generic Power OnOff Server:

Your application is expected to hold the state memory and provide access to the state through the bt_mesh_light_sat_srv_handlers handler structure.

Note

If the Saturation Server is part of an HSL Server, the application must publish the HSL status using bt_mesh_light_hsl_srv_pub() whenever the Saturation state changes. This is not handled automatically by the HSL Server.

Saturation Range: bt_mesh_light_hsl_range

The Saturation Range is a meta state that defines the valid range for the Saturation state. The Saturation should never go outside the Saturation Range.

The memory for the Saturation Range state is held by the model, and the application may receive updates on state changes through the bt_mesh_light_sat_handlers.range_update callback.

Default Saturation: uint16_t

The Default Saturation state is only used when the model is instantiated as part of a Light HSL Server. The Default Saturation determines the initial Saturation when the node is powered on, and the On Power Up state of the Light HSL Server’s extended Generic Power OnOff Server is ON or OFF.

The memory for the Default Saturation state is held by the model, and the application may receive updates on state changes through the bt_mesh_light_sat_handlers.default_update callback.

Extended models

The Light Saturation Server extends the following models:

As the state of the extended model is bound to the Saturation state, the extended model is not exposed directly to the application.

Persistent storage

The Light Saturation Server stores the following information:

  • Any changes to the Default Saturation and Saturation Range states.

  • The last known Saturation level.

This information is used to reestablish the correct Saturation level when the device powers up.

If CONFIG_BT_SETTINGS is enabled, the Light Saturation Server stores all its states persistently using a configurable storage delay to stagger storing. See CONFIG_BT_MESH_STORE_TIMEOUT.

The Light Saturation Server can use the emergency data storage (EMDS) together with persistent storage for the following purposes:

  • Extend the flash memory life expectancy.

  • Reduce the use of resources by reducing the number of writes to flash memory.

If option CONFIG_EMDS is enabled, the Light Saturation Server continues to store the default saturation and saturation range states to the flash memory through the settings library, but the last known saturation level is stored by using the EMDS library. This split is done so the values that may change often are stored on shutdown only, while the rarely changed values are immediately stored in flash memory.

API documentation

Header file: include/bluetooth/mesh/light_sat_srv.h
Source file: subsys/bluetooth/mesh/light_sat_srv.c
group bt_mesh_light_sat_srv

API for the Light Saturation Server model.

Defines

BT_MESH_LIGHT_SAT_SRV_INIT(_handlers)

Initialization parameters for a Light Saturation Server model instance.

Parameters:

  • _handlers – [in] HSL Saturation Server callbacks.

BT_MESH_MODEL_LIGHT_SAT_SRV(_srv)

HSL Saturation Server model composition data entry.

Parameters:

Functions

int bt_mesh_light_sat_srv_pub(struct bt_mesh_light_sat_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_sat_status *status)

Publish the current HSL Saturation status.

Asynchronously publishes a HSL Saturation 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 default 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_sat_srv_handlers
#include <light_sat_srv.h>

HSL Saturation Server state access handlers.

Public Members

void (*const set)(struct bt_mesh_light_sat_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_sat *set, struct bt_mesh_light_sat_status *rsp)

Set the Saturation state.

When a set message is received, the model publishes a status message, with the response set to rsp. When an acknowledged set message is received, the model also sends a response back to a client. If a state change is non-instantaneous, for example when bt_mesh_model_transition_time returns a nonzero value, the application is responsible for publishing a value of the Saturation state at the end of the transition.

Note

This handler is mandatory.

Param srv:

[in] Light Saturation server.

Param ctx:

[in] Message context, or NULL if the callback was not triggered by a mesh message.

Param set:

[in] Parameters of the state change.

Param rsp:

[out] Response structure to be filled.

void (*const get)(struct bt_mesh_light_sat_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_sat_status *rsp)

Get the Saturation state.

Note

This handler is mandatory.

Param srv:

[in] Light Saturation server.

Param ctx:

[in] Message context, or NULL if the callback was not triggered by a mesh message.

Param rsp:

[out] Response structure to be filled.

void (*const default_update)(struct bt_mesh_light_sat_srv *srv, struct bt_mesh_msg_ctx *ctx, uint16_t old_default, uint16_t new_default)

The default saturation value has been updated.

Param srv:

[in] Light Saturation server.

Param ctx:

[in] Message context, or NULL if the callback was not triggered by a mesh message

Param old_default:

[in] Default value before the update.

Param new_default:

[in] Default value after the update.

void (*const range_update)(struct bt_mesh_light_sat_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_range *old_range, const struct bt_mesh_light_hsl_range *new_range)

The valid saturation range has been updated.

Param srv:

[in] Light Saturation server.

Param ctx:

[in] Message context, or NULL if the callback was not triggered by a mesh message

Param old_range:

[in] Range before the update.

Param new_range:

[in] Range after the update.

struct bt_mesh_light_sat_srv
#include <light_sat_srv.h>

HSL Saturation Server instance. Should be initialized with BT_MESH_LIGHT_SAT_SRV_INIT.

Public Members

struct bt_mesh_lvl_srv lvl

Light Level Server instance.

const struct bt_mesh_light_sat_srv_handlers *handlers

Handler function structure.

const struct bt_mesh_model *model

Model entry.

const struct bt_mesh_light_hsl_srv *hsl

Pointer to the corresponding HSL server, if it has one. Is set automatically by the HSL server.

struct bt_mesh_model_pub pub

Publish parameters.

struct net_buf_simple buf

Publication buffer

uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_LIGHT_SAT_OP_STATUS, BT_MESH_LIGHT_HSL_MSG_MAXLEN_SAT_STATUS)]

Publication buffer data

struct bt_mesh_tid_ctx prev_transaction

Transaction ID tracker for the set messages.

struct bt_mesh_light_hsl_range range

Saturation range

uint16_t dflt

Default Saturation level

uint16_t last

Last known Saturation level