Light HSL Client

The Light HSL Client model remotely controls the state of the Light HSL Server, Light Hue Server and Light Saturation Server models.

Unlike the Light HSL Server model, the Client only creates a single model instance in the mesh composition data.

Extended models

None.

Persistent storage

None.

Shell commands

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

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

mdl_hsl instance get-all

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

mdl_hsl instance set <elem_idx>

Select the Light HSL 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_hsl get

Get the Light HSL state value of the bound server.

mdl_hsl set <light> <hue> <saturation> [transition_time_ms [delay_ms]]

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

  • light - Lightness level to set.

  • hue - Hue level to set.

  • saturation - Saturation level 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_hsl set-unack <light> <hue> <saturation> [transition_time_ms [delay_ms]]

Set the Light HSL state value without requesting for a response.

  • light - Lightness level to set.

  • hue - Hue level to set.

  • saturation - Saturation level 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_hsl target-get

Get the Light HSL target state value of the bound server.

mdl_hsl default-get

Get the default HSL value of the bound server.

mdl_hsl default-set <light> <hue> <saturation>

Set the default HSL value of the server and wait for a response.

  • light - Default lightness level to set.

  • hue - Default hue level to set.

  • saturation - Default saturation level to set.

mdl_hsl default-set-unack <light> <hue> <saturation>

Set the Default Light state value of the server without requesting a response.

  • light - Default lightness level to set.

  • hue - Default hue level to set.

  • saturation - Default saturation level to set.

mdl_hsl range-get

Get the Light HSL Range state value of the bound server.

mdl_hsl range-set <hue_min> <hue_max> <sat_min> <sat_max>

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

  • hue_min - Minimum allowed hue value.

  • hue_max - Maximum allowed hue value.

  • sat_min - Minimum allowed saturation value.

  • sat_max - Maximum allowed saturation value.

mdl_hsl range-set-unack <hue_min> <hue_max> <sat_min> <sat_max>

Set the Light HSL Range state value without requesting a response.

  • hue_min - Minimum allowed hue value.

  • hue_max - Maximum allowed hue value.

  • sat_min - Minimum allowed saturation value.

  • sat_max - Maximum allowed saturation value.

mdl_hsl hue-get

Get the Light Hue state value of the bound server.

mdl_hsl hue-set <lvl> [transition_time_ms [delay_ms]]

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

  • lvl - Hue level 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_hsl hue-set-unack <lvl> [transition_time_ms [delay_ms]]

Set the Light Hue state value without requesting a response.

  • lvl - Hue level 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_hsl saturation-get

Get the Light Saturation state value of the bound server.

mdl_hsl saturation-set <lvl> [transition_time_ms [delay_ms]]

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

  • lvl - Saturation level 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_hsl saturation-set-unack <lvl> [transition_time_ms [delay_ms]]

Set the Light Saturation state value without requesting a response.

  • lvl - Saturation level 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.

API documentation

Header file: include/bluetooth/mesh/light_hsl_cli.h
Source file: subsys/bluetooth/mesh/light_hsl_cli.c
group bt_mesh_light_hsl_cli

API for the Light HSL Client model.

Defines

BT_MESH_MODEL_LIGHT_HSL_CLI(_cli)

Light HSL Client model composition data entry.

Parameters

Functions

int bt_mesh_light_hsl_get(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hsl_status *rsp)

Get the Light HSL 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 – [in] 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_hsl_set(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_params *set, struct bt_mesh_light_hsl_status *rsp)

Set the Light HSL 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] HSL state to set.

  • rsp – [in] 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_hsl_set_unack(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_params *set)

Set the Light HSL 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] HSL 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_hsl_target_get(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hsl_status *rsp)

Get the Light HSL target 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 – [in] 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_hsl_default_get(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hsl *rsp)

Get the default HSL 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 – [in] 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_hsl_default_set(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl *set, struct bt_mesh_light_hsl *rsp)

Set the default HSL 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 HSL value to set.

  • rsp – [in] 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_hsl_default_set_unack(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl *set)

Set the default HSL 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 HSL 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_hsl_range_get(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hsl_range_status *rsp)

Get the Light HSL 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 – [in] 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_hsl_range_set(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_sat_range *set, struct bt_mesh_light_hsl_range_status *rsp)

Set the Light HSL 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 – [in] 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_hsl_range_set_unack(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_sat_range *set)

Set the Light HSL 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.

int bt_mesh_light_hue_get(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_hue_status *rsp)

Get the Light Hue 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 – [in] 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_hue_set(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue *set, struct bt_mesh_light_hue_status *rsp)

Set the Light Hue 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] Light Hue state to set.

  • rsp – [in] 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_hue_set_unack(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue *set)

Set the Light Hue 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] Light Hue 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_saturation_get(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_light_sat_status *rsp)

Get the Light Saturation 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 – [in] 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_saturation_set(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_sat *set, struct bt_mesh_light_sat_status *rsp)

Set the Light Saturation 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] Light Saturation state to set.

  • rsp – [in] 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_saturation_set_unack(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_sat *set)

Set the Light Saturation 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] Light Saturation 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_hsl_cli_handlers
#include <light_hsl_cli.h>

Light HSL Client state access handlers.

Public Members

void (*const status)(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_status *status)

HSL status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] HSL status contained in the message.

void (*const target_status)(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_status *status)

HSL target status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] HSL target status contained in the message.

void (*const default_status)(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl *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 HSL value of the server.

void (*const range_status)(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hsl_range_status *status)

Range status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] HSL Range state of the server.

void (*const hue_status)(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_hue_status *status)

Hue status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Hue status contained in the message.

void (*const saturation_status)(struct bt_mesh_light_hsl_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_light_sat_status *status)

Saturation status message handler.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the message.

Param status

[in] Saturation status contained in the message.

struct bt_mesh_light_hsl_cli
#include <light_hsl_cli.h>

Light HSL Client instance.

Public Members

const struct bt_mesh_light_hsl_cli_handlers *handlers

Handler function structure.

struct bt_mesh_model *model

Model entry.

struct bt_mesh_model_pub pub

Publish parameters.

struct net_buf_simple buf

Publication buffer

uint8_t pub_data[BT_MESH_MODEL_BUF_LEN(BT_MESH_LIGHT_HSL_OP_SET, BT_MESH_LIGHT_HSL_MSG_MAXLEN_SET)]

Publication buffer data

struct bt_mesh_msg_ack_ctx ack_ctx

Acknowledged message tracking.

uint8_t tid

Current transaction ID.