Light xyL Server¶
The Light xyL Server represents a single light on a mesh device. This model is well suited for implementation in light sources with multi-color light emission. It should be instantiated in the light fixture node.
Three states can be used to configure the lighting output of an element:
Lightness - This state determines the lightness of a tunable white light emitted by an element.
x - Determines the x coordinate on the CIE1931 color space chart of a color light emitted by an element.
y - Determines the y coordinate on the CIE1931 color space chart of a color light emitted by an element.
The Light xyL Server adds two model instances in the composition data, in addition to the extended Light Lightness Server model. These model instances share the states of the Light xyL Server, but accept different messages. This allows for a fine-grained control of the access rights for the Light xyL states, as the model instances can be bound to different application keys. The following two model instances are added:
Light xyL Server - Provides write access to the Lightness, x and y states for the user, in addition to read access to all meta states
Light xyL Setup Server - Provides write access to Default xyL state and Range meta states, allowing configurator devices to set up a range for the x and y state, and a default xyL state
States¶
The xyL model contains the following states:
- Lightness:
uint16_t
The Lightness state represents the emitted light level of an element, and ranges from
0
to65535
. The Lightness state is shared by the extended Light Lightness Server model.The Lightness 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 Lightness state is set to0
on power-up.BT_MESH_ON_POWER_UP_ON
- The Lightness state is set to Default Lightness on power-up.BT_MESH_ON_POWER_UP_RESTORE
- The Lightness state is set to the last known Light level (zero or non-zero).
The Lightness state is held and managed by the extended Light Lightness Server.
- x:
uint16_t
The x state represents the x coordinate on the CIE1931 color space chart of a color light emitted by an element. This is a 16-bit unsigned integer representation of a scale from 0 to 1 using the formula:
CIE1931_x = (Light xyL x) / 65535
The x 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 x state is set to Default x on power-up.BT_MESH_ON_POWER_UP_ON
- The x state is set to Default x on power-up.BT_MESH_ON_POWER_UP_RESTORE
- The x state is set to the last known x level.
Your application is expected to hold the state memory and provide access to the state through the
bt_mesh_light_xyl_srv_handlers
handler structure.- y:
uint16_t
The y state represents the y coordinate on the CIE1931 color space chart of a color light emitted by an element. This is a 16-bit unsigned integer representation of a scale from 0 to 1 using the formula:
CIE1931_y = (Light xyL y) / 65535
The y 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 y state is set to Default y on power-up.BT_MESH_ON_POWER_UP_ON
- The y state is set to Default y on power-up.BT_MESH_ON_POWER_UP_RESTORE
- The y state is set to the last known y level.
Your application is expected to hold the state memory and provide access to the state through the
bt_mesh_light_xyl_srv_handlers
handler structure.- Default xy:
bt_mesh_light_xy
The Default xy state is a meta state that controls the default x and y level. It is used when the light is turned on, but its exact state levels are not specified.
The memory for the Default xy state is held by the model, and the application may receive updates on state changes through the
bt_mesh_light_xyl_srv_handlers.default_update
callback.- Range:
bt_mesh_light_xyl_range
The Range state is a meta state that determines the accepted x and y level range. If the x or y level is set to a value outside the currently defined Range state value, it is moved to fit inside the range. If the Range state changes to exclude the current x or y level, the level should be changed accordingly.
The memory for the Range state is held by the model, and the application may receive updates on state changes through the
bt_mesh_light_xyl_srv_handlers.range_update
callback.
Extended models¶
The Light xyL Server extends the following model:
State of the extended Lightness Server model is partially controlled by the Light xyL Server, making it able to alter states like Lightness and the Default Lightness of the Lightness Server model.
Persistent storage¶
The Light xyL Server stores the following information:
Any changes to states Default xyL and Range
The last known Lightness, x, and y levels
In addition, the model takes over the persistent storage responsibility of the Light Lightness Server model.
This information is used to reestablish the correct light configuration when the device powers up.
If CONFIG_BT_SETTINGS
is enabled, the Light xyL 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_xyl_srv.h
subsys/bluetooth/mesh/light_xyl_srv.c
-
group
bt_mesh_light_xyl_srv
API for the Light xyL Server model.
Defines
-
BT_MESH_LIGHT_XYL_SRV_INIT
(_lightness_handlers, _light_xyl_handlers)¶ initialization parameters for a Light xyL Server model instance.
- Parameters
_lightness_handlers – [in] Lightness server callbacks.
_light_xyl_handlers – [in] Light xyL server callbacks.
-
BT_MESH_MODEL_LIGHT_XYL_SRV
(_srv)¶ Light XYL Server model composition data entry.
- Parameters
_srv – [in] Pointer to a Light xyL Server model instance.
Functions
-
int
bt_mesh_light_xyl_srv_pub
(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_xyl_status *status)¶ Publish the current xyL status.
Asynchronously publishes a xyL 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] Current status.
- 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.
-
int
bt_mesh_light_xyl_srv_target_pub
(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_xyl_status *status)¶ Publish the current xyL target status.
Asynchronously publishes a xyL target 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] Current status.
- 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.
-
int
bt_mesh_light_xyl_srv_range_pub
(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_model_status status_code)¶ Publish the current xyL Range status.
Asynchronously publishes a xyL Range 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_code – [in] The status code of the response.
- 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.
-
int
bt_mesh_light_xyl_srv_default_pub
(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx)¶ Publish the current xyL Default parameter status.
Asynchronously publishes a xyL Default parameter 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.
- 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_xy_set
¶ - #include <light_xyl_srv.h>
Light xy set parameters.
Public Members
-
struct bt_mesh_light_xy
params
¶ xy set parameters
-
struct bt_mesh_model_transition *
transition
¶ Transition time parameters for the state change, or NULL.
When sending, setting the transition to NULL makes the receiver use its default transition time parameters, or 0 if no default transition time is set.
-
struct bt_mesh_light_xy
-
struct
bt_mesh_light_xy_status
¶ - #include <light_xyl_srv.h>
Light xy status response parameters.
Public Members
-
struct bt_mesh_light_xy
current
¶ Current xy parameters
-
struct bt_mesh_light_xy
target
¶ Target xy parameters
-
int32_t
remaining_time
¶ Remaining time for the state change (ms).
-
struct bt_mesh_light_xy
-
struct
bt_mesh_light_xyl_srv_handlers
¶ - #include <light_xyl_srv.h>
Light xyL Server state access handlers.
Public Members
-
void (*const
xy_set
)(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_xy_set *set, struct bt_mesh_light_xy_status *rsp)¶ Set the xy state.
Note
This handler is mandatory.
- Parameters
srv – [in] Server to set the xy state of.
ctx – [in] Message context.
set – [in] Parameters of the state change.
rsp – [out] Response structure to be filled.
-
void (*const
xy_get
)(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_xy_status *rsp)¶ Get the xy state.
Note
This handler is mandatory.
- Parameters
srv – [in] Server to get the xy state of.
ctx – [in] Message context.
rsp – [out] Response structure to be filled.
-
void (*const
range_update
)(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_xy_range *old_range, const struct bt_mesh_light_xy_range *new_range)¶ The Range state has changed.
- Parameters
srv – [in] Server the Range state was changed on.
ctx – [in] Context of the set message that triggered the update.
old_range – [in] The old Range.
new_range – [in] The new Range.
-
void (*const
default_update
)(struct bt_mesh_light_xyl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_xy *old_default, const struct bt_mesh_light_xy *new_default)¶ The Default Parameter state has changed.
- Parameters
srv – [in] Server the Default Parameter state was changed on.
ctx – [in] Context of the set message that triggered the update.
old_default – [in] The old Default Parameters.
new_default – [in] The new Default Parameters.
-
void (*const
-
struct
bt_mesh_light_xyl_srv
¶ - #include <light_xyl_srv.h>
Light xyL Server instance. Should be initialized with BT_MESH_LIGHT_XYL_SRV_INIT.
Public Members
-
struct bt_mesh_model *
model
¶ Model entry.
-
struct bt_mesh_lightness_srv
lightness_srv
¶ Lightness Server instance.
-
struct bt_mesh_model_pub
pub
¶ Publish parameters.
-
struct bt_mesh_tid_ctx
prev_transaction
¶ Transaction ID tracker for the set messages.
-
struct bt_mesh_light_xy_range
range
¶ Current range parameters
-
const struct bt_mesh_light_xyl_srv_handlers *
handlers
¶ Handler function structure.
-
struct bt_mesh_light_xy
xy_last
¶ The last known xy Level.
-
struct bt_mesh_light_xy
xy_default
¶ The default xy Level.
-
struct bt_mesh_model *
-