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, i.e. white light. If the Saturation of a light is the maximum value of65535
, 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:
BT_MESH_ON_POWER_UP_OFF
- The Saturation state is set to the Default Saturation state on power-up.BT_MESH_ON_POWER_UP_ON
- The Saturation state is set to the Default Saturation state on power-up.BT_MESH_ON_POWER_UP_RESTORE
- The Saturation state is set to the last known Saturation value on power-up.
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
orOFF
.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_MODEL_SRV_STORE_TIMEOUT
.
API documentation¶
include/bluetooth/mesh/light_sat_srv.h
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
_srv – [in] Pointer to a Light Saturation Server model instance.
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.
- Returns 0
Successfully sent the message.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -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.
Note
This handler is mandatory.
- Parameters
srv – [in] Light Saturation server.
ctx – [in] Message context, or NULL if the callback was not triggered by a mesh message.
set – [in] Parameters of the state change.
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.
- Parameters
srv – [in] Light Saturation server.
ctx – [in] Message context, or NULL if the callback was not triggered by a mesh message.
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.
- Parameters
srv – [in] Light Saturation server.
ctx – [in] Message context, or NULL if the callback was not triggered by a mesh message
old_default – [in] Default value before the update.
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.
- Parameters
srv – [in] Light Saturation server.
ctx – [in] Message context, or NULL if the callback was not triggered by a mesh message
old_range – [in] Range before the update.
new_range – [in] Range after the update.
-
void (*const
-
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.
-
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
last
¶ Last known Saturation level
-
uint16_t
dflt
¶ Default Saturation level
-
struct bt_mesh_lvl_srv
-