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.

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

bt_mesh_lightness_cli_handlers

Parameters

  • [in] _handlers: 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

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

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

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

Return Value

  • 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

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

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

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

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

Return Value

  • 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

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

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

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

Return Value

  • 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

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

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

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

Return Value

  • 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

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

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

  • [in] range: New Light Range value to set.

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

Return Value

  • 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

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

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

  • [in] range: New Light Range value to set.

Return Value

  • 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

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

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

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

Return Value

  • 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

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

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

  • [in] default_light: New Default Light value to set.

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

Return Value

  • 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

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

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

  • [in] default_light: New Default Light value to set.

Return Value

  • 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

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

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

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

Return Value

  • 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.

Parameters

  • [in] cli: Client that received the status message.

  • [in] ctx: Context of the message.

  • [in] status: 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.

Parameters

  • [in] cli: Client that received the status message.

  • [in] ctx: Context of the message.

  • [in] default_light: 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.

Parameters

  • [in] cli: Client that received the status message.

  • [in] ctx: Context of the message.

  • [in] status: 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.

Parameters

  • [in] cli: Client that received the status message.

  • [in] ctx: Context of the message.

  • [in] last: 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_model_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