About This File
This is a scene that runs in the background and schedules your scenes that have a '%% timer' included
(the original thread for this scene is <here>)
Scenes can trigger on devices changing status (%% properties), when globals change values (%% globals) and events (%% events) etc.
However, there is no trigger for time or timers - to allow a scene to be started at a specified time.
Well, here is a fix for that... and it makes it very easy to start scenes at specified times of day including sunrise/sunset, at regular intervals, at specified weekdays, and at specified months...
The scene below watches other scenes and allows them to declare "%% time" headers that they will be triggered on
When the Timer.lua scene is installed and started (no configuration needed) we should be able to forget about it and turn our attention to scenes that we want to be triggered at given times.
It's a perfect "tool" to have running on the HC2 as it makes it really easy to add a scene and schedule it to run at a given time. A simple added header to the scene is all that is needed:
--[[ %% properties %% events %% globals %% time 15:00 --]] print("Scene started at 15:00")
This scene will be run at 15:00 every day. To stop it from being scheduled, just remove the "%% time" lines from the header and save the scene again.
A more extensive example with a scene declaring multiple triggers and retrieving the trigger when the scene gets invoked;
--[[ %% properties %% events %% globals %% time log 15:00 bar -- scene triggered at 15:00 every day *00:15 test -- scene triggered every 15min throughout the day --]] print("Scene started") -- Redefine fibaro:getSourceTrigger do local a,b=fibaro;b=a.getSourceTrigger;function a:getSourceTrigger()local c=b(a)local d=a:args()if type(d)=='table'and d[1]and type(d[1])=='table'then if d[1].type~= nil then return d[1]end end;return c end end local st=fibaro:getSourceTrigger() if st.type=='time' and st.time then -- do something when we get a time trigger... fibaro:debug(string.format("Triggered:%s, tag:'%s'",st.time,st.tag)) end if st.type=='time' and st.tag=='log' then -- write out log messages from the time scene fibaro:debug("Time log:") fibaro:debug(st.log) end if st.type=='time' and st.tag=='error' then -- write out error messages from the time scene fibaro:debug("Time error:"..st.log) end
In the scene we also redefine fibaro:getSourceTrigger() to return our timer as an "standard" source trigger. It's not strictly necessary as time triggers are of type 'other' with the arguments coming from fibaro:args(). However, this makes it more streamlined and plays well with standard fibaro source triggers. The timer scene is "drift free" so if you declare a timer on the hour you will be called exactly on the hour, and not slowly start to drift as is very common in many home made Lua timer loops.
Standard 'time' triggers look like
{type='time', tag=<tag>, time=<str>}
tag=<tag> is the (optional) word provided last in the time rule and helps us to identify what time rule triggered our scene.
time=<str> is the time the rule is invoked (in HH:MM format)
Here we also add the keyword 'log' under "%% time" to instruct the time scene to send us log statements.
Log statements come in two versions
{type='time', tag='log', log=<msg>}
Standard log messages are sent at startup and at midnight with the log msg containing information about the time rules scheduled. It's usually nice to get some feedback that the Timer scene has scheduled our scene and for what times.
{type='time', tag='error', log=<msg>}
Error messages are always sent (even without the 'log' keyword). Usually due to time rules being faulty.
When you enable log messages your scene will also be triggered by log messages and not only timers. You need to tell them apart. A good way to test for a time trigger that is not a log message is to test if there is a .time field in the source trigger
if sourceTrigger.type=='time' and sourceTrigger.time then --- do whatever end
IN that case we know that it is a proper time trigger and not a log message, as they lack the .time field.
Ok, the time rules in the example are
15:00 bar
This means that the scene is called 15:00 every day, with the identifier tag "bar"
In the scene we get an sourceTrigger at 15:00 of type
{type='time', time='15:00', tag='bar'}
In the above example we just print out the tag.
*00:15 test
creates a repeating timer that triggers the scene every 15 minutes, and with the tag "test". We get a sourceTrigger of type
{type='time', time='*00:15', tag='test'}
The generic version of a time description looks like
%% time <time list> <conditions> <tag> : <time list> <conditions> <tag>
Examples
-
15:00,17:00 test
creates two timers at 15 and 17 with the same tag "test". -
sunrise test
'sunrise' is a valid time descriptor and evaluates to todays sunrise hour. 'sunset', "dawn", and "dusk" are available too. -
sunrise-00:10 test
We can do simple arithmetic on times (+/-) to create offsets. -
15:00 wednesday test
timers at 15 but only on wednesday, tag "test". -
15:00 wed test
days can be shortened -
15:00 wed,fri test
or listed. -
15:00 wed..fri test
or intervals. -
15:00 1..7 test
interval with first to seventh day of the month -
15:00 lastday test
Only on the last day of the month -
15:00 lastweek test
only in the last week of the month (number_of_days_in_month-6..number_of_days_in_month) -
15:00 monday lastweek test
conditions can be combined. True for Monday of the last week -
15:00 monday lastweek may..aug test
month conditions also available. -
*00:15 test
interval, every 15min starting immediately (when the script starts). Ex. 12:08:33, 12:23:33, 12:38:33 ... -
+00:15 test
interval, every 15min, starting on next even 15min interval. Ex. 12:15:00, 12:30:00, 12:45:00 ... -
+00:15 weekends 10:00..15:00 test
combined with weekend test (sat..sun) and time interval (10:00 to 15:00) -
+01:00 sunrise..sunset may..sep water
every hour between sunrise and sunset and between May and September call scene with tag 'water' -
20:30 2020/05/28,2021/05/27,2022/05/26 earth_hour
"long date" format -
+01:00 oct/28/10:00..dec/30/07:00 tag
Long date intervals. Year can be excluded and month can be the name of the month, and time can optionally be added at the end (not sunrise/sunset)
The <time list> should be seen as the times we want to schedule and the <conditions> as filters, excluding some times from the <time list>
The other way to look at the list of <conditions> is that the spaces are ANDs and commas are ORs. Ex."10:00 thu,sat lasweek tag" is "10:00 ((thu OR sat) AND lastweek), tag"
The complete set of conditions are:
- <time>..<time>, time interval in HH:MM or HH:MM:SS (but also 'sunset' and 'sunrise')
- <week day>..<week day>, day interval. mon..wed, Thursday..Saturday
- <day number>..<day number> - 1..7, first to second day in current month
- <month>..<month>, month interval
- <time>,<time> -- One or more time specifiers. Ex. 10:00,11:00
- <week day>,<week day> -- One or more day specifiers. Ex. monday
- <day number>,<day number> -- Ex. 1,8,15,22
- <month>,<month> -- One or more month specifiers. Ex. june,july,august
- <long date>..<long date> - YYYY/MM/DD/HH:MM. Year cane be left out and time part is optional
- <long date>,<long date> - 2020/may/11/10:00, may/11/10:00, may/11
- alldays - same as mon..sun
- weekends - same as sat..sun
- weekdays - same as mon..sun
- lastday - true if last day of the month
- lastweek - true if last week in the month
- true - always return true. See example below using fibaro global to disable rules
- false - always return false. Effectively disabling the rule.
...and they can be combined.
It's allowed to end a time rule with a comment '--'. It's just removed before parsing the rule. (Wouldn't it be nice to be able to add comments to all headers?)
Ex.
15:00 monday test -- Trigger scene every Monday at 3 PM
A simple example turning on a lamp (with deviceID 55) at sunset-10min and turning off the lamp at sunrise+10min on weekdays
--[[ %% time log sunset-00:10 weekdays turnOn sunrise+00:10 weekdays turnOff --]] print("Scene started") -- Redefine fibaro:getSourceTrigger do local a,b=fibaro;b=a.getSourceTrigger;function a:getSourceTrigger()local c=b(a)local d=a:args()if type(d)=='table'and d[1]and type(d[1])=='table'then if d[1].type~=nil then return d[1]end end;return c end end local st=fibaro:getSourceTrigger() if st.type=='time' and st.tag='turnOn' then fibaro:call(55,"turnOn") end if st.type=='time' and st.tag='turnOff' then fibaro:call(55,"turnOff") end --[[ -- Another solution if st.type=='time' and st.time then fibaro:call(55,st.tag) end --]]
The tag is useful to identify what timer you get so you don't have to test against time again (or you can use it as in the example above, as an argument to a function, fibaro:call in the above case).
We can also let the tag be the name of a function called in our scene at that time. .
--[[ %% properties %% events %% globals %% time log 15:00 bar *00:15 test %% autostart --]] print("Scene started") -- Redefine fibaro:getSourceTrigger do local a,b=fibaro;b=a.getSourceTrigger;function a:getSourceTrigger()local c=b(a)local d=a:args()if type(d)=='table'and d[1]and type(d[1])=='table'then if d[1].type~=nil then return d[1]end end;return c end end local st=fibaro:getSourceTrigger() function bar() print("Bar called") end function test() print("Test called") end if st.type=='time' and st.time then fibaro:debug(string.format("Triggered:%s, tag:'%s'",st.time,st.tag)) if _ENV[st.tag] then _ENV[st.tag]() end end
A more advanced feature is that time rules allows for substituting in values from fibaro globals.
Ex.
<myTime> monday test
This will fetch the value from the the fibaro global "myTime" and insert whatever value it has instead of <myTest>. If the value was "10:00" the rule would be
10:00 monday test
The substitution can be anywhere in the rule and contain anything so be careful.
We also watch if the value of "myTime" changes and if it does it will update the timers for the scene.
One way to use this is to have a global, ex "Stop" that is set to "true" or "false". If we include that in a rule
10:00 monday <Stop> test
We can easily enable/disable the rule depending on what we set "Stop" to.
What's New in Version 2.3 See changelog
Released
Improved time format