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

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

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.

Returns

0 Successfully published the current Light state.

Returns

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

  • -EAGAIN – The device has not been provisioned.

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.

Note

This handler is mandatory.

Parameters

  • srv – [in] Server to set the Light state of.

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

  • set – [in] Parameters of the state change.

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

Note

This handler is mandatory.

Parameters

  • srv – [in] Server to get the Light state of.

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

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

Parameters

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

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

  • old_default – [in] The Default Light before the change.

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

Parameters

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

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

  • old_range – [in] The Light Range before the change.

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

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 last

The last known Light Level.

uint16_t delta_start

The delta start Light Level

atomic_t flags

Internal flag state.