Generic Power Level Server

The Generic Power Level Server controls the output power level of a peripheral on the mesh-enabled device.

Generic Power Level Server adds two model instances in the composition data:

  • The Generic Power Level Server

  • The Generic Power Level Setup Server

The two model instances share the states of the Generic Power Level Server, but accept different messages. This allows fine-grained control of the access rights for the Generic Power Level states, as the two model instances can be bound to different application keys.

The Generic Power Level Server is the user-facing model instance in the pair, and only provides access to the Generic Power Level state, and its last non-zero value.

The Generic Power Level Setup Server provides access to the two metastates, Default Power and Power Range, allowing configurator devices to set up the range and default value for the Generic Power Level state.

States

The following states are available:

Generic Power Level: (uint16_t)

The Generic Power Level state controls the power level of an element, and ranges from 0 to 65535. The Generic Power Level state is bound to the Generic Level State of the Generic Level Server:

Generic Power Level = Generic Level + 32768

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

Generic OnOff = Generic Power Level > 0

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

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

The user is expected to hold the state memory and provide access to the state through the bt_mesh_plvl_srv_handlers handler structure.

Default Power: (int16_t)

The Default Power state is a metastate that controls the default non-zero Generic Power Level. It is used when the Generic Power Level turns on, but its exact level is not specified.

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

Power Range: (bt_mesh_plvl_range)

The Power Range state is a metastate that determines the accepted Generic Power Level range.

If the Generic Power Level is set to a value outside the current Power Range, the actual Generic Power Level is moved to fit inside the range.

If the Power Level Range changes to exclude the current Generic Power Level, the Generic Power Level should be changed accordingly. Note that the Generic Power Level may always be set to zero, even if this is outside the current Power Range.

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

Extended models

The Generic Power Level Server extends the following models:

As the states of both extended models are bound to states in the Generic Power Level Server, the states of the extended models are not exposed directly to the application.

Persistent storage

The Generic Power Level Server stores any changes to the Default Power and Power Range states, as well as the last known non-zero Generic Power Level and whether the Generic Power Level is on or off. This information is used to reestablish the correct Generic Power Level when the device powers up.

If option CONFIG_BT_SETTINGS is enabled, the Generic Power Level Server stores all its states persistently using a configurable storage delay to stagger storing. See CONFIG_BT_MESH_STORE_TIMEOUT.

The Generic Power Level 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 Generic Power Level Server continues to store the default power and power range states to the flash memory through the settings library, but the last known level and whether the Generic Power Level 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/gen_plvl_srv.h
Source file: subsys/bluetooth/mesh/gen_plvl_srv.c
group bt_mesh_plvl_srv

API for the Generic Power Level Server.

Defines

BT_MESH_PLVL_SRV_INIT(_handlers)

Initialization parameters for Generic Power Level Server model.

Parameters:

  • _handlers – [in] Handler callback structure.

BT_MESH_MODEL_PLVL_SRV(_srv)

Generic Power Level model entry.

Parameters:

Functions

int bt_mesh_plvl_srv_pub(struct bt_mesh_plvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_status *status)

Publish the current Power state.

Publishes a Generic Power Level 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 Power state.

struct bt_mesh_plvl_srv_handlers
#include <gen_plvl_srv.h>

Collection of handler callbacks for the Generic Power Level Server.

Public Members

void (*const power_set)(struct bt_mesh_plvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_set *set, struct bt_mesh_plvl_status *rsp)

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

Note

This handler is mandatory.

Param srv:

[in] Server to set the Power 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 power_get)(struct bt_mesh_plvl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_plvl_status *rsp)

Get the current Power state.

Note

This handler is mandatory.

Param srv:

[in] Server to get the Power 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_plvl_srv *srv, struct bt_mesh_msg_ctx *ctx, uint16_t old_default, uint16_t new_default)

The Default Power state has changed.

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

Param srv:

[in] Server the Default Power 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 Power before the change.

Param new_default:

[in] The Default Power after the change.

void (*const range_update)(struct bt_mesh_plvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_range *old_range, const struct bt_mesh_plvl_range *new_range)

The Power Range state has changed.

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

Param srv:

[in] Server the Power 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 Power Range before the change.

Param new_range:

[in] The Power Range after the change.

struct bt_mesh_plvl_srv
#include <gen_plvl_srv.h>

Generic Power Level Server instance.

Should be initialized with BT_MESH_PLVL_SRV_INIT.

Public Members

struct bt_mesh_lvl_srv lvl

Generic Level Server instance.

struct bt_mesh_ponoff_srv ponoff

Generic Power OnOff server instance.

const struct bt_mesh_model *plvl_model

Pointer to the model entry in the composition data.

const struct bt_mesh_model *plvl_setup_model

Pointer to the model entry of the Setup Server.

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_plvl_srv_handlers *const handlers

User handler functions.

struct bt_mesh_plvl_range range

Current Power Range.

uint16_t default_power

Current Default Power.

uint16_t last

The last known Power Level.

bool is_on

Whether the Power is on.