Generic Level Client

The Generic Level Client model remotely controls the state of a Generic Level Server model.

Extended models

None.

Persistent storage

None.

Shell commands

The Bluetooth mesh shell subsystem provides a set of commands to interact with the Generic Level Client model instantiated on a device.

To make these commands available, enable the following Kconfig options:

mesh models lvl instance get-all

Print all instances of the Generic Level Client model on the device.

mesh models lvl instance set <ElemIdx>

Select the Generic Level Client model instantiated on the specified element ID. This instance will be used in message sending. If no model instance is selected, the first model instance found on the device will be used by default.

  • ElemIdx - Element index where the model instance is found.

mesh models lvl get

Get the current Generic Level state value.

mesh models lvl set <Lvl> [TransTime(ms) [Delay(ms)]]

Set the Generic Level state value and wait for a response.

  • Lvl - Level state value to set.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models lvl set-unack <Lvl> [TransTime(ms) [Delay(ms)]]

Set the Generic Level state value without requesting a response.

  • Lvl - Level state value to set.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models lvl delta-set <Dlt> [TransTime(ms) [Delay(ms)]]

Trigger a differential level state change for the server and wait for a response.

  • Dlt - Translation from the original value.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models lvl delta-set-unack <Dlt> [TransTime(ms) [Delay(ms)]]

Trigger a differential level state change for the server without requesting a response.

  • Dlt - Translation from the original value.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models lvl move-set <Dlt> [TransTime(ms) [Delay(ms)]]

Trigger a continuous level change for the server and wait for a response.

  • Dlt - Translation to make for every transition step.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models lvl move-set-unack <Dlt> [TransTime(ms) [Delay(ms)]]

Trigger a continuous level change for the server without requesting a response.

  • Dlt - Translation to make for every transition step.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

API documentation

Header file: include/bluetooth/mesh/gen_lvl_cli.h
Source file: subsys/bluetooth/mesh/gen_lvl_cli.c
group bt_mesh_lvl_cli

API for the Generic Level Client model.

Defines

BT_MESH_LVL_CLI_INIT(_status_handler)

Initialization parameters for the Generic Level Client model.

See also

bt_mesh_lvl_cli::status_handler

Parameters:

  • _status_handler – [in] Optional status message handler.

BT_MESH_MODEL_LVL_CLI(_cli)

Generic Level Client model composition data entry.

Parameters:

Functions

int bt_mesh_lvl_cli_get(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_lvl_status *rsp)

Get the status of the bound server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_lvl_cli::status_handler callback.

Parameters:

  • cli – [in] Client model to send on.

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

  • rsp – [out] Status response buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

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

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_lvl_cli_set(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_set *set, struct bt_mesh_lvl_status *rsp)

Set the level state in the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_lvl_cli::status_handler callback.

Parameters:

  • cli – [in] Client model to send on.

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

  • set – [in] New level value to set. Set set::transition to NULL to use the server’s default transition parameters.

  • rsp – [out] Response status buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

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

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_lvl_cli_set_unack(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_set *set)

Set the level state in the server without requesting a response.

Parameters:

  • cli – [in] Client model to send on.

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

  • set – [in] New level value to set. Set set::transition to NULL to use the server’s default transition parameters.

Return values:

  • 0 – Successfully sent the message.

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

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_lvl_cli_delta_set(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_delta_set *delta_set, struct bt_mesh_lvl_status *rsp)

Trigger a differential level state change in the server.

Makes the server move its level state by some delta value. If multiple delta_set messages are sent in a row (with less than 6 seconds interval), and delta_set::new_transaction is set to false, the server will continue using the same base value for its delta as in the first message, unless some other client made changes to the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_lvl_cli::status_handler callback.

Parameters:

  • cli – [in] Client model to send on.

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

  • delta_set – [in] State change to make. Set set::transition to NULL to use the server’s default transition parameters.

  • rsp – [out] Response status buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

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

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_lvl_cli_delta_set_unack(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_delta_set *delta_set)

Trigger a differential level state change in the server without requesting a response.

Makes the server move its level state by some delta value. If multiple delta_set messages are sent in a row (with less than 6 seconds interval), and delta_set::new_transaction is set to false, the server will continue using the same base value for its delta as in the first message, unless some other client made changes to the server.

Parameters:

  • cli – [in] Client model to send on.

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

  • delta_set – [in] State change to make. Set set::transition to NULL to use the server’s default transition parameters.

Return values:

  • 0 – Successfully sent the message.

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

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_lvl_cli_move_set(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_move_set *move_set, struct bt_mesh_lvl_status *rsp)

Trigger a continuous level change in the server.

Makes the server continuously move its level state by the set rate:

rate_of_change = move_set->delta / move_set->transition->time

The server will continue moving its level until it is told to stop, or until it reaches some application specific boundary value. The server may choose to wrap around the level value, depending on its usage. The move can be stopped by sending a new move message with a delta value of 0.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_lvl_cli::status_handler callback.

Parameters:

  • cli – [in] Client model to send on.

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

  • move_set – [in] State change to make. Set set::transition to NULL to use the server’s default transition parameters.

  • rsp – [out] Response status buffer, or NULL to keep from blocking.

Return values:

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

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

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_lvl_cli_move_set_unack(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_move_set *move_set)

Trigger a continuous level change in the server without requesting a response.

Makes the server continuously move its level state by the set rate:

rate_of_change = move_set->delta / move_set->transition->time

The server will continue moving its level until it is told to stop, or until it reaches some application specific boundary value. The server may choose to wrap around the level value, depending on its usage. The move can be stopped by sending a new move message with a delta value of 0.

Parameters:

  • cli – [in] Client model to send on.

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

  • move_set – [in] State change to make. Set set::transition to NULL to use the server’s default transition parameters.

Return values:

  • 0 – Successfully sent the message.

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

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_lvl_cli
#include <gen_lvl_cli.h>

Generic Level Client instance.

Should be initialized with BT_MESH_LVL_CLI_INIT.

Public Members

struct bt_mesh_model *model

Model entry.

struct bt_mesh_model_pub pub

Publish parameters.

struct bt_mesh_msg_ack_ctx ack_ctx

Acknowledged message tracking.

uint8_t tid

Current transaction ID.

void (*const status_handler)(struct bt_mesh_lvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lvl_status *status)

Level status message handler.

Param cli:

[in] Client that received the status message.

Param ctx:

[in] Context of the message.

Param status:

[in] Generic level status contained in the message.