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 <elem_idx>
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.
elem_idx
- Element index where the model instance is found.
- mesh models lvl get
Get the current Generic Level state value.
- mesh models lvl set <lvl> [transition_time_ms [delay_ms]]
Set the Generic Level state value and wait for a response.
lvl
- Level state value to set.transition_time_ms
- If present, defines the transition time in the message in milliseconds.delay_ms
- If present, defines the delay in the message in milliseconds.
- mesh models lvl set-unack <lvl> [transition_time_ms [delay_ms]]
Set the Generic Level state value without requesting a response.
level
- Level state value to set.transition_time_ms
- If present, defines the transition time in the message in milliseconds.delay_ms
- If present, defines the delay in the message in milliseconds.
- mesh models lvl delta-set <delta> [transition_time_ms [delay_ms]]
Trigger a differential level state change for the server and wait for a response.
delta
- Translation from the original value.transition_time_ms
- If present, defines the transition time in the message in milliseconds.delay_ms
- If present, defines the delay in the message in milliseconds.
- mesh models lvl delta-set-unack <delta> [transition_time_ms [delay_ms]]
Trigger a differential level state change for the server without requesting a response.
delta
- Translation from the original value.transition_time_ms
- If present, defines the transition time in the message in milliseconds.delay_ms
- If present, defines the delay in the message in milliseconds.
- mesh models lvl move-set <delta> [transition_time_ms [delay_ms]]
Trigger a continuous level change for the server and wait for a response.
delta
- Translation to make for every transition step.transition_time_ms
- If present, defines the transition time in the message in milliseconds.delay_ms
- If present, defines the delay in the message in milliseconds.
- mesh models lvl move-set-unack <delta> [transition_time_ms [delay_ms]]
Trigger a continuous level change for the server without requesting a response.
delta
- Translation to make for every transition step.transition_time_ms
- If present, defines the transition time in the message in milliseconds.delay_ms
- If present, defines the delay in the message in milliseconds.
API documentation
include/bluetooth/mesh/gen_lvl_cli.h
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
- Parameters
_status_handler – [in] Optional status message handler.
-
BT_MESH_MODEL_LVL_CLI(_cli)
Generic Level Client model composition data entry.
- Parameters
_cli – [in] Pointer to a Generic Level Client model instance.
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.
-
struct bt_mesh_model *model
-
BT_MESH_LVL_CLI_INIT(_status_handler)