In webCoRE there are several trigger comparison types around stays:
- stays
- stays equal to
- ...
Stays means we want to check in the future if things stay the way they are now
In general there are 3 time periods one can want to use
- past (see below - condition comparison)
- present (these are tracking triggers like changes*, drops*, remains*, rises*, enters*, exits*)
- future (here - stays* trigger comparisons)
So what is going on with stays*:
Let's assume the starting state is we have not run since saving and the contact is open
In this example the piston will subscribe to the vctl1:contact events (because it is in use by this stays comparison)
If I hit the 'test' piston in the IDE, the piston runs:
First execution
-
the test event wakeup occurred, and we began executing the piston from the beginning/top
-
the if at line 2 return FALSE, which means one or more of
-
the contact is not now open
-
or value is as requested AND we are initializing the timer to monitor 2 minutes to resume at #2
- or value is as requested AND the existing timer (from an earlier run) has not fired yet
-
-
The if returns false, because monitoring vctl:contact being open for 2 minutes has not occurred and the else clause is executed
-
-
piston exits because it ran to the end
result: the log message contact not open or has not been open for 2 minutes is printed, and a timer is set for 2 minutes from now
Second execution
2 minutes later the timer fires
-
the piston is started because of a timer event (saying to resume at 2)
-
the piston resumes at #2, which now returns true. (contact is open and we know it stayed open for two minutes from the first run)
- the piston executes stayed open message
-
piston exits because it ran to the end
Alternate execution 2
The contact changes to closed during the 2 minutes
-
The piston starts at the top with event vctl:contact:closed
-
The if at line 2 returns false because the contact is not open
-
the stays detects the earlier timer, and cancels it
-
the piston logs again contact not open or has not been open for 2 minutes is printed
-
-
piston exits because it ran to the end
Execution 3 (after alternate 2)
The contact changes to open
-
The piston starts at the top with event vctl:contact:open and the if returns false because the contact is open and the timer is being set.
- ie we are back to the execution 1 case
Few things to note:
-
First time executing stays, the stays if returns false and if the condition matches it sets the timer to monitor the condition and resume in the future
- if the timer fires then TRUE is returned on the resume
- If the initial condition state changes (ie contact is not open event in this example), any timer set is cancelled and the if returns false.
-
Stays* are a tracking trigger comparison, so like other tracking trigger comparisons
-
they should be at level 1 looking left to right (ie they are not nested below other if's, else's or restrictions) so that state changes can be track for the initial condition
-
stays when setting the future timer, is not blocking the piston execution like a 'wait', ie true or false the stays command did not block/pause the piston.
-
- This also means that mixing stays with other conditions like
-
if a is true and/or b stays open
-
is generally not a good idea, because on resume from the timer, some of the additional conditions may not be true any longer due to the wait for the timer
- trigger aggregation can be a workaround for this with setting of a boolean for use later.
-
What if I want to see if in the past something did or did not change?
-
webCoRE has several condition comparisons (was* and changed*). (ie was equal to for example) that allows you to understand if in a period of time in the past a value comparison is true).
- this depends on the depth/history of the HE database (device states) on how far you can look back. You should be pretty safe for the last state of an attribute.