Scheduler Server

The Scheduler Server model holds the current state of the Scheduler Register, and performs scheduling of the configured actions. The model notifies appropriate Scene Server and Generic OnOff Server instances about actions in progress.

The Scheduler Server relies on the Time Server that is provided during initialization. However, it is the application that should handle the Time Server events and notify the Scheduler Server if the UTC time or the Time Zone have changed.

The Scheduler Server model adds two model instances in the composition data:

  • Scheduler Server

  • Scheduler Setup Server

The two model instances share the states of the Scheduler Server, but accept different messages. This allows for a fine-grained control of the access rights for the Scheduler Server states, as the two model instances can be bound to different application keys.

  • Scheduler Server manages the scheduled actions.

  • Scheduler Setup Server provides functionality for configuration and recalling of actions in the Scheduler Server’s Scheduler Register state.

Operation

The Scheduler models perform conversion of the configuration parameters from incoming client messages into international atomic time (TAI). The configuration parameters with calculated time closest to the current time are scheduled as actions. If an action requires rescheduling when the scheduled time has expired, the Scheduler Server calculates new time and repeats the scheduling procedure. However, the Scheduler Server skips configuration parameters not allowing to calculate the exact time of the action. Such actions will never be executed.

When the scheduled action is executed, the Scheduler Server sends a notification about the action in progress to appropriate Scene or OnOff Server instances, starting with the same element on which the Scheduler Server is present. The Scene or OnOff Server instances are notified until the Scheduler Server reaches another element with a Scheduler Server instance, or there are just no elements left. The Scene or OnOff Servers publish their states if the states have changed.

The application should notify the Scheduler Server if the Time Zone or the UTC time has changed, using the Scheduler Server API:

The Scheduler Server will recalculate time for the actions.

States

Schedule Register: bt_mesh_schedule_entry

The Scheduler Server model offers a Schedule Register that contains up to sixteen registered action entries.

Each entry has the following fields:

Extended models

The Scheduler Server is implemented as a root model. When a Scheduler Server model is present on an element, the Scene Server model (see the Scene Server documentation) shall also be present on the same element.

Persistent storage

The Scheduler Server stores the following information:

  • Any changes to the Schedule Register state

This information is used to restore previously configured register entries when the device powers up.

The scheduler operation depends on the availability of the updated current time provided by the Time Server. It is the application’s responsibility to call bt_mesh_scheduler_srv_time_update() after the current local time has been updated to schedule available entries correctly.

API documentation

Header file: include/bluetooth/mesh/scheduler_srv.h
Source file: subsys/bluetooth/mesh/scheduler_srv.c
group bt_mesh_scheduler_srv

API for the Scheduler Server model.

Defines

BT_MESH_SCHEDULER_SRV_INIT(_action_set_cb, _time_srv)

Initialization parameters for Scheduler Server model.

Parameters

  • _action_set_cb – [in] Action Set callback.

  • _time_srv – [in] Timer server that is used for action scheduling.

BT_MESH_MODEL_SCHEDULER_SRV(_srv)

Scheduler Server model composition data entry.

Warning

If the Scheduler model is registered on the element then the Scene model shouldn’t. The Scheduler model includes already the Scene model.

Parameters

Functions

int bt_mesh_scheduler_srv_time_update(struct bt_mesh_scheduler_srv *srv)

Update time of the scheduled action.

Note

This API is required to update time if referenced time server updated Time Zone BT_MESH_TIME_SRV_ZONE_UPDATE or UTC BT_MESH_TIME_SRV_UTC_UPDATE.

Parameters

  • srv – [in] Scheduler server model.

Return values

  • 0 – Successfully updated time of the ongoing action.

  • -EINVAL – Invalid parameters.

struct bt_mesh_scheduler_srv
#include <scheduler_srv.h>

Scheduler Server model instance

Public Members

struct bt_mesh_scheduler_srv.[anonymous] [anonymous]

Model state related structure of the Scheduler Server instance.

struct bt_mesh_model *model

Composition data model pointer.

struct bt_mesh_model_pub pub

Publication state.

struct bt_mesh_time_srv *time_srv

Referenced time server to get time for scheduling.

struct bt_mesh_scene_srv scene_srv

Scene server instance that is extended by the Scheduler model.

void (*const action_set_cb)(struct bt_mesh_scheduler_srv *srv, struct bt_mesh_msg_ctx *ctx, uint8_t idx, struct bt_mesh_schedule_entry *entry)

Scheduler action set callback.

Called whenever the server receives an action set both ack or unack

Note

This handler is optional.

Param srv

[in] Scheduler server instance.

Param ctx

[in] Context information about received message.

Param idx

[in] Scheduler Register state index.

Param entry

[in] Scheduler Register state entry.