The clock rules file on the Raspberry Pi Zero W will be parsed by the ETHA Light Switch Python program once a day. The clock rules will be translated to time events (switch the light on or off at a certain time). This clock rules file parsing will be scheduled at the last event of that (UTC) day. If there are no events on a particular day, then a dummy (no-op) event will be scheduled at 23:59 (UTC).
A word about time zones: the Raspberry Pi Zero W is meant to run in your local time zone. You can check by entering the Linux command timedatectl in an SSH terminal. The output should show something like this (but in your own local time zone):
In the UK the standard time zone is GMT (Greenwich Mean Time), but in the summer the daylight saving time zone BST (British Summer Time) is held. Something similar applies to your local time zone.
The Raspberry Pi Zero W runs in your local time zone, but the ETHA Light Switch Python program calculates all times in UTC (Coordinated Universal Time (the abbreviation UTC is a compromise between English and French)). All input to and output from the ETHA Light Switch Python program (and the ETHA Manager Android app), however, is in your local time zone.
The advantage of this is that daylight saving time doesn’t disturb anything. If you, for example, want the light to switch on at 07:00, it switches on at 07:00, no matter the time of year (winter or summer) or the time zone you’re in. Technically, with the start or end of daylight saving time, the time itself doesn’t change. It is the time zone that changes. So in the winter the time will be displayed as 07:00 GMT and in the summer as 07:00 BST. In the conversion from UTC to your local time zone, this is accounted for.
Sometimes this can have strange side effects too, especially if you’re living far from the UTC (GMT) zone. For example, the reparsing of the clock rules is done with the last event on a particular day (if there are no real events that day (switching the light on or off) a no-op event is scheduled at 23:59 UTC). But it is the last event of the UTC day, not the day in your local time zone. So if you live in Wellington, New Zealand, and it’s summer, your local time zone is NZDT (New Zealand Daylight Time). That is UTC+13 (hours). Then a UTC day (00.00 UTC to 23:59 UTC) is 13.00 NZDT to 12:59 NZDT the next day. So if the last event on a day (at which the clock rules are parsed), for example, is 23:00 UTC, that means that the last event is at 12:00 NZDT, even if you have another event at 17:00 NZDT.
Parsing of the clock rules is always done for two days: today and tomorrow. Remember: today and tomorrow are in UTC.
Parsing of the clock rules file will also be done when the ETHA Light Switch Python program is starting or restarting, or receives a reload. The reload can be sent by the Android app and with the Linux command systemctl reload etha-light-switch in a terminal (SSH).
Examples of parsing clock rules into events
Sometimes clock rules collide with each other. How is that handled in ETHA Light Switch? The general rule is: the on state of the light always takes precedence. So when you have a clock rule period of, let’s say, 07:00 to 10:00, and another period of 08:00 to 09:00, the light stays on from 07:00 to 10:00. The former clock rule has precedence over the latter. In fact, there are no events calculated for the latter clock rule. Here are some more examples:
| Clock rule period 1 | Clock rule period 2 | Events at |
|---|---|---|
| 07:00 to 09:00 | 08:00 to 10:00 | 07:00 (on) and 10:00 (off) |
| 07:00 to 08:00 | 08:00 to 09:00 | 07:00 (on) and 09:00 (off) |
| 07:00 to 07:59:301 | 08:00 to 09:00 | 07:00 (on) and 09:00 (off)2 |
| 07:00 to 07:59 | 08:00 to 09:00 | 07:00 (on), 07:59 (off), 08:00 (on) and 09:00 (off)2 |
1 A time like 07:59:30 can only exist as a consequence of a solar time. Clock times are always in hh:mm format.
2 Two subsequent events within one minute (< 00:01:00, ≤ 00:00:59) are discarded.
With solar times there are some more considerations. For example, what happens if you want the light on from sunset (dawn) to 22:00 and sunset happens to be later than 22:00 (in the summer)? Some examples to clarify:
| Clock rule period | Actual solar time value | Events at |
|---|---|---|
| Sunset to 22:00 | 19:12:44 | 19:12:44 (on) and 22:00 (off) |
| Sunset to 22:00 | 21:59:30 | No events1 |
| Sunset to 22:00 | 22:15:33 | No events |
| 07:00 to sunrise | 08:25:47 | 07:00 (on), 08:25:48 (off) |
| 07:00 to sunrise | 06:01:12 | No events |
1 Two subsequent events within one minute (< 00:01:00, ≤ 00:00:59) are discarded.
Complex example
So what happens in this case (see Screenshot Android app)? In the first place it depends on what day today is. So suppose it’s Thursday. Sunset is at 17:58:27 and sunrise on Friday is at 05:13:18. The following happens:
- On Thursday the light switches on at 17:58:27 (according to clock rule At night (week)).
- The light stays on until at least 23:01 and at most until 23:05. Why? The clock rule At night (week) finishes at 23:00. At that time the clock rule Burglary prevention kicks in. That clock rule has a random pattern of 5 minutes on and 60 minutes off (see here). The randomizations yields a time in seconds between 1 minute and 5 minutes on and between 1 minute and 60 minutes off. So at 23:00 on Thursday the light stays on (preceded by the clock rule At night (week)) for 1 to 5 minutes. Then follows a period of 1 to 60 minutes with the light of. And so on…
- And so on until the end of the clock rule Burglary prevention. Assuming that Burglary prevention really works and no-one stole your ETHA Light Switch, at what time does that clock rule end? We need a little bit of calculation here. The clock rule ends at
Civil twilight begin + 25 (next day). The clock rule started at 23:00 on Thursday, so the next day is Friday. Now suppose civil twilight begin on Friday is at 04:38:23. The divider into the next solar time (see here) is 0.25, and the next solar time is sunrise (at 05:13:18). So the calculated time (according to the formula) is:
(The fractional part of 00:08:43.75 gets rounded off.) So at 04:47:07 the light turns off or stays off (depending on the state of the light at that moment due to the random pattern).time = solar_time + ((next_solar_time - solar_time) * divider) time = 04:38:23 + ((05:13:18 - 04:38:23 ) * 0.25) time = 04:38:23 + ((00:34:55 ) * 0.25) time = 04:38:23 + ((00:08:43.75 ) ) time = 04:38:23 + ((00:08:44 ) ) time = 04:47:07 - And that’s the end of it. The next clock rule (In the morning (week)) doesn’t do anything because 07:00 is way later than sunrise (05:13:18). There are no events generated due to this clock rule.