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

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.