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.
API documentation¶
include/bluetooth/mesh/scene_cli.h
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
_cli – [in] Pointer to a Scene Client model instance.
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.
- Returns 0
Successfully got the scene state.
- Returns -EALREADY
A blocking request is already in progress.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -EAGAIN
The device has not been provisioned.
- Returns -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 mostrsp.count
number of scenes, andrsp.count
will be changed to reflect the number of retrieved scenes.
- Returns 0
Successfully got the scene register.
- Returns -EALREADY
A blocking request is already in progress.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -EAGAIN
The device has not been provisioned.
- Returns -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 mostrsp.count
number of scenes, andrsp.count
will be changed to reflect the number of retrieved scenes.
- Returns 0
Successfully sent the store message and processed the response.
- Returns -EINVAL
Invalid scene number.
- Returns -EALREADY
A blocking request is already in progress.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -EAGAIN
The device has not been provisioned.
- Returns -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.
- Returns 0
Successfully sent the store message.
- Returns -EINVAL
Invalid scene number.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -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 mostrsp.count
number of scenes, andrsp.count
will be changed to reflect the number of retrieved scenes.
- Returns 0
Successfully sent the delete message and processed the response.
- Returns -EINVAL
Invalid scene number.
- Returns -EALREADY
A blocking request is already in progress.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -EAGAIN
The device has not been provisioned.
- Returns -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.
- Returns 0
Successfully sent the delete message.
- Returns -EINVAL
Invalid scene number.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -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.
- Returns 0
Successfully sent the recall message and processed the response.
- Returns -EINVAL
Invalid scene number or transition parameters.
- Returns -EALREADY
A blocking request is already in progress.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -EAGAIN
The device has not been provisioned.
- Returns -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.
- Returns 0
Successfully sent the recall message.
- Returns -EINVAL
Invalid scene number or transition parameters.
- Returns -EADDRNOTAVAIL
A message context was not provided and publishing is not configured.
- Returns -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.
-
enum bt_mesh_scene_status
-
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.
-
enum bt_mesh_scene_status
-
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
cli – [in] Scene client model.
ctx – [in] Message context parameters.
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.
- Parameters
cli – [in] Scene client model.
ctx – [in] Message context parameters.
reg – [in] Received scene register.
-
void (*
-