Light Hue Server¶
The Light Hue Server controls the hue of the light color. It should be instantiated in the light fixture node.
The Light Hue Server adds a single model instance to the composition data, in addition to the extended Generic Level Server.
Although the Light Hue Server contains range
and default
states like other lighting models, the states cannot be accessed directly by other nodes without a Light HSL Server.
Unlike the other Lightness models, the Hue Server model’s Hue state will wrap around when reaching its maximum or minimum values as defined in bt_mesh_light_hue_srv.range
.
To be able to handle this effectively in the application, the Light Hue Server model exposes the underlying Generic Level Server’s Move and Delta Set messages, which must be implemented.
If the application gets a call to the bt_mesh_light_hue_srv_handlers.delta_set
callback, it must move the Hue relative to its current value, in the direction determined by the delta_set
message.
Note that this may cause the Hue state to wrap around.
Similarly, if the application gets a call to the bt_mesh_light_hue_srv_handlers.move_set
callback, it must start a continuous transition of the Hue state in the direction and rate determined by the move_set
message.
This move transition continues until the Hue Server receives a new set
, delta_set
or move_set
message, or the device reboots.
States¶
- Hue:
uint16_t
The Hue controls the light’s angle on the color wheel. The Hue values
0
-65535
can represent any position on the color spectrum, starting at red, moving through green and blue, before coming back to red at the maximum value. The Hue state should wrap around when it reaches the end of the spectrum, so that a Generic Level Move message to the extended Generic Level Server should start a never-ending cycling through the hue spectrum, unless it is restricted by the Hue Range.The Hue 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 Hue state is set to the Default Hue state on power-up.BT_MESH_ON_POWER_UP_ON
- The Hue state is set to the Default Hue state on power-up.BT_MESH_ON_POWER_UP_RESTORE
- The Hue state is set to the last known Hue value on power-up.
Your application is expected to hold the state memory and provide access to the state through the
bt_mesh_light_hue_srv_handlers
handler structure.Note
If the Hue Server is part of an HSL Server, the application must publish the HSL status using
bt_mesh_light_hsl_srv_pub()
whenever the Hue state changes. This is not handled automatically by the HSL Server.- Hue Range:
bt_mesh_light_hsl_range
The Hue Range is a meta state that defines the valid range for the Hue state. The Hue should never go outside the Hue Range.
The memory for the Hue Range state is held by the model, and the application may receive updates on state changes through the
bt_mesh_light_hue_handlers.range_update
callback.- Default Hue:
uint16_t
The Default Hue state is only used when the model is instantiated as part of a Light HSL Server. The Default Hue determines the initial Hue 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 Hue state is held by the model, and the application may receive updates on state changes through the
bt_mesh_light_hue_handlers.default_update
callback.
Extended models¶
The Light Hue Server extends the following models:
As the state of the extended model is bound to the Hue state, the extended model is not exposed directly to the application.
Persistent storage¶
The Light Hue Server stores the following information:
Any changes to the Default Hue and Hue Range states.
The last known Hue level.
This information is used to reestablish the correct Hue level when the device powers up.
If CONFIG_BT_SETTINGS
is enabled, the Light Hue 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_hue_srv.h
subsys/bluetooth/mesh/light_hue_srv.c
-
group
bt_mesh_light_hue_srv
API for the Light Hue Server model.
Defines
-
BT_MESH_LIGHT_HUE_SRV_INIT
(_handlers)¶ Initialization parameters for a Light Hue Server model instance.
- Parameters
_handlers – [in] HSL Hue Server callbacks.
-
BT_MESH_MODEL_LIGHT_HUE_SRV
(_srv)¶ HSL Hue Server model composition data entry.
- Parameters
_srv – [in] Pointer to a Light Hue Server model instance.
Functions
-
int
bt_mesh_light_hue_srv_pub
(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_status *status)¶ Publish the current HSL Hue status.
Asynchronously publishes a HSL Hue 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_hue_srv_handlers
¶ - #include <light_hue_srv.h>
HSL Hue Server state access handlers.
Public Members
-
void (*const
set
)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue *set, struct bt_mesh_light_hue_status *rsp)¶ Set the Hue state.
Note
This handler is mandatory.
- Parameters
srv – [in] Server to set the Hue state of.
ctx – [in] Message context.
set – [in] Parameters of the state change.
rsp – [out] Response structure to be filled.
-
void (*const
delta_set
)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_delta *delta_set, struct bt_mesh_light_hue_status *rsp)¶ Change the hue relative to its current value.
If
delta_set::new_transaction
is false, the state transition should use the same start point as the previous delta_set message, effectively overriding the previous message. If it’s true, the level transition should start from the current level, stopping any ongoing transitions.When reaching the border values for the state, the value should wrap around. While the server is executing a move command, it should report its
target
value as BT_MESH_LIGHT_HSL_MIN or BT_MESH_LIGHT_HSL_MAX, depending on whether it’s moving up or down.Note
This handler is mandatory.
- Parameters
srv – [in] Light Hue server.
ctx – [in] Message context, or NULL if the callback was not triggered by a mesh message.
delta_set – [in] Parameters of the state change. Note that the transition will always be non-NULL.
rsp – [out] Response structure to be filled.
-
void (*const
move_set
)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_move *move, struct bt_mesh_light_hue_status *rsp)¶ Move the hue continuously at a certain rate.
The hue state should move
move_set::delta
units for everymove_set::transition::time
milliseconds. For instance, if delta is 5 and the transition time is 100ms, the state should move at a rate of 50 per second.When reaching the border values for the state, the value should wrap around. While the server is executing a move command, it should report its
target
value as BT_MESH_LIGHT_HSL_MIN or BT_MESH_LIGHT_HSL_MAX, depending on whether it’s moving up or down.Note
This handler is mandatory.
- Parameters
srv – [in] Server to set the Hue state of.
ctx – [in] Message context.
move – [in] Parameters of the state change.
rsp – [out] Response structure to be filled.
-
void (*const
get
)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hue_status *rsp)¶ Get the Hue state.
Note
This handler is mandatory.
- Parameters
srv – [in] Server to get the CTL state of.
ctx – [in] Message context.
rsp – [out] Response structure to be filled.
-
void (*const
default_update
)(struct bt_mesh_light_hue_srv *srv, struct bt_mesh_msg_ctx *ctx, uint16_t old_default, uint16_t new_default)¶ The default hue has been updated.
- Parameters
srv – [in] Light Hue 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_hue_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 hue range has been updated.
- Parameters
srv – [in] Light Hue 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_hue_srv
¶ - #include <light_hue_srv.h>
HSL Hue Server instance. Should be initialized with BT_MESH_LIGHT_HUE_SRV_INIT.
Public Members
-
struct bt_mesh_lvl_srv
lvl
¶ Light Level Server instance.
-
const struct bt_mesh_light_hue_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_HUE_OP_STATUS
,BT_MESH_LIGHT_HSL_MSG_MAXLEN_HUE_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
¶ Hue range
-
uint16_t
last
¶ Last known Hue level
-
uint16_t
dflt
¶ Default Hue level
-
struct bt_mesh_lvl_srv
-