Light Lightness Server

The Light Lightness Server represents a single light on a mesh device. It should be instantiated in the light fixture node.

The Light Lightness Server adds the following new model instances in the composition data, in addition to the extended Generic Level Server and Generic Power OnOff Server models:

  • Light Lightness Server

  • Light Lightness Setup Server

These model instances share the states of Light Lightness Server, but accept different messages. This allows for a fine-grained control of the access rights for the Light Lightness states, as these model instances can be bound to different application keys:

  • The Light Lightness Server only provides write access to the Light state for the user, in addition to read access to all the meta states.

  • The Light Lightness Setup Server provides write access to the Default Light and Light Range meta states. This allows the configurator devices to set up the range and the default value for the Light state.

States

The Generic Power OnOff Server model contains the following states:

Light: uint16_t

The Light state represents the emitted light level of an element, and ranges from 0 to 65535. The Light state is bound to the Generic Level State of the extended Generic Level Server:

Light (Actual) = Generic Level + 32768

The Generic OnOff state of Generic OnOff Server (extended through the Generic Power OnOff Server) is derived from the Light state:

Generic OnOff = (Light > 0)

Conversely, if the Generic OnOff state is changed to Off, the Light state is set to 0. If the Generic OnOff state is changed to On and the Default Light state is set, the Light state is set to the value of the Default Light state. If the Generic OnOff state is changed to On and the Default Light state is not set, the Light state is set to the last known non-zero value.

The Light state power-up behavior is determined by the On Power Up state of the extended Generic Power OnOff Server:

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

Note

If the Lightness Server is part of an xyL, CTL or HSL Server, it will publish the xyL, CTL or HSL status whenever the Light state changes. This is not handled automatically by the xyL, CTL or HSL Servers.

Default Light: int16_t

The Default Light state is a meta state that controls the default non-zero Light level. It is used when the light is turned on, but its exact level is 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.

Light Range: bt_mesh_lightness_range

The Light Range state is a meta state that determines the accepted Light level range.

If the Light level is set to a value outside the current Light Range, it is moved to fit inside the range.

If the Light Range changes to exclude the current Light level, the Light level should be changed accordingly.

Note

The Light level may always be set to zero, even if this is outside the current Light Range.

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

The Light Range state uses the configured lightness representation.

Extended models

The Light Lightness Server extends the following models:

As the states of both extended models are bound to states in the Light Lightness Server, the states of the extended models are not exposed directly to the application.

Persistent storage

The Light Lightness Server stores the following information:

  • Any changes to the Default Light and Light Range states.

  • The last known non-zero Light level.

  • Whether the light is on or off.

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

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

The Light Lightness Server can use the emergency data storage (EMDS) together with persistent storage for the following purposes:

  • 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 Lightness Server continues to store the default light and light range states to the flash memory through the settings library, but the last known non-zero Light level and whether the light is on or off are 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/lightness_srv.h
Source file: subsys/bluetooth/mesh/lightness_srv.c
group bt_mesh_lightness_srv

API for the Light Lightness Server.

Defines

BT_MESH_LIGHTNESS_SRV_INIT(_handlers)

Initialization parameters for Light Lightness Server model.

Parameters:

  • _handlers – [in] Handler callback structure.

BT_MESH_MODEL_LIGHTNESS_SRV(_srv)

Light Lightness model entry.

Parameters:

Functions

static inline uint16_t bt_mesh_lightness_clamp(const struct bt_mesh_lightness_srv *srv, uint16_t lightness)

Clamp lightness to lightness range.

Returns:

lightness clamped to the lightness range set on the Light Lightness Server model pointed to by srv if lightness > 0, zero otherwise.

int bt_mesh_lightness_srv_pub(struct bt_mesh_lightness_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_status *status)

Publish the current Light state.

Publishes a Light Lightness status message with the configured publish parameters, or using the given message context.

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

  • ctx – [in] Message context, or NULL to publish with the configured parameters.

  • status – [in] Status to publish.

Return values:

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

Returns:

0 Successfully published the current Light state.

struct bt_mesh_lightness_srv_handlers
#include <lightness_srv.h>

Collection of handler callbacks for the Light Lightness Server.

Public Members

void (*const light_set)(struct bt_mesh_lightness_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_set *set, struct bt_mesh_lightness_status *rsp)

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

When performing a non-instantaneous state change, the Light state at any intermediate point must be clamped to the current lightness range of the server using bt_mesh_lightness_clamp.

Note

This handler is mandatory.

Param srv:

[in] Server to set the Light state of.

Param ctx:

[in] Message context, or NULL if the state change was not a result of a message.

Param set:

[in] Parameters of the state change.

Param rsp:

[out] Response structure to be filled.

void (*const light_get)(struct bt_mesh_lightness_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_lightness_status *rsp)

Get the current Light state.

When in the middle of a non-instantaneous state change, the Light value filled in rsp must be clamped to the current lightness range of the server using bt_mesh_lightness_clamp.

Note

This handler is mandatory.

Param srv:

[in] Server to get the Light state of.

Param ctx:

[in] Context of the get message that triggered the query, or NULL if it was not triggered by a message.

Param rsp:

[out] Response structure to be filled.

void (*const default_update)(struct bt_mesh_lightness_srv *srv, struct bt_mesh_msg_ctx *ctx, uint16_t old_default, uint16_t new_default)

The Default Light state has changed.

The user may implement this handler to subscribe to changes to the Default Light state.

Param srv:

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

Param ctx:

[in] Context of the set message that triggered the update, or NULL if it was not triggered by a message.

Param old_default:

[in] The Default Light before the change.

Param new_default:

[in] The Default Light after the change.

void (*const range_update)(struct bt_mesh_lightness_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.

The user may implement this handler to subscribe to change to the Light Range state. If the change in range causes the current Light state to be out of range, the Light state should be changed to the nearest value inside the range. It’s recommended to call bt_mesh_lightness_srv_pub to notify the mesh if the Light state changes.

Param srv:

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

Param ctx:

[in] Context of the set message that triggered the update, or NULL if it was not triggered by a message.

Param old_range:

[in] The Light Range before the change.

Param new_range:

[in] The Light Range after the change.

struct bt_mesh_lightness_srv
#include <lightness_srv.h>

Light Lightness Server instance.

Should be initialized with BT_MESH_LIGHTNESS_SRV_INIT.

Public Members

struct bt_mesh_lvl_srv lvl

Light Level Server instance.

struct bt_mesh_ponoff_srv ponoff

Light Light OnOff server instance.

atomic_t flags

Internal flag state.

struct bt_mesh_model *lightness_model

Pointer to the model entry in the composition data.

struct bt_mesh_model *lightness_setup_model

Pointer to the Setup Server model entry in the composition data.

struct bt_mesh_model_pub pub

Model publication parameters.

struct bt_mesh_tid_ctx tid

Transaction ID tracker for the set messages.

const struct bt_mesh_lightness_srv_handlers *const handlers

User handler functions.

struct bt_mesh_lightness_range range

Current Light Level Range.

uint16_t default_light

Current Default Light Level.

uint16_t delta_start

The delta start Light Level

uint16_t last

The last known Light Level.

bool is_on

Whether the Light is on.

struct bt_mesh_light_ctrl_srv *ctrl

Acting controller, if enabled.