Light CTL Server¶

States
Extended models
Persistent storage
API documentation

The Color-Tunable Light (CTL) Server represents a single light on a mesh device. 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.
Temperature - This state determines the color temperature of tunable white light emitted by an element.
Delta UV - This state determines the distance from the black body curve. The color temperatures fall on the black body locus.

The Light CTL 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 CTL Server, but accept different messages. This allows for a fine-grained control of the access rights for the Light CTL states, as the model instances can be bound to different application keys. The following two model instances are added:

Light CTL Server - Provides write access to Lightness, Temperature and Delta UV states for the user, in addition to read access to all meta states
Light CTL Setup Server - Provides write access to Default CTL state and Temperature Range meta states, allowing configurator devices to set up a temperature range and a default CTL state

In addition to the extended Lightness Server model, the Light CTL Server also requires a Light CTL Temperature Server to be instantiated on a subsequent element. The Light Temperature Server should reference the bt_mesh_light_ctl_srv.temp_srv.

Conventionally, the Light Temperature Server model is instantiated on the very next element, and the composition data looks as presented below.

static struct bt_mesh_light_ctl_srv light_ctl_srv = BT_MESH_LIGHT_CTL_SRV_INIT(&light_ctl_handlers);

static struct bt_mesh_elem elements[] = {
    BT_MESH_ELEM(
        1,
        BT_MESH_MODEL_LIST(BT_MESH_MODEL_LIGHT_CTL_SRV(&light_ctl_srv)),
        BT_MESH_MODEL_NONE),
    BT_MESH_ELEM(
        2,
        BT_MESH_MODEL_LIST(BT_MESH_MODEL_LIGHT_TEMP_SRV(&light_ctl_srv.temp_srv)),
        BT_MESH_MODEL_NONE),
};

Note

The Light CTL Server will verify that its internal Light Temperature Server is instantiated on a subsequent element on startup. If the Light Temperature Server is missing or instantiated on the same or a preceding element, the Bluetooth Mesh startup procedure will fail, and the device will not be responsive.

States ¶

The Generic Power OnOff Server model (extended by the Lightness Server model) contains the following states:

Lightness: uint16_t

The Lightness state represents the emitted light level of an element, and ranges from 0 to 65535. 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 to 0 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).

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

Temperature: uint16_t

The Temperature state represents the color temperature of the tunable white light emitted by an element. It ranges from 800 to 20000, and is shared by the assosiated Light CTL Temperature Server.

The Temperature 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 Temperature state is set to Default Temperature on power-up.
BT_MESH_ON_POWER_UP_ON - The Temperature state is set to Default Temperature on power-up.
BT_MESH_ON_POWER_UP_RESTORE - The Temperature state is set to the last known Temperature level.

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

Delta UV: int16_t

The Temperature state represents the distance from the black body curve. The color temperatures all fall on the black body locus (curve). This is a 16-bit signed integer representation of a -1 to +1 scale using the following formula:

Represented Delta UV = (Light CTL Delta UV) / 32768

The Delta UV state of the Light CTL Server is shared by the assosiated Light CTL Temperature Server, and its 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 Delta UV state is set to Default Delta UV on power-up.
BT_MESH_ON_POWER_UP_ON - The Delta UV state is set to Default Delta UV on power-up.
BT_MESH_ON_POWER_UP_RESTORE - The Delta UV state is set to the last known Delta UV level.

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

Default CTL: bt_mesh_light_ctl

The Default CTL state is a meta state that controls the default Lightness, Temperature and Delta UV level. It is used when the light is turned on, but its exact state levels are not specified.

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

The Default Light state uses the configured lightness representation.

Temperature Range: bt_mesh_light_temp_range

The Temperature Range state is a meta state that determines the accepted Temperature level range. If the Temperature level is set to a value outside the current Temperature Range, it is moved to fit inside the range. If the Temperature Range changes to exclude the current Temperature level, the Temperature level should be changed accordingly.

The Temperature Range state of the Light CTL Server is shared by the assosiated Light CTL Temperature Server.

The memory for the Temperature Range state is held by the model, and the application may receive updates on state changes through the bt_mesh_light_ctl_srv_handlers.temp_range_update callback.

Extended models ¶

The Light CTL Server extends the following model:

Light Lightness Server

The state of the extended Lightness Server model is for the most part bound to states in the Light CTL Server. The only exception is the Lightness range state, which is exposed to the application through the bt_mesh_light_ctl_srv_handlers.lightness_range_update callback of the Light CTL Server model.

In addition to the extended Lightness Server model, the Light CTL Server model is associated with a Light Temperature model on a subsequent element. Contrary to the extended models, the associated models do not share subscription lists, but still share states.

Persistent storage ¶

The Light CTL Server stores the following information:

Any changes to the Default CTL and Temperature Range states
The last known Lightness, Temperature and Delta UV level

This information is used to reestablish the correct Light configuration when the device powers up.

API documentation ¶

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

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

group bt_mesh_light_ctl_srv

API for the Light CTL Server model.

Defines

BT_MESH_LIGHT_CTL_SRV_INIT(_handlers)¶

Initialization parameters for a Light CTL Server model instance.

Parameters

[in] _handlers: Light CTL server callbacks.

BT_MESH_MODEL_LIGHT_CTL_SRV(_srv)¶

Light CTL Server model composition data entry.

Parameters

[in] _srv: Pointer to a Light CTL Server model instance.

Functions

int32_t bt_mesh_light_ctl_pub(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_ctl_status *status)¶

Publish the current CTL status.

Asynchronously publishes a CTL 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

[in] srv: Server instance to publish on.
[in] ctx: Message context to send with, or NULL to send with the default publish parameters.
[in] status: Current status.

Return Value

0: Successfully published a Generic OnOff Status message.
-ENOTSUP: A message context was not provided and publishing is not supported.
-EADDRNOTAVAIL: A message context was not provided and publishing is not configured.
-EAGAIN: The device has not been provisioned.

int32_t bt_mesh_light_ctl_range_pub(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_model_status status)¶

Publish the current CTL Range status.

Asynchronously publishes a CTL 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

[in] srv: Server instance to publish on.
[in] ctx: Message context to send with, or NULL to send with the default publish parameters.
[in] status: Current status.

Return Value

0: Successfully published a Generic OnOff Status message.
-ENOTSUP: A message context was not provided and publishing is not supported.
-EADDRNOTAVAIL: A message context was not provided and publishing is not configured.
-EAGAIN: The device has not been provisioned.

int32_t bt_mesh_light_ctl_default_pub(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx)¶

Publish the current CTL Default status.

Asynchronously publishes a CTL Default 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

[in] srv: Server instance to publish on.
[in] ctx: Message context to send with, or NULL to send with the default publish parameters.

Return Value

0: Successfully published a Generic OnOff Status message.
-ENOTSUP: A message context was not provided and publishing is not supported.
-EADDRNOTAVAIL: A message context was not provided and publishing is not configured.
-EAGAIN: The device has not been provisioned.

struct bt_mesh_light_ctl_rsp¶

#include <light_ctl_srv.h>

Generic status response structure for CTL messages.

Public Members

struct bt_mesh_light_ctl current¶: Current CTL parameters

struct bt_mesh_light_ctl target¶: Target CTL parameters

int32_t remaining_time¶: Remaining time for the state change (ms).

struct bt_mesh_light_ctl_gen_cb_set¶

#include <light_ctl_srv.h>

Generic set structure for CTL messages.

Public Members

uint16_t *light¶

Pointer to new Light level to set.

Note: NULL if not applicable.

uint16_t *temp¶

Pointer to new Temperature level to set.

Note: NULL if not applicable.

int16_t *delta_uv¶

Pointer to new Delta UV level to set.

Note: NULL if not applicable.

uint32_t time¶: Transition time value in milliseconds.

uint32_t delay¶: Message execution delay in milliseconds.

struct bt_mesh_light_ctl_srv_handlers¶

#include <light_ctl_srv.h>

Light CTL Server state access handlers.

Public Members

void (*const set)(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl_gen_cb_set *set, struct bt_mesh_light_ctl_rsp *rsp)¶

Set the CTL state.

Note

This handler is mandatory.

Parameters

[in] srv: Server to set the CTL state of.
[in] ctx: Message context.
[in] set: Parameters of the state change.
[out] rsp: Response structure to be filled.

void (*const get)(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_ctl_rsp *rsp)¶

Get the CTL state.

Note

This handler is mandatory.

Parameters

[in] srv: Server to get the CTL state of.
[in] ctx: Message context.
[out] rsp: Response structure to be filled.

void (*const temp_range_update)(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_range *set)¶

The Temperature Range state has changed.

Parameters

[in] srv: Server the Temperature Range state was changed on.
[in] ctx: Context of the set message that triggered the update.
[in] set: The new Temperature Range.

void (*const default_update)(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl *set)¶

The Default Parameter state has changed.

Parameters

[in] srv: Server the Default Parameter state was changed on.
[in] ctx: Context of the set message that triggered the update.
[in] set: The new Default Parameters.

void (*const lightness_range_update)(struct bt_mesh_light_ctl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_range *old_range, const struct bt_mesh_lightness_range *new_range)¶

The Light Range state has changed.

Parameters

[in] srv: Server the Light Range state was changed on.
[in] ctx: Context of the set message that triggered the update, or NULL if it was not triggered by a message.
[in] old_range: The Light Range before the change.
[in] new_range: The Light Range after the change.

struct bt_mesh_light_ctl_srv¶

#include <light_ctl_srv.h>

Light CTL Server instance. Should be initialized with BT_MESH_LIGHT_CTL_SRV_INIT.

Public Members

struct bt_mesh_model *model¶: Model entry.

struct bt_mesh_light_temp_srv temp_srv¶: Light CTL Temp. Server instance.

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_model_pub setup_pub¶: Setup model publish parameters

struct bt_mesh_model_ack_ctx ack_ctx¶: Acknowledged message tracking.

struct bt_mesh_light_ctl default_params¶: Model state structure

const struct bt_mesh_light_ctl_srv_handlers *handlers¶: Handler function structure.

struct bt_mesh_scene_entry scene¶: Scene entry

Light CTL Server¶

States¶

Extended models¶

Persistent storage¶

API documentation¶

States ¶

Extended models ¶

Persistent storage ¶

API documentation ¶