Skip to main content

Schedules

A Schedule is a time-based rule — "set the light to 20% at 22:00 on weekdays" — that runs on the Node itself. ESP RainMaker Neo stores the Schedule set in the cloud so it survives app reinstalls and is visible to everyone with access to the Node, but the Node is what watches the clock and fires the action.

That split is the whole point of the feature, and it is worth stating plainly:

Schedules run on the Node against its own clock; Automations are evaluated in the cloud. A Schedule keeps firing while the Node is offline; an Automation cannot run at all unless the cloud is reachable.

What the user sees​

A Schedules screen per Node, listing each Schedule with a name and an enable toggle. Each Schedule carries one or more time triggers and one action — a set of Parameter values applied when it fires.

Three kinds of trigger are supported, distinguished by which fields are present rather than by a type field:

  • One-shot — fire once, a number of seconds from now (rsec).
  • Clock time on chosen days or dates — minutes past midnight plus a day or date mask (m with d or dd).
  • Solar — sunrise or sunset at a given latitude and longitude (lat/lon with sr/ss).

A Schedule may also carry a validity window with start and end Unix timestamps, outside which it never fires.

Editing is whole-set: the client sends the complete Schedule set and it replaces what was stored. There is no add-one or delete-one operation, on the API or on the wire. Deleting clears every Schedule on the Node at once.

Anyone who can reach the Node through its Group — or through a Subgroup they have access to — can read, replace and delete its Schedules. There is no read-only tier here, so a user who can merely see a Node can also change when it turns on.

What the firmware must do​

Schedules are built in. esp_rmaker_node_init() starts the service and esp_rmaker_start() fetches the Schedule set from the cloud — there is no enable call and no Kconfig option to switch the feature on.

  • Enable time sync (enable_time_sync in the SDK config) and the timezone service. Schedules are armed only after the first successful clock sync; before that they are held, and they are re-armed when the timezone changes.
  • Handle being called by a Schedule. When one fires, the SDK invokes your ordinary write callback with the request source set to ESP_RMAKER_REQ_SRC_SCHEDULE. Most products need no special case; suppress chimes and other change announcements if yours does.
  • Set CONFIG_RMAKER_SCHEDULING_MAX_SCHEDULES to the number your product actually offers, and budget NVS for it.

See Schedules and automations for the callback and Time and timezone for clock setup.

What the operator must do​

Nothing per deployment. Schedules are part of the base platform: the set is stored on the Node's row in the Nodes table alongside a version marker, and the API is live as soon as the deployment is up. There is no cloud-side scheduler to size, monitor or scale.

Two things are worth knowing when supporting users:

  • Every write bumps a version marker that travels down to the Node with the data. A Node that missed a push notices the stale copy on reconnect and re-syncs.
  • The cloud does not validate Schedule contents. It stores and forwards whatever well-formed JSON the client sends, so a malformed action is rejected by the Node, not by the API.
The Node's clock is the only clock

A Node fires Schedules against its own synchronised clock and configured timezone, not the phone's. A Node that has never reached an NTP server has no clock and holds every Schedule until it gets one.

Limits and caveats​

Maximum Schedules per Node — CONFIG_RMAKER_SCHEDULING_MAX_SCHEDULES, default 10, settable from 1 to 50. The reported JSON grows with the count.

Schedule ID — mandatory, a string of 16 characters or fewer. The Node derives a fixed-length NVS key from it and rejects a Schedule whose ID is missing, empty, not a string, or oversized.

Schedule name — stored by the cloud for display only; the Node ignores it.

No partial edits — a write replaces the whole set, so a client that sends a short list silently drops the Schedules it left out.

No cloud fallback — if the Node's clock is wrong the Schedule fires at the wrong time, and nothing in the cloud double-checks or re-fires it.

Missed-fire behaviour unconfirmed

Whether a Node catches up or drops a Schedule whose fire time passed while it was powered off, and how a one-shot trigger behaves across a reboot, is not stated in the Schedule specification. If your product depends on this, test the behaviour on your firmware version.