Light Lightness Control Client

Note

This model interacts with the new sensor API introduced as of nRF Connect SDK v2.6.0. As a consequence, parts of the model API have been changed as well. The old API is deprecated, but still available by enabling the Kconfig option CONFIG_BT_MESH_SENSOR_USE_LEGACY_SENSOR_VALUE. The Kconfig option is enabled by default in the deprecation period. See the documentation for nRF Connect SDK versions prior to v2.6.0 for documentation about the old sensor API.

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, and it can send messages to both the Light LC Server and the Light LC 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 LC Client model instantiated on a device.

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

mesh models ctrl instance get-all

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

mesh models ctrl instance set <ElemIdx>

Select the Light LC 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.

  • ElemIdx - Element index where the model instance is found.

mesh models ctrl mode-get

Get the Light Lightness Control Server’s current Mode.

mesh models ctrl mode-set <Enable(off, on)>

Set the Light Lightness Control Server’s current Mode and wait for a response.

  • Enable - Mode to set.

mesh models ctrl mode-set-unack <Enable(off, on)>

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

  • Enable - Mode to set.

mesh models ctrl occupancy-get

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

mesh models ctrl occupancy-set <Enable(off, on)>

Set the Light Lightness Control Server’s current Occupancy Mode and wait for a response.

  • Enable - Occupancy Mode to set.

mesh models ctrl occupancy-set-unack <Enable(off, on)>

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

  • Enable - Occupancy Mode to set.

mesh models ctrl light-onoff-get

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

mesh models ctrl light-onoff-set <OnOff> [TransTime(ms) [Delay(ms)]]

Tell the Light Lightness Control Server to turn the light on or off, and wait for a response.

  • OnOff - OnOff state value to set. Use on, enable, or any non-zero value to enable the state.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models ctrl light-onoff-set-unack <OnOff> [TransTime(ms) [Delay(ms)]]

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

  • OnOff - OnOff state value to set. Use on, enable, or any non-zero value to enable the state.

  • TransTime - If present, defines the transition time in the message in milliseconds.

  • Delay - If present, defines the delay in the message in milliseconds.

mesh models ctrl prop-get <ID>

Get a property value of the Light Lightness Control Server.

mesh models ctrl prop-set <ID> <Val>

Set a property value of the Light Lightness Control Server and wait for a response.

  • ID - ID of the property to set. See bt_mesh_light_ctrl_prop for a list of supported properties.

  • Val - The new value of the property.

mesh models ctrl prop-set-unack <ID> <Val>

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

  • ID - ID of the property to set. See bt_mesh_light_ctrl_prop for a list of supported properties.

  • Val - The new value of the property.

mesh models ctrl coeff-get <ID>

Get a Regulator Coefficient value of the Light Lightness Control Server.

mesh models ctrl coeff-set <ID> <Val>

Set a Regulator Coefficient value of the Light Lightness Control Server and wait for a response.

  • ID - ID of the coefficient to set. See bt_mesh_light_ctrl_coeff for a list of supported coefficients.

  • Val - New coefficient value.

mesh models ctrl coeff-set-unack <ID> <Val>

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

  • ID - ID of the coefficient to set. See bt_mesh_light_ctrl_coeff for a list of supported coefficients.

  • Val - New coefficient value.

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 also

bt_mesh_light_ctrl_cli_handlers

Parameters:

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

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

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

  • rsp – [out] Response status buffer, returning the Server’s current mode, 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_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:

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

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

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

  • rsp – [out] Response status buffer, returning the Server’s current mode, 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_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:

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

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

  • enabled – [in] The new Mode 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_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:

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

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

  • rsp – [out] Response status buffer, returning whether the Server’s occupancy mode is currently enabled, 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_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:

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

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

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

  • rsp – [out] Response status buffer, returning whether the Server’s occupancy mode is currently enabled, 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_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:

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

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

  • enabled – [in] The new Occupancy Mode 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_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:

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

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

  • rsp – [out] Response status buffer, returning the Server’s current OnOff state, 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_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:

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

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

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

  • rsp – [out] Response status buffer, returning the Server’s current OnOff state, 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_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:

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

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

  • set – [in] 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 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_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 bt_mesh_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:

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

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

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

  • rsp – [out] Property value 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_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 bt_mesh_sensor_value *val, struct bt_mesh_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:

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

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

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

  • val – [in] New property value.

  • rsp – [out] Property value 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_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 bt_mesh_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:

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

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

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

  • val – [in] New property value.

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_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:

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

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

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

  • rsp – [in] Coefficient value 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_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:

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

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

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

  • val – [in] New coefficient value.

  • rsp – [in] Coefficient value 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_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:

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

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

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

  • val – [in] New coefficient value.

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

Param cli:

[in] Client that received the status message.

Param ctx:

[in] Context of the message.

Param enabled:

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

Param cli:

[in] Client that received the message.

Param ctx:

[in] Context of the message.

Param enabled:

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

Param cli:

[in] Client that received the message.

Param ctx:

[in] Context of the message.

Param status:

[in] 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 bt_mesh_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 channel.

Param cli:

[in] Client that received the message.

Param ctx:

[in] Context of the message.

Param id:

[in] ID of the property.

Param value:

[in] 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 Coefficients control its Illuminance Regulator’s response.

Param cli:

[in] Client that received the message.

Param ctx:

[in] Context of the message.

Param id:

[in] ID of the property.

Param value:

[in] 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

const struct bt_mesh_model *model

Composition data model entry pointer.

struct bt_mesh_model_pub pub

Publication parameters.

struct bt_mesh_msg_ack_ctx ack_ctx

Acknowledged message tracking.

const struct bt_mesh_light_ctrl_cli_handlers *handlers

Collection of handler callbacks.

uint8_t tid

Current transaction ID.