If you don’t want to use MQTT and the ETHA Manager Android app, you need to know how to configure the clock rules file. This file is easily configurable with the Android app, and it’s a bit harder to edit manually.
This file is located in the configuration directory (default: /etc/etha). The file is normally named etha-light-switch.json, but this can be changed with the clock_rules_filename option in the configuration (see here).
The clock rules file will be parsed by the ETHA Light Switch Python program and converted to events. See Converting clock rules to events.
The clock rules file is a JSON file. Here’s an example:
[
{
"name": "At night (week)",
"active": true,
"day": [1, 2, 3, 4, 7],
"period": {
"from": "sunset",
"to": "23:00",
"to_next_day": false
},
"divider": {
"from": 0,
"to": 0
}
},
{
"name": "At night (weekend)",
"active": true,
"day": [5, 6],
"period": {
"from": "sunset",
"to": "00:30",
"to_next_day": true
},
"divider": {
"from": 0,
"to": 0
}
},
{
"name": "Burglary prevention",
"active": true,
"day": [1, 2, 3, 4, 5, 6, 7],
"period": {
"from": "23:00",
"to": "civil_twilight_begin",
"to_next_day": true
},
"divider": {
"from": 0,
"to": 0.25
},
"pattern": {
"on": 5,
"off": 60,
"randomize": true
}
}
]JSON is very error prone if you edit it manually. It is very sensitive to errors in punctuation. So when you edit this file, it’s best to check the syntax with an online tool like JSONLint. That doesn’t guarantee it’s error-free for this particular file, but at least the errors will be syntactically correct.
Here’s what all the options mean:
name
String. Just a (explanatory) name.
active
Boolean (true or false). Indicates whether this particular clock rule is active or not. This offers a quick way to inactivate the clock rule without the need to delete it completely.
day
Array of integers. Indicates on which days this clock rule is active. 1 means monday, 2 tuesday, until 7 sunday (according to ISO 8601).
period
Object consisting of three members: from, to and to_next_day. period describes a period wherein the light is on.
period: from
String. The time at which the light is switched on. This can be a clock time or a solar time. If it is a clock time, it consists of hour and minute in the 24-hour clock notation (“military time”). The format is: hh:mm with leading zero’s (for example 07:05 or 22:50).
It can also be a solar time. In that case it should be one of the following:
solar_midnight.astronomical_twilight_begin.nautical_twilight_begin.civil_twilight_begin.sunrise.solar_noon.sunset.civil_twilight_end.nautical_twilight_end.astronomical_twilight_end.
See here for an explanation of solar times.
period: to
String. The time at which the light is switched off. This can be a clock time or a solar time. See further under from.
period: to_next_day
Boolean (true or false). Indicates whether the to time is on the day following the from time. In the Android app this field will sometimes be fixed if it’s obvious that the to time is on the next day (for example in the case when the from time is 23:00 and the to time is 07:00). But when you edit the clock rules file manually, you must take care of the right value of to_next_day. If you’ve got it wrong, then this clock rule will never turn the light on! A clock rule where from time is 23:00 and to time is 07:00 and to_next_day is false will be silently disposed of.
divider
Object consisting of two double-precision floating-point: from and to. Each of the double-precision floating-points should be between 0 (including) and 1 (excluding). These values only mean something if the corresponding time is a solar time.
divider: from
Double-precision floating-point. See also under divider. This option adds time to the period: from time if that time is a solar time. The time difference between the period: from time and the next solar time will be multiplied by divider: from and then added to the period: from time. In a (Python) formula:
time = solar_time + ((next_solar_time - solar_time) * divider)
So a divider: from value of 0.5 yields the time exactly halfway between two solar times.
The solar times as described under period: from are treated as a round-robin array, so the next solar time of sunrise is solar_noon and the next solar time of astronomical_twilight_end is solar_midnight (obviously of the next day).
So when you think that sunset is too early to switch on the light and civil twilight end is too late, you can give period: from the value of sunset and divider: from a value of 0.25, for instance.
divider: to
Double-precision floating-point. See also under divider and divider: from. This option adds time to the period: to time if that time is a solar time.
pattern
Optional object consisting of three members: on, off and randomize. Normally the ETHA Light Switch switches the light on at period: from and off again at period: to. So the light stays on during this period. With a pattern you can change that. A pattern consists of an on time in minutes, followed by an off time in minutes, and then again followed by an on time (et cetera). The on time starts at period: from. The cycle of the pattern is interrupted by period: to. No matter what the state of the light is, the light switches off (or stays off) at period: to.
pattern: on
Integer (minutes). See under pattern.
pattern: off
Integer (minutes). See under pattern.
pattern: randomize
Boolean (true or false). If this option is true, the values of pattern: on and pattern: off are randomized between 1 minute and the time in minutes defined in pattern: on and pattern: off. The randomization is done in seconds.
This means that the pattern itself is also randomized. If pattern: randomize is false, the pattern will always last for pattern: on plus pattern: off minutes. But if pattern: randomize is true patterns will have random lengths.
The randomizations will be done beforehand, namely at the time the clock rules file is parsed to calculate the switch events in the ETHA Light Switch.