Global functions
Scheduling
schedule, unschedule, runDaily, runOnce, runIn, scheduleAtSunrise, scheduleAtSunset
Global functions available to smart-app code. Call them by bare name; there is no object to import.
| Function | Summary |
|---|---|
schedule | Run a handler on a cron schedule, evaluated in the home’s time zone. |
unschedule | Cancel scheduled work: every schedule and pending timer of this app, or only those bound to one handler. |
runDaily | Run a handler every day at a wall-clock time in the home’s time zone. |
runOnce | Run a handler once at an absolute instant. |
runIn | One-shot delayed handler. |
scheduleAtSunrise | Run a handler once at the next sunrise (plus an optional offset). |
scheduleAtSunset | Run a handler once at the next sunset (plus an optional offset). |
schedule
Run a handler on a cron schedule, evaluated in the home’s time zone. Persisted across reboots.
Signature
function schedule(cron: string, handler: unknown): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
cron | string | yes | — | Standard 5-field cron (minute hour day month weekday); a leading 6th field for seconds is also accepted. |
handler | unknown | yes | — | A top-level named function (or its name as a string). Handlers are dispatched by name, so arrow functions assigned to variables cannot be used. |
Returns
void
Notes
- The expression fires in the zone returned by
getHomeTimeZone(), not the process zone. UseformatDateParts(new Date(), getHomeTimeZone())inside the handler for any additional time logic.
Examples
schedule('0 22 * * 1-5', lockUp); // 22:00 on weekdays, home timeSee also
unschedule · runDaily · scheduling
unschedule
Cancel scheduled work: every schedule and pending timer of this app, or only those bound to one handler.
Signature
function unschedule(handler: unknown): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
handler | unknown | yes | — | undefined cancels everything this instance scheduled (cron jobs, runIn, runOnce, sunrise/sunset). A function or name cancels only that handler’s entries. |
Returns
void
Examples
unschedule(turnLightsOff); // motion resumed: drop the pending off-timerSee also
runDaily
Run a handler every day at a wall-clock time in the home’s time zone.
Signature
function runDaily(timeOfDay: string, handler: unknown): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
timeOfDay | string | yes | — | HH:MM, 24-hour. |
handler | unknown | yes | — | A top-level named function (or its name as a string). Handlers are dispatched by name, so arrow functions assigned to variables cannot be used. |
Returns
void
Examples
runDaily('07:30', openBlinds);See also
runOnce
Run a handler once at an absolute instant.
Signature
function runOnce(whenIsoOrDate: string | Date, handler: unknown): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
whenIsoOrDate | string | Date | yes | — | An ISO-8601 string. Although the type also allows a Date, the helper currently ignores anything that is not a string, so pass date.toISOString(). |
handler | unknown | yes | — | A top-level named function (or its name as a string). Handlers are dispatched by name, so arrow functions assigned to variables cannot be used. |
Returns
void — Silently does nothing when the instant is in the past or the string does not parse.
Notes
- Timers are persisted; a timer that comes due while the hub is down fires once on boot.
Examples
const at = new Date(Date.now() + 90 * 60 * 1000);
runOnce(at.toISOString(), reminder);See also
runIn
One-shot delayed handler. Replace-by-default: re-arming the same handler supersedes its pending runIn timer(s). Pass { overwrite: false } to stack concurrent timers (e.g. token-keyed duration waits).
Signature
function runIn(delaySeconds: number, handler: unknown, data?: Record<string, unknown>, options?: { overwrite?: boolean }): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
delaySeconds | number | yes | — | Delay before the handler fires, in seconds. |
handler | unknown | yes | — | A top-level named function (or its name as a string). Handlers are dispatched by name, so arrow functions assigned to variables cannot be used. |
data | Record<string, unknown> | no | {} | Passed to the handler as its argument. Must be JSON-serialisable; persisted with the timer. |
options | { overwrite?: boolean } | no | {} | Timer behaviour flags. |
options.overwrite | see signature | no | true | true (default) replaces any pending timer for the same handler; false stacks a new one alongside it. |
Returns
void
Notes
- Timers survive reboots and code updates; one that came due while the hub was off fires once on boot.
- The handler runs in a fresh isolate — nothing but
state,settingsanddatacarries over.
Examples
runIn(minutes * 60, turnLightsOff);runIn(300, releaseLock, { token: evt.entityId }, { overwrite: false });
function releaseLock(data) {
console.log('releasing', data.token);
}See also
unschedule · runOnce · scheduling
scheduleAtSunrise
Run a handler once at the next sunrise (plus an optional offset). One-shot: re-arm inside the handler or on systemStart for a daily effect.
Signature
function scheduleAtSunrise(handler: unknown, offsetMinutes?: number): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
handler | unknown | yes | — | A top-level named function (or its name as a string). Handlers are dispatched by name, so arrow functions assigned to variables cannot be used. |
offsetMinutes | number | no | 0 | Minutes after sunrise; negative means before. If the offset time for today has passed, the next day’s sunrise is used. |
Returns
void
Notes
- Needs the hub’s location (monitoring address). Check
getSunTimes().availableif you must handle hubs without one.
Examples
function onSunrise() {
$g.porch.turnOff();
scheduleAtSunrise(onSunrise); // re-arm for tomorrow
}
scheduleAtSunrise(onSunrise, -15);See also
scheduleAtSunset · getSunTimes
scheduleAtSunset
Run a handler once at the next sunset (plus an optional offset). One-shot: re-arm inside the handler or on systemStart for a daily effect.
Signature
function scheduleAtSunset(handler: unknown, offsetMinutes?: number): voidParameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
handler | unknown | yes | — | A top-level named function (or its name as a string). Handlers are dispatched by name, so arrow functions assigned to variables cannot be used. |
offsetMinutes | number | no | 0 | Minutes after sunset; negative means before. |
Returns
void
Examples
scheduleAtSunset(onSunset, 30); // half an hour after sunset