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.

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.