Scene Client

The Scene Client model remotely controls the state of a Scene Server model.

Unlike the Scene Server model, the Scene Client only creates a single model instance in the mesh composition data. The Scene Client can send messages to both the Scene Server and the Scene 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 Scene Client model instantiated on a device.

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

mesh models scene instance get-all

Print all instances of the Scene Client model on the device.

mesh models scene instance set <elem_idx>

Select the Scene 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.

mesh models scene get

Get the current state of the Scene Server.

mesh models scene register-get

Get the full scene register of the Scene Server.

mesh models scene store <scene>

Store the current state as a scene and wait for a response.

  • store - Scene number to store.

mesh models scene store-unack <scene>

Store the current state as a scene without requesting a response.

  • store - Scene number to store.

mesh models scene delete <scene>

Delete the given scene and wait for a response.

  • store - Scene number to delete.

mesh models scene delete-unack <scene>

Delete the given scene without requesting a response.

  • scene - Scene number to delete.

mesh models scene recall <scene> [transition_time_ms [delay_ms]]

Recall the given scene and wait for a response.

  • scene - Scene number to recall.

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

mesh models scene recall-unack <scene> [transition_time_ms [delay_ms]]

Recall the given scene without requesting a response.

  • scene - Scene number to recall.

  • 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/scene_cli.h
Source file: subsys/bluetooth/mesh/scene_cli.c
group bt_mesh_scene_cli

API for the Scene Client model.

Defines

BT_MESH_MODEL_SCENE_CLI(_cli)

Scene Client model composition data entry.

Parameters

Functions

int bt_mesh_scene_cli_get(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_scene_state *rsp)

Get the current state of a Scene Server.

This call is blocking if the rsp buffer is non-NULL. The response will always be passed to the bt_mesh_scene_cli::status callback.

Parameters

  • cli – [in] Scene client model.

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

  • rsp – [out] Response buffer, or NULL to keep from blocking.

Return values

  • 0 – Successfully got the scene state.

  • -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_scene_cli_register_get(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_scene_register *rsp)

Get the full scene register of a Scene Server.

This call is blocking if the rsp buffer is non-NULL. The response will always be passed to the bt_mesh_scene_cli::scene_register callback.

Parameters

  • cli – [in] Scene client model.

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

  • rsp – [out] Response buffer, or NULL to keep from blocking. If the rsp.scenes parameter points to a valid buffer, it will be filled with at most rsp.count number of scenes, and rsp.count will be changed to reflect the number of retrieved scenes.

Return values

  • 0 – Successfully got the scene register.

  • -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_scene_cli_store(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t scene, struct bt_mesh_scene_register *rsp)

Store the current state as a scene.

This call is blocking if the rsp buffer is non-NULL. The response will always be passed to the bt_mesh_scene_cli::scene_register callback.

Parameters

  • cli – [in] Scene client model.

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

  • scene – [in] Scene number to store. Cannot be BT_MESH_SCENE_NONE.

  • rsp – [out] Response buffer, or NULL to keep from blocking. If the rsp.scenes parameter points to a valid buffer, it will be filled with at most rsp.count number of scenes, and rsp.count will be changed to reflect the number of retrieved scenes.

Return values

  • 0 – Successfully sent the store message and processed the response.

  • -EINVAL – Invalid scene number.

  • -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_scene_cli_store_unack(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t scene)

Store the current state as a scene without requesting a response.

Parameters

  • cli – [in] Scene client model.

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

  • scene – [in] Scene number to store. Cannot be BT_MESH_SCENE_NONE.

Return values

  • 0 – Successfully sent the store message.

  • -EINVAL – Invalid scene number.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_scene_cli_delete(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t scene, struct bt_mesh_scene_register *rsp)

Delete the given scene.

This call is blocking if the rsp buffer is non-NULL. The response will always be passed to the bt_mesh_scene_cli::scene_register callback.

Parameters

  • cli – [in] Scene client model.

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

  • scene – [in] Scene to delete. Cannot be BT_MESH_SCENE_NONE.

  • rsp – [out] Response buffer, or NULL to keep from blocking. If the rsp.scenes parameter points to a valid buffer, it will be filled with at most rsp.count number of scenes, and rsp.count will be changed to reflect the number of retrieved scenes.

Return values

  • 0 – Successfully sent the delete message and processed the response.

  • -EINVAL – Invalid scene number.

  • -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_scene_cli_delete_unack(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t scene)

Delete the given scene without requesting a response.

Parameters

  • cli – [in] Scene client model.

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

  • scene – [in] Scene to delete. Cannot be BT_MESH_SCENE_NONE.

Return values

  • 0 – Successfully sent the delete message.

  • -EINVAL – Invalid scene number.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_scene_cli_recall(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t scene, const struct bt_mesh_model_transition *transition, struct bt_mesh_scene_state *rsp)

Recall the given scene.

All models that participate in the scene will transition to the stored scene state with the given transition parameters.

This call is blocking if the rsp buffer is non-NULL. The response will always be passed to the bt_mesh_scene_cli::status callback.

Parameters

  • cli – [in] Scene client model.

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

  • scene – [in] Scene to recall. Cannot be BT_MESH_SCENE_NONE.

  • transition – [in] Parameters for the scene transition, or NULL to use the target’s default parameters.

  • rsp – [out] Response buffer, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the recall message and processed the response.

  • -EINVAL – Invalid scene number or transition parameters.

  • -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_scene_cli_recall_unack(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, uint16_t scene, const struct bt_mesh_model_transition *transition)

Recall the given scene without requesting a response.

All models that participate in the scene will transition to the stored scene state with the given transition parameters.

Parameters

  • cli – [in] Scene client model.

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

  • scene – [in] Scene to recall. Cannot be BT_MESH_SCENE_NONE.

  • transition – [in] Parameters for the scene transition, or NULL to use the target’s default parameters.

Return values

  • 0 – Successfully sent the recall message.

  • -EINVAL – Invalid scene number or transition parameters.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_scene_register
#include <scene_cli.h>

Scene register parameters

Public Members

enum bt_mesh_scene_status status

Status of the previous operation.

uint16_t current

Current scene.

size_t count

Number of entries in the scenes list.

uint16_t *scenes

Optional list of scenes to populate.

struct bt_mesh_scene_cli
#include <scene_cli.h>

Scene client model instance.

Public Members

void (*status)(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_scene_state *state)

Status message callback.

Param cli

[in] Scene client model.

Param ctx

[in] Message context parameters.

Param state

[in] Received scene state.

void (*scene_register)(struct bt_mesh_scene_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_scene_register *reg)

Scene register message callback.

Param cli

[in] Scene client model.

Param ctx

[in] Message context parameters.

Param reg

[in] Received scene register.