Generic Power Level Client

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

Unlike the Generic Power Level Server model, the Generic Power Level Client only creates a single model instance in the mesh composition data. The Generic Power Level Client may send messages to both the Generic Power Level Server and the Generic Power Level Setup Server, as long as it has the right application keys.

Extended models

None.

Persistent storage

None.

Shell commands

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

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

mdl_plvl instance get-all

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

mdl_plvl instance set <elem_idx>

Select the Generic Power 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.

mdl_plvl get

Get the Power Level of the bound server.

mdl_plvl set <lvl> [transition_time_ms [delay_ms]]

Set the Power Level of the server and wait for a response.

  • lvl - Power Level 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.

mdl_plvl set-unack <lvl> [transition_time_ms [delay_ms]]

Set the Power Level of the server without requesting a response.

  • lvl - Power Level 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.

mdl_plvl range-get

Get the Power Range of the bound server.

mdl_plvl range-set <min> <max>

Set the Power Range state value and wait for a response.

  • min - Minimum allowed Power Level.

  • max - Maximum allowed Power Level.

mdl_plvl range-set-unack <min> <max>

Set the Generic Power Range state value without requesting a response.

  • min - Minimum allowed Power Level.

  • max - Maximum allowed Power Level.

mdl_plvl default-get

Get the Default Power state of the bound server.

mdl_plvl default-set <lvl>

Set the Default Power state of the server and wait for a response.

  • lvl - Default Power value to set.

mdl_plvl default-set-unack <lvl>

Set the Default Power state of the server without requesting a response.

  • lvl - Default Power value to set.

mdl_plvl last-get

Get the last non-zero Power Level of the bound server.

API documentation

Header file: include/bluetooth/mesh/gen_plvl_cli.h
Source file: subsys/bluetooth/mesh/gen_plvl_cli.c
group bt_mesh_plvl_cli

API for the Generic Power Level Client model.

Defines

BT_MESH_PLVL_CLI_INIT(_handlers)

Initialization parameters for the Generic Power Level Client model.

See also

bt_mesh_plvl_cli_handlers.

Parameters

  • _handlers – [in] Optional message handler structure.

BT_MESH_MODEL_PLVL_CLI(_cli)

Generic Power Level Client model composition data entry.

Parameters

Functions

int bt_mesh_plvl_cli_power_get(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_plvl_status *rsp)

Get the Power Level 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_plvl_cli_handlers::power_status 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_plvl_cli_power_set(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_set *set, struct bt_mesh_plvl_status *rsp)

Set the Power Level of 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_plvl_cli_handlers::power_status callback.

Parameters

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

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

  • set – [in] New Power 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_plvl_cli_power_set_unack(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_set *set)

Set the Power Level of 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 Power 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_plvl_cli_range_get(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_plvl_range_status *rsp)

Get the Power Range 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_plvl_cli_handlers::range_status 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_plvl_cli_range_set(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_range *range, struct bt_mesh_plvl_range_status *rsp)

Set the Power Range 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_plvl_cli_handlers::range_status callback.

Parameters

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

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

  • range – [in] New Power Range value to set.

  • 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_plvl_cli_range_set_unack(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_range *range)

Set the Power Range 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.

  • range – [in] New Power Range value to set.

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_plvl_cli_default_get(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t *rsp)

Get the Default Power 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_plvl_cli_handlers::default_status 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_plvl_cli_default_set(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t default_power, uint16_t *rsp)

Set the Default Power 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_plvl_cli_handlers::default_status callback.

Parameters

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

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

  • default_power – [in] New Default Power value to set.

  • 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_plvl_cli_default_set_unack(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t default_power)

Set the Default Power 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.

  • default_power – [in] New Default Power value to set.

Return values

  • 0 – Successfully sent the message.

  • -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_plvl_cli_last_get(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t *rsp)

Get the last non-zero Power Level of the bound server.

The last non-zero Power Level is the Power Level that will be restored if the Power Level changes from off to on and no Default Power is set.

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_plvl_cli_handlers::last_status 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.

struct bt_mesh_plvl_cli_handlers
#include <gen_plvl_cli.h>

Handler function for the Power Level Client.

Public Members

void (*const power_status)(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_status *status)

Power Level status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Generic Power Level status contained in the message.

void (*const default_status)(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t default_power)

Default Power status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param default_power

[in] Default Power Level of the server.

void (*const range_status)(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_plvl_range_status *status)

Power Range status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Power Range state of the server.

void (*const last_status)(struct bt_mesh_plvl_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t last)

Last non-zero Power Level status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param last

[in] Last non-zero Power Level of the server.

struct bt_mesh_plvl_cli
#include <gen_plvl_cli.h>

Generic Power Level Client instance. Should be initialized with BT_MESH_PLVL_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.

const struct bt_mesh_plvl_cli_handlers *const handlers

Collection of handler callbacks