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

Starting with version 1.18.0 relative schedule type was added.

Configuration key	Build flag	Description
	SCHEDULER_SUPPORT (1 by default, 0 to disable)	Build scheduler module
	SCHEDULER_MAX_SCHEDULES (10 by default, cannot be zero)	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 (0 by default, 1 to enable)	Build sunrise & sunset module. 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.

Configuration key	Build flag	Description
schType#		Type of the n-th schedule. One of: unknown, disabled, calendar or relative. Note that unknown schedules cannot be saved in settings, and will be removed
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 by default)	0 (disabled, default) or 1 (enable) to attempt to trigger last missed schedule when device syncs time for the very first time.

Command	Description
schedule	shows scheduler status global configuration options
schedule <ID>	shows n-th schedule configuration options
event	shows info about sunrise, sunset and named events
event <NAME>	shows info about a specific event
event <NAME> <DATETIME>	sets event timestamp. Datetime is a timestamp in ISO 8601 format, either using an UTC time (Z or +00:00 at the end) or without it to use device local time

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

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

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

Expected format is HH:MM (24-hour)

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

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

• 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

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

Time string	When action would be triggered
30 AFTER CAL#0	30 minutes after 1st (index 0) schedule action was triggered
AFTER SUNRISE	1 minute after sunrise
30m BEFORE SUNSET	30 minutes before sunset
1h AFTER "something"	1 hour after custom event with the name something

Expected format is <TIME> <WHEN> <EVENT>

• <TIME> - number of minutes or hours between the specified event and the current time
• <WHEN> - either BEFORE or AFTER
• <EVENT>

• Can be omitted. For example before EVENT would mean 1m before EVENT
• A number without m or h suffix is interpretted as m (minutes)
• Same suffix cannot be specified multiple times (i.e. 1h2h is invalid)
• Value is expected to be less than 24h (twenty four hours) for calendar, sunrise and sunset events
• Named events are removed from memory after 1d (one day)
• Calendar events are removed from memory after 1d (one day)

Custom event currently can only be created using the terminal command event (see Terminal section above)

• cal#N or calendar#N, where N is Nth schedule (index starting from 0)
• "NAME" where NAME is a user-created event
• SUNRISE for sunrise, same as calendar keyword
• SUNSET for sunset

• ⁽¹⁾ 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