Generic Level Client

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

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.