SCHEDULER

Scheduler

SCHEDULER module (source code⁽¹⁾)

Introduced in version 1.12.0

Original implementation by @faina09, ref. xoseperez/espurna#131⁽²⁾

Starting with version 1.16.0 uses generic 'time string' specification string instead of separate weekdays, hour and minute strings. Format is based on systemd calendar events spec⁽³⁾. Also, instead of module-bound actions, generic terminal command support⁽⁴⁾ was included.

Sunrise / sunset calculations based on Sunrise equation⁽⁵⁾. C++ code ported from Go implementation at nathan-osman/go-sunrise⁽⁶⁾ by @nathan-osman. Altitude calculation implementation based on nathan-osman/go-sunrise#11⁽⁷⁾ by @jrabasco

Module configuration

Configuration key	Build flag	Description
	SCHEDULER_SUPPORT	Build scheduler module, 1 by default (0 to disable)
	SCHEDULER_MAX_SCHEDULES	Maximum amount of schedules that will be stored on the device
schRstrDays	SCHEDULER_RESTORE_DAYS (applied to all schedules)	1 (today and yesterday, default). Number of days to look back for schRestore#. Set to 0 to only check 00:00..NOW. Disable schRestore# for individual schedules.
	SCHEDULER_SUN_SUPPORT	Build sunrise & sunset module, 0 by default (1 to disable). Use sunrise or sunset keywords in the time string
schLat	SCHEDULER_LATITUDE	Current latitude (float)
schLong	SCHEDULER_LONGITUDE	Current longitude (float)
schAlt	SCHEDULER_ALTITUDE	Current altitude aka elevation (float). Default is 0.0, adjust for more precise time calculation.

Schedule configuration

Configuration key	Build flag	Description
schType#		Type of the n-th schedule. One of: unknown, disabled or calendar. Note that unknown schedules cannot be saved in settings, and will be removed. Currently, only calendar type is used.
schTime#		Time specification at which the n-th schedule action should take place. See below for more information.
schAction#		Action to perform for n-th schedule. w/ TERMINAL_SUPPORT=1, uses terminal commands. When disabled, see below.
schRestore#	SCHEDULER_RESTORE (applied to all schedules)	0 (disabled, default) or 1 (enable) to attempt to trigger last missed schedule when device syncs time for the very first time.

Terminal

Command	Description
schedule	shows scheduler status global configuration options
schedule <ID>	shows n-th schedule configuration options

Time string

Examples

Time string	When action would be triggered
12:00	at tweelve o'clock
00:00 UTC	at midnight UTC
UTC	at midnight UTC
Sat,Sun 10:00	at ten o'clock on Saturday and Sunday
13,15..17:00	at thirteen, fifteen, sixteen and seventeen o'clock
01-01 06:00	at six o'clock on January 1st
05-W2 02:00	at 2 o'clock of every day on the 2nd week of May
12-L1,2 18:55	at eighteen fifty five on the second to last day and the last day of December
*-1/5 5:00	at five o'clock on days 1, 6, 11, 16, 21, 26 and 31
Mon,Thu..Sat 10,15,20:30	at ten thirty, fifteen thirty and twenty thirty on Mondays, Thursdays, Fridays and Saturdays

Base elements

Date

Expected format is YYYY-MM-DD or MM-DD, where

• YYYY is a year, a 4-digit number
• MM is a month, 1–12
• DD is a day, 1–31

Weekday(s)

Expected format is either full or abbreviated name in English (case insensitive), or its ISO numeric value.

Quoting ISO 8601⁽⁸⁾

D is the weekday number, from 1 through 7, beginning with Monday and ending with Sunday.

Name	Abbreviation	Number
Monday	Mon	1
Tuesday	Tue	2
Wednesday	Wed	3
Thursday	Thu	4
Friday	Fri	5
Saturday	Sat	6
Sunday	Sun	7

Time

Expected format is HH:MM (24-hour)

• HH is an hour, 0–23
• MM is a minute, 0–59

Keywords

Can be specified only once per string, generally right at the end. Case insensitive.

• UTC to use coordinated universal time⁽⁹⁾ instead of local time.

When SUNRISE_SUN_SUPPORT=1, additional keywords can be used in place of HH:MM

• SUNRISE to trigger schedule at the next sunrise.
• SUNSET to trigger schedule at the next sunset.

Time string	When action would be triggered
05-* SUNRISE	at sunrise during May
Monday SUNSET	at sunset, but only on Mondays

While the actual sunrise and sunset time includes seconds, it is rounded down to the nearest minute value.

When using restore feature, both are respected for previous dates

Additional format info

• At least one element must appear in the string
• YYYY-MM-DD can be omitted from the string, *-*-* is used by default
• Weekdays can be omitted from the string and defaults to Mon..Sun
• HH:MM can be omitted from the string and defaults to 00:00 (midnight)
• * can be used to match any year, month, day, hour or minute
• Extra zero in front is not required for numbers less than 10
• Multiple months, days of month, weekdays, hours and minutes can be specified when separated with a , (comma)
• Range of months, days of month, weekdays, hours and minutes can be specified by separating two values with a .. (double period)
• Comma and double period can be combined within one element
• In place of DD, W1–5 can be used to match a specific week number.
• In place of DD, L1–31 can be used to match last day of the month as a starting point for the day number instead of its start.
• In place of DD, L to match the last day of the month
• /1–.. is a repetition suffix, which matches specific element and also any multiples of the repeat value, starting with the specified element itself. This suffix is allowed with month, day (including L), hour, minute

Actions without terminal enabled

Action	Dependency	Format
relay	RELAY_SUPPORT=1	relay <ID> <STATUS>, where ID is n-th relay and STATUS is one of: on, off or toggle
channel	LIGHT_PROVIDER!=LIGHT_PROVIDER_NONE	channel <ID> <VALUE>, where ID is n-th channel and VALUE is a value between 0 and 255
curtain	CURTAIN_SUPPORT	curtain <ID> <VALUE>, where ID is n-th curtain and VALUE is a value between 0 and 100

Notes

• ⁽¹⁾ https://github.com/xoseperez/espurna/blob/dev/code/espurna/scheduler.cpp
• ⁽²⁾ https://github.com/xoseperez/espurna/issues/131
• ⁽³⁾ https://www.freedesktop.org/software/systemd/man/latest/systemd.time.html#Calendar%20Events
• ⁽⁴⁾ https://github.com/xoseperez/espurna/wiki/Terminal
• ⁽⁵⁾ https://en.wikipedia.org/wiki/Sunrise_equation#Complete_calculation_on_Earth
• ⁽⁶⁾ https://github.com/nathan-osman/go-sunrise
• ⁽⁷⁾ https://github.com/nathan-osman/go-sunrise/pull/11
• ⁽⁸⁾ https://en.wikipedia.org/wiki/ISO_8601
• ⁽⁹⁾ https://en.wikipedia.org/wiki/Coordinated_Universal_Time