Light CTL Client

The Color-Tunable Light (CTL) Client model remotely controls the state of the Light CTL Server model, and the Light CTL Temperature Server model.

Unlike the server models, the Light CTL Client only creates a single model instance in the mesh composition data. The Light CTL Client can send messages to the Light CTL Server, the Light CTL Setup Server and the Light CTL Temperature Server, as long as it has the right application keys.

Note

By specification, the Light CTL Temperature Server must be located in another element than the Light CTL Server models. The user must ensure that the publish parameters of the client instance point to the correct element address when using the function calls in the client API.

Extended models

None.

Persistent storage

None.

Shell commands

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

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

mdl_ctl instance get-all

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

mdl_ctl instance set <elem_idx>

Select the Light CTL 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_ctl get

Get the current Light CTL state value.

mdl_ctl set <light> <temp> <delta> [transition_time_ms [delay_ms]]

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

  • light - Light level to set.

  • temp - Light temperature value to set.

  • delta - Delta UV 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_ctl set-unack <light> <temp> <delta> [transition_time_ms [delay_ms]]

Set the Light CTL state value without waiting for a response.

  • light - Light level value to set.

  • temp - Light temperature value to set.

  • delta - Delta UV 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_ctl temp-get

Get the current Light CTL Temperature state value.

mdl_ctl temp-set <light> <temp> <delta> [transition_time_ms [delay_ms]]

Set the Light CTL Temperature state value and wait for a response.

  • temp - Light temperature value to set.

  • delta - Delta UV 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_ctl temp-set-unack <light> <temp> <delta> [transition_time_ms [delay_ms]]

Set the Light CTL Temperature state value.

  • temp - Light temperature value to set.

  • delta - Delta UV 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_ctl default-get

Get the current Light CTL Default state value.

mdl_ctl default-set <light> <temp> <delta>

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

  • light - Light level value to set.

  • temp - Light temperature value to set.

  • delta - Delta UV value to set.

mdl_ctl default-set-unack <light> <temp> <delta>

Set the default CTL value of the server without requesting a response.

  • light - Light level value to set.

  • temp - Light temperature value to set.

  • delta - Delta UV value to set.

mdl_ctl temp-range-get

Get the current Light CTL Temperature Range state value.

mdl_ctl temp-range-set <min> <max>

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

  • min - Minimum allowed light temperature value.

  • max - Maximum allowed light temperature value.

mdl_ctl temp-range-set-unack <min> <max>

Set the Light CTL Temperature Range state value.

  • min - Minimum allowed light temperature value.

  • max - Maximum allowed light temperature value.

API documentation

Header file: include/bluetooth/mesh/light_ctl_cli.h
Source file: subsys/bluetooth/mesh/light_ctl_cli.c
group bt_mesh_light_ctl_cli

API for the Light CTL Client model.

Defines

BT_MESH_LIGHT_CTL_CLI_INIT(_handlers)

Initialization parameters for a Light CTL Client model instance.

BT_MESH_MODEL_LIGHT_CTL_CLI(_cli)

Light CTL Client model composition data entry.

Parameters

Functions

int bt_mesh_light_ctl_get(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_ctl_status *rsp)

Get the Light CTL state of the bound server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

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_light_ctl_set(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl_set *set, struct bt_mesh_light_ctl_status *rsp)

Set the CTL state of the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

Parameters

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

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

  • set – [in] CTL state 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_light_ctl_set_unack(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl_set *set)

Set the CTL state 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] CTL state 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_temp_get(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_temp_status *rsp)

Get the Light CTL Temperature state of the bound server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

Note

In order to use this call, the user must ensure that the client instance is set to publish messages to the Light Temperature associated with the target Light CTL server. This server will be located in another element than the Light CTL server.

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_light_temp_set(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_set *set, struct bt_mesh_light_temp_status *rsp)

Set the CTL Temperature state of the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

Note

In order to use this call, the user must ensure that the client instance is set to publish messages to the Light Temperature associated with the target Light CTL server. This server will be located in another element than the Light CTL server.

Parameters

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

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

  • set – [in] CTL Temperature state 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_light_temp_set_unack(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_set *set)

Set the CTL Temperature state of the server without requesting a response.

Note

In order to use this call, the user must ensure that the client instance is set to publish messages to the Light Temperature associated with the target Light CTL server. This server will be located in another element than the Light CTL server.

Parameters

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

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

  • set – [in] CTL Temperature state 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_ctl_default_get(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_ctl *rsp)

Get the default CTL value of the bound server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

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_light_ctl_default_set(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl *set, struct bt_mesh_light_ctl *rsp)

Set the default CTL value of the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

Parameters

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

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

  • set – [in] Default CTL 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_light_ctl_default_set_unack(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl *set)

Set the default CTL value 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] Default CTL 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_light_temp_range_get(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_temp_range_status *rsp)

Get the Light CTL Range state of the bound server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

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_light_temp_range_set(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_range *set, struct bt_mesh_light_temp_range_status *rsp)

Set the CTL Range of the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return.

Parameters

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

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

  • set – [in] Range 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_light_temp_range_set_unack(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_range *set)

Set the CTL Range 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] Range state 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.

struct bt_mesh_light_ctl_cli_handlers
#include <light_ctl_cli.h>

Light CTL Client state access handlers.

Public Members

void (*const ctl_status)(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl_status *status)

CTL status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] CTL status contained in the message.

void (*const temp_status)(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_status *status)

CTL Temperature status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] CTL Temperature status contained in the message.

void (*const default_status)(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_ctl *status)

Default parameter status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Default CTL value of the server.

void (*const temp_range_status)(struct bt_mesh_light_ctl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_temp_range_status *status)

CTL Range status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] CTL Range state of the server.

struct bt_mesh_light_ctl_cli
#include <light_ctl_cli.h>

Light CTL Client instance. Should be initialized with BT_MESH_LIGHT_CTL_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_light_ctl_cli_handlers *handlers

Handler function structure.