Light CTL Temperature Server

The Color-Tunable Light (CTL) Temperature Server represents a single light on a mesh device. It should be instantiated in the light fixture node.

The Light CTL Temperature Server is normally instantiated as part of the Light CTL Server model, but may be instantiated as a stand-alone model.

Two states can be used to configure the lighting output of 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 Temperature Server adds the following new model instances in the composition data, in addition to the extended Generic Level Server model:

  • Light CTL Temperature Server

States

Temperature: uint16_t

The Temperature state represents the color temperature of the tunable white light emitted by an element, and ranges from 800 to 20000.

The Temperature state is bound to the Generic Level State of the extended Generic Level Server:

Light CTL Temperature = T_MIN + (Generic Level + 32768) * (T_MAX - T_MIN) / 65535

In the above formula, T_MIN and T_MAX are values representing the Light CTL Temperature Range Min and Light CTL Temperature Range Max states.

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 formula:

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

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 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.

Access to the Temperature Range state can only be done when the Light CTL Temperature Server is associated with an instance of the Light CTL Server model. The default value for the Temperature Range is 800 for T_MIN, and 20000 for T_MAX.

Extended models

The Light CTL Temperature Server extends the following model:

The states of the extended model are bound to the states in the Light CTL Temperature Server, and not directly exposed to the application.

Persistent storage

The Light CTL Temperature Server stores the following information:

  • Any changes to the Default Light Temperature/Delta UV and Temperature Range states.

  • The last known Temperature level.

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

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

The Light CTL Temperature Server can use the emergency data storage (EMDS) together with persistent storage to:

  • 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 CTL Temperature Server continues to store the default light temperature and temperature range states to the flash memory through the settings library, but the last known color temperature level is stored by using the EMDS library. The values stored by EMDS will be lost at first boot when the CONFIG_EMDS is enabled. 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_temp_srv.h
Source file: subsys/bluetooth/mesh/light_temp_srv.c
group bt_mesh_light_temp_srv

API for the Light CTL Temperature Server model.

Defines

BT_MESH_LIGHT_TEMP_SRV_INIT(_handlers)

Initialization parameters for a Light Temperature Server model instance.

Parameters:

  • _handlers – [in] Light CTL Temperature Server callbacks.

BT_MESH_MODEL_LIGHT_TEMP_SRV(_srv)

Light CTL Temperature Server model composition data entry.

Parameters:

Functions

int bt_mesh_light_temp_srv_pub(struct bt_mesh_light_temp_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_status *status)

Publish the current CTL Temperature status.

Asynchronously publishes a CTL Temperature status message with the configured publish parameters.

Note

This API is only used for 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.

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_temp_srv_handlers
#include <light_temp_srv.h>

Light CTL Temperature Server state access handlers.

Public Members

void (*const set)(struct bt_mesh_light_temp_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_set *set, struct bt_mesh_light_temp_status *rsp)

Set the Light Temperature 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 Light Temperature state at the end of the transition.

Note

This handler is mandatory.

Param srv:

[in] Server to set the CTL Temperature state of.

Param ctx:

[in] Message context.

Param set:

[in] Parameters of the state change.

Param rsp:

[out] Response structure to be filled.

void (*const get)(struct bt_mesh_light_temp_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_temp_status *rsp)

Get the CTL Temperature state.

Note

This handler is mandatory.

Param srv:

[in] Server to get the CTL state of.

Param ctx:

[in] Message context.

Param rsp:

[out] Response structure to be filled.

void (*const range_update)(struct bt_mesh_light_temp_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_range *old_range, const struct bt_mesh_light_temp_range *new_range)

The Temperature Range state has changed.

Param srv:

[in] Server the Temperature Range state was changed on.

Param ctx:

[in] Context of the set message that triggered the update.

Param old_range:

[in] The old Temperature Range.

Param new_range:

[in] The new Temperature Range.

void (*const default_update)(struct bt_mesh_light_temp_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp *old_default, const struct bt_mesh_light_temp *new_default)

The Default Light Temperature has changed.

Param srv:

[in] Server the Default Light Temperature state was changed on.

Param ctx:

[in] Context of the set message that triggered the update.

Param old_default:

[in] The old Default Light Temperature.

Param new_default:

[in] The new Default Light Temperature.

struct bt_mesh_light_temp_srv
#include <light_temp_srv.h>

Light CTL Temperature Server instance. Should be initialized with BT_MESH_LIGHT_TEMP_SRV_INIT.

Public Members

struct bt_mesh_lvl_srv lvl

Light Level Server instance.

const struct bt_mesh_model *model

Model entry.

const struct bt_mesh_light_ctl_srv *ctl

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

struct bt_mesh_model_pub pub

Publish parameters.

struct bt_mesh_tid_ctx prev_transaction

Transaction ID tracker for the set messages.

const struct bt_mesh_light_temp_srv_handlers *handlers

Handler function structure.

struct bt_mesh_light_temp dflt

Default light temperature and delta UV

struct bt_mesh_light_temp_range range

Current Temperature range.

uint16_t corrective_delta

Corrective delta used by the generic level server.

struct bt_mesh_light_temp last

The last known color temperature.