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.

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

  • [in] cli: Scene client model.

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

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

Return Value

  • 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

  • [in] cli: Scene client model.

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

  • [out] rsp: 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 Value

  • 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

  • [in] cli: Scene client model.

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

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

  • [out] rsp: 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 Value

  • 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

  • [in] cli: Scene client model.

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

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

Return Value

  • 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

  • [in] cli: Scene client model.

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

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

  • [out] rsp: 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 Value

  • 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

  • [in] cli: Scene client model.

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

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

Return Value

  • 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

  • [in] cli: Scene client model.

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

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

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

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

Return Value

  • 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

  • [in] cli: Scene client model.

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

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

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

Return Value

  • 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_state
#include <scene_cli.h>

Scene state

Public Members

enum bt_mesh_scene_status status

Status of the previous operation.

uint16_t current

Current scene, or BT_MESH_SCENE_NONE if no scene is active.

uint16_t target

Target scene, or BT_MESH_SCENE_NONE if no transition is in progress.

uint32_t remaining_time

Remaining time of the scene transition in milliseconds.

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.

Parameters

  • [in] cli: Scene client model.

  • [in] ctx: Message context parameters.

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

Parameters

  • [in] cli: Scene client model.

  • [in] ctx: Message context parameters.

  • [in] reg: Received scene register.