Light Lightness Client

The Light Lightness Client model remotely controls the state of a Light Lightness Server model.

Unlike the Light Lightness Server model, the Light Lightness Client only creates a single model instance in the mesh composition data. The Light Lightness Client can send messages to both the Light Lightness Server and the Light Lightness 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 Light Lightness Client model instantiated on a device.

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

mdl_lightness instance get-all

Print all instances of the Light Lightness Client model on the device.

mdl_lightness instance set <elem_idx>

Select the Light Lightness 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_lightness get

Get the Light Level value of the bound server.

mdl_lightness set <lightness_actual>|<lightness_linear> [transition_time_ms [delay_ms]]

Set the Light Level value and wait for a response.

  • lightness_actual|lightness_linear - The Light Level value to be set. By default, the Actual representation of the value is used. If CONFIG_BT_MESH_LIGHTNESS_LINEAR is enabled, the Linear representation of the value is used.

  • 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_lightness set-unack <lightness_actual>|<lightness_linear> [transition_time_ms [delay_ms]]

Set the Light Level value without requesting a response.

  • lightness_actual|lightness_linear - The Light Level value to be set. By default, the Actual representation of the value is used. If CONFIG_BT_MESH_LIGHTNESS_LINEAR is enabled, the Linear representation of the value is used.

  • 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_lightness range-get

Get the Light Range state value of the bound server.

mdl_lightness range-set <min> <max>

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

  • min - Minimum allowed Light Level value.

  • max - Maximum allowed Light Level value.

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

Set the Light Range state value without requesting a response.

  • min - Minimum allowed Light Level value.

  • max - Maximum allowed Light Level value.

mdl_lightness default-get

Get the Default Light state value of the bound server.

mdl_lightness default-set <lvl>

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

  • lvl - The Default Light state value to be set.

mdl_lightness default-set-unack <lvl>

Set the Default Light state value of the server without requesting a response.

  • lvl - The Default Light state value to be set.

mdl_lightness last-get

Get the last non-zero Light Level value of the bound server.

API documentation

Header file: include/bluetooth/mesh/lightness_cli.h
Source file: subsys/bluetooth/mesh/lightness_cli.c
group bt_mesh_lightness_cli

API for the Light Lightness Client model.

Defines

BT_MESH_LIGHTNESS_CLI_INIT(_handlers)

Initialization parameters for the Light Lightness Client model.

See also

bt_mesh_lightness_cli_handlers

Parameters

  • _handlers – [in] Optional message handler structure.

BT_MESH_MODEL_LIGHTNESS_CLI(_cli)

Light Lightness Client model composition data entry.

Parameters

Functions

int bt_mesh_lightness_cli_light_get(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_lightness_status *rsp)

Get the Light Level of the bound server.

By default, the ACTUAL representation will be used. LINEAR representation can be configured by defining CONFIG_BT_MESH_LIGHTNESS_LINEAR.

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_lightness_cli_handlers::light_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_lightness_cli_light_set(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_set *set, struct bt_mesh_lightness_status *rsp)

Set the Light Level of the server.

By default, the ACTUAL representation will be used. LINEAR representation can be configured by defining CONFIG_BT_MESH_LIGHTNESS_LINEAR.

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_lightness_cli_handlers::light_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 Light 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_lightness_cli_light_set_unack(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_set *set)

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

By default, the ACTUAL representation will be used. LINEAR representation can be configured by defining CONFIG_BT_MESH_LIGHTNESS_LINEAR.

Parameters

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

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

  • set – [in] New Light 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_lightness_cli_range_get(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_lightness_range_status *rsp)

Get the Light 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_lightness_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_lightness_cli_range_set(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_range *range, struct bt_mesh_lightness_range_status *rsp)

Set the Light 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_lightness_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 Light 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_lightness_cli_range_set_unack(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_range *range)

Set the Light 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 Light 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_lightness_cli_default_get(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t *rsp)

Get the Default Light 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_lightness_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_lightness_cli_default_set(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t default_light, uint16_t *rsp)

Set the Default Light 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_lightness_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_light – [in] New Default Light 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_lightness_cli_default_set_unack(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t default_light)

Set the Default Light 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_light – [in] New Default Light 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_lightness_cli_last_get(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t *rsp)

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

The last non-zero Light Level is the Light Level that will be restored if the Light Level changes from off to on and no Default Light 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_lightness_cli_handlers::last_light_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_lightness_cli_handlers
#include <lightness_cli.h>

Handler function for the Light Lightness Client.

Public Members

void (*const light_status)(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_status *status)

Light Level status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Light Lightness status contained in the message.

void (*const default_status)(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t default_light)

Default Light status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param default_light

[in] Default Light Level of the server.

void (*const range_status)(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_lightness_range_status *status)

Light Range status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Light Range state of the server.

void (*const last_light_status)(struct bt_mesh_lightness_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t last)

Last non-zero Light 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 Light Level of the server.

struct bt_mesh_lightness_cli
#include <lightness_cli.h>

Light Lightness Client instance. Should be initialized with BT_MESH_LIGHTNESS_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_lightness_cli_handlers *const handlers

Collection of handler callbacks