Light Lightness Control Client

The Light Lightness Control (LC) Client configures and interacts with the Light Lightness Control Server.

The Light LC Client creates a single model instance in the mesh composition data. The client can send messages to both the Light LC Server and the Light LC Setup Server, as long as it has the right application keys.

API documentation

Header file: include/bluetooth/mesh/light_ctrl_cli.h
Source file: subsys/bluetooth/mesh/light_ctrl_cli.c
group bt_mesh_light_ctrl_cli

Light Lightness Control Client model API.

Defines

BT_MESH_LIGHT_CTRL_CLI_INIT(_handlers)

Initialization parameters for the Light Lightness Control Client.

See

bt_mesh_light_ctrl_cli_handlers

Parameters

  • [in] _handlers: Optional message handler structure.

BT_MESH_MODEL_LIGHT_CTRL_CLI(_cli)

Light Lightness Control Client model composition data entry.

Parameters

Functions

int bt_mesh_light_ctrl_cli_mode_get(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool *rsp)

Get a Light Lightness Control Server’s current Mode.

The Mode determines whether the Server is actively controlling its Lightness Server’s state.

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_light_ctrl_cli_handlers::mode callback.

Parameters

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

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

  • [out] rsp: Response status buffer, returning the Server’s current mode, 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_light_ctrl_cli_mode_set(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool enabled, bool *rsp)

Set a Light Lightness Control Server’s current Mode.

The Mode determines whether the Server is actively controlling its Lightness Server’s state.

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_light_ctrl_cli_handlers::mode callback.

Parameters

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

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

  • [in] enabled: The new Mode to set.

  • [out] rsp: Response status buffer, returning the Server’s current mode, 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_light_ctrl_cli_mode_set_unack(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool enabled)

Set a Light Lightness Control Server’s current Mode without requesting a response.

The Mode determines whether the Server is actively controlling its Lightness Server’s state.

Parameters

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

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

  • [in] enabled: The new Mode 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_light_ctrl_cli_occupancy_enabled_get(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool *rsp)

Get a Light Lightness Control Server’s current Occupancy Mode.

The Occupancy Mode determines whether the Server accepts messages from Occupancy Servers.

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_light_ctrl_cli_handlers::occupancy_mode callback.

Parameters

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

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

  • [out] rsp: Response status buffer, returning whether the Server’s occupancy mode is currently enabled, 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_light_ctrl_cli_occupancy_enabled_set(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool enabled, bool *rsp)

Set a Light Lightness Control Server’s current Occupancy Mode.

The Occupancy Mode determines whether the Server accepts messages from Occupancy Servers.

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_light_ctrl_cli_handlers::occupancy_mode callback.

Parameters

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

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

  • [in] enabled: The new Occupancy Mode to set.

  • [out] rsp: Response status buffer, returning whether the Server’s occupancy mode is currently enabled, 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_light_ctrl_cli_occupancy_enabled_set_unack(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool enabled)

Set a Light Lightness Control Server’s current Occupancy Mode without requesting a response.

The Occupancy Mode determines whether the Server accepts messages from Occupancy Servers.

Parameters

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

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

  • [in] enabled: The new Occupancy Mode 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_light_ctrl_cli_light_onoff_get(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_onoff_status *rsp)

Get a Light Lightness Control Server’s current OnOff state.

The OnOff state determines whether the Server is currently keeping the light of its Lightness Server on.

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_light_ctrl_cli_handlers::light_onoff callback.

Parameters

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

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

  • [out] rsp: Response status buffer, returning the Server’s current OnOff state, 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_light_ctrl_cli_light_onoff_set(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_onoff_set *set, struct bt_mesh_onoff_status *rsp)

Tell a Light Lightness Control Server to turn the light on or off.

The OnOff state determines whether the Server is currently keeping the light of its Lightness Server on.

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_light_ctrl_cli_handlers::light_onoff callback.

Parameters

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

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

  • [in] set: Set parameters. The transition::time parameter may be set to override the Server’s default fade time, or transition may be set to NULL.

  • [out] rsp: Response status buffer, returning the Server’s current OnOff state, 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_light_ctrl_cli_light_onoff_set_unack(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_onoff_set *set)

Tell a Light Lightness Control Server to turn the light on or off without requesting a response.

The OnOff state determines whether the Server is currently keeping the light of its Lightness Server on.

Parameters

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

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

  • [in] set: Set parameters. The transition::time parameter may be set to override the Server’s default fade time, or transition may be set to NULL.

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_light_ctrl_cli_prop_get(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_prop id, struct sensor_value *rsp)

Get a Light Lightness Control Server property value.

Properties are the configuration parameters for the Light Lightness Control Server. Each property value is represented as a single sensor channel.

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_light_ctrl_cli_handlers::prop callback.

Parameters

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

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

  • [in] id: Light Lightness Control Server property to get.

  • [out] rsp: Property value 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_light_ctrl_cli_prop_set(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_prop id, const struct sensor_value *val, struct sensor_value *rsp)

Set a Light Lightness Control Server property value.

Properties are the configuration parameters for the Light Lightness Control Server. Each property value is represented as a single sensor channel.

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_light_ctrl_cli_handlers::prop callback.

Parameters

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

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

  • [in] id: Light Lightness Control Server property to set.

  • [in] val: New property value.

  • [out] rsp: Property value 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_light_ctrl_cli_prop_set_unack(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_prop id, const struct sensor_value *val)

Set a Light Lightness Control Server property value without requesting a response.

Properties are the configuration parameters for the Light Lightness Control Server. Each property value is represented as a single sensor channel.

Parameters

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

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

  • [in] id: Light Lightness Control Server property to set.

  • [in] val: New property value.

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_light_ctrl_cli_coeff_get(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_coeff id, float *rsp)

Get a Light Lightness Control Server Regulator Coefficient value.

Regulator coefficients are the configuration parameters for the Light Lightness Control Server Illuminance Regulator.

Parameters

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

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

  • [in] id: Light Lightness Control Server coefficient to get.

  • [in] rsp: Coefficient value 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_light_ctrl_cli_coeff_set(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_coeff id, float val, float *rsp)

Set a Light Lightness Control Server Regulator Coefficient value.

Regulator coefficients are the configuration parameters for the Light Lightness Control Server Illuminance Regulator.

Parameters

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

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

  • [in] id: Light Lightness Control Server coefficient to set.

  • [in] val: New coefficient value.

  • [in] rsp: Coefficient value 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_light_ctrl_cli_coeff_set_unack(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_coeff id, float val)

Set a Light Lightness Control Server Regulator Coefficient value without requesting a response.

Regulator coefficients are the configuration parameters for the Light Lightness Control Server Illuminance Regulator.

Parameters

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

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

  • [in] id: Light Lightness Control Server coefficient to set.

  • [in] val: New coefficient value.

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.

struct bt_mesh_light_ctrl_cli_handlers
#include <light_ctrl_cli.h>

Light Control Client handlers

Public Members

void (*mode)(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool enabled)

Light LC Mode status handler.

The Light Lightness Control Server will only control its Lightness Server when in enabled mode.

Parameters

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

  • [in] ctx: Context of the message.

  • [in] enabled: Whether the reporting server is enabled.

void (*occupancy_mode)(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, bool enabled)

Light LC Occupancy Mode status handler.

The Occupancy Mode state controls whether the Light Lightness Control accepts occupancy sensor messages for controlling it.

Parameters

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

  • [in] ctx: Context of the message.

  • [in] enabled: Whether the reporting server accepts occupancy sensor messages.

void (*light_onoff)(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_onoff_status *status)

Light LC OnOff status handler.

The Light OnOff state indicates whether the Light Lightness Control Server is enabled and has turned the Lightness Server on.

Parameters

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

  • [in] ctx: Context of the message.

  • [in] status: Current OnOff state of the reporting server. The remaining time indicates the remaining fading time.

void (*prop)(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_prop id, const struct sensor_value *value)

Light LC Property status handler.

The Light Lightness Control Server’s properties are configuration parameters for its behavior. All properties are represented as a single sensor value channel.

Parameters

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

  • [in] ctx: Context of the message.

  • [in] id: ID of the property.

  • [in] value: Value of the property.

void (*coeff)(struct bt_mesh_light_ctrl_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_light_ctrl_coeff id, float value)

Light LC Regulator Coefficient status handler.

The Light Lightness Control Server’s Regulator Coeffients control its Illuminance Regulator’s response.

Parameters

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

  • [in] ctx: Context of the message.

  • [in] id: ID of the property.

  • [in] value: Value of the property.

struct bt_mesh_light_ctrl_cli
#include <light_ctrl_cli.h>

Light Lightness Control Client instance.

Should be initialized with BT_MESH_LIGHT_CTRL_CLI_INIT.

Public Members

struct bt_mesh_model *model

Composition data model entry pointer.

struct bt_mesh_model_pub pub

Publication parameters.

struct bt_mesh_model_ack_ctx ack

Acknowledged message tracking.

const struct bt_mesh_light_ctrl_cli_handlers *handlers

Collection of handler callbacks.

uint8_t tid

Current transaction ID.