Generic Level Server

The Generic Level Server model contains a single Generic Level state.

States

The Generic Level Server model contains the following state:

Generic Level: int16_t

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

Changes to the Generic Level state may include transition parameters. While transitioning to a new level, any request to read out the current level should report the following information:

  • Actual current level in the transition

  • Target level

  • Remaining time in milliseconds (including an optional delay)

If the transition includes a delay, the state must remain unchanged until the delay expires.

Extended models

None.

Persistent storage

None.

API documentation

Header file: include/bluetooth/mesh/gen_lvl_srv.h
Source file: subsys/bluetooth/mesh/gen_lvl_srv.c
group bt_mesh_lvl_srv

API for the Generic Level Server model.

Defines

BT_MESH_LVL_SRV_INIT(_handlers)

Initialization parameters for a Bluetooth Mesh Generic Level Server model instance.

Parameters:

  • _handlers – [in] Pointer to a handler function structure.

BT_MESH_MODEL_LVL_SRV(_srv)

Generic Level Server model composition data entry.

Parameters:

Functions

int bt_mesh_lvl_srv_pub(struct bt_mesh_lvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_status *status)

Publish the current Level state.

Parameters:

  • srv – [in] Server whose Level state should be published.

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

  • status – [in] Current status.

Return values:

  • 0 – Successfully published a Generic Level Status message.

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

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_lvl_srv_handlers
#include <gen_lvl_srv.h>

Handler functions for the Generic Level Server.

Public Members

void (*const get)(struct bt_mesh_lvl_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_lvl_status *rsp)

Get the current Level state.

Note

This handler is mandatory.

Param srv:

[in] Level server to get the state of.

Param ctx:

[in] Message context for the message that triggered the request, or NULL if the request is not coming from a message.

Param rsp:

[out] Response structure to be filled.

void (*const set)(struct bt_mesh_lvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_set *set, struct bt_mesh_lvl_status *rsp)

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

Note

This handler is mandatory.

Param srv:

[in] Level server to set the state of.

Param ctx:

[in] Message context for the message that triggered the change, or NULL if the change is not coming from a message.

Param set:

[in] Parameters of the state change. Note that the transition will always be non-NULL.

Param rsp:

[out] Response structure to be filled.

void (*const delta_set)(struct bt_mesh_lvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_delta_set *delta_set, struct bt_mesh_lvl_status *rsp)

Change the Level state relative to its current value.

If delta_set::new_transaction is false, the state transition should use the same start point as the previous delta_set message, effectively overriding the previous message. If it is true, the level transition should start from the current level, stopping any ongoing transitions.

Note

This handler is mandatory.

Param srv:

[in] Level server to change the state of.

Param ctx:

[in] Message context for the message that triggered the change, or NULL if the change is not coming from a message.

Param delta_set:

[in] Parameters of the state change. Note that the transition will always be non-NULL.

Param rsp:

[out] Response structure to be filled.

void (*const move_set)(struct bt_mesh_lvl_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_move_set *move_set, struct bt_mesh_lvl_status *rsp)

Move the Level state continuously at a given rate.

The Level state should move move_set::delta units for every move_set::transition::time milliseconds. For instance, if delta is 5 and the transition time is 100ms, the state should move at a rate of 50 per second.

When reaching the border values for the state, the wraparound behavior is application specific. While the server is executing a move command, it should report its target value as BT_MESH_LVL_MIN or BT_MESH_LVL_MAX, depending on whether it is moving up or down.

Note

This handler is mandatory.

Param srv:

[in] Level server to change the state of.

Param ctx:

[in] Message context for the message that triggered the change, or NULL if the change is not coming from a message.

Param move_set:

[in] Parameters of the state change. Note that the transition will always be non-NULL.

Param rsp:

[out] Response structure to be filled.

struct bt_mesh_lvl_srv
#include <gen_lvl_srv.h>

Generic Level Server instance. Should be initialized with the BT_MESH_LVL_SRV_INIT macro.

Public Members

const struct bt_mesh_lvl_srv_handlers *const handlers

Application handler functions.

const struct bt_mesh_model *model

Pointer to the mesh model entry.

struct bt_mesh_model_pub pub

Model publication parameters.

struct bt_mesh_tid_ctx tid

Transaction ID tracking.