Configuring ETHA Light Switch

The configuration of ETHA Light Switch is defined in the file /etc/etha/etha-light-switch.conf. If that file or directory doesn’t exist, create it. You can change the location of the configuration with a parameter when starting ETHA Light Switch: /opt/etha/etha-light-switch -d /path/to/configuration_directory. Make sure that the file etha-light-switch.conf is present in that directory.

Here’s an example of etha-light-switch.conf with only the default values filled in:

[common]
group_name =
light_name =
default_flash_time = 15
shift_solar_times = False
clock_rules_filename = etha-light-switch
invert_nm_state_led = False

[coordinates]
latitude = 0
longitude = 0

[time]
time_server = pool.ntp.org

[mqtt]
mqtt_broker = 
mqtt_broker_port = 
mqtt_broker_scheme = tcp
mqtt_username = 
mqtt_password = 
mqtt_topic_base = 
mqtt_topic_identification = 
mqtt_topic_group = 

[gpio]
gpio_light_switch_led = 0
gpio_nm_state_led = 0
gpio_relay = 0
gpio_button = 0

The configuration file is read and written by Python’s ConfigParser. Some of the options in this file can be changed from within the Android app. You can add comments to this file, but they are overwritten by changing options with the Android app.

[common]
[coordinates]
[time]
[mqtt]
[gpio]

Section headers. Mandatory, except when there are no options in that section. Then the section headers are optional.

group_name

String. Optional. No default value. If this option is specified, mqtt_topic_group is mandatory and vice versa. This option is just a name. In the ETHA Manager Android app time switches with the same mqtt_topic_group will be grouped together.

light_name

String. Mandatory. No default value. The name of the time switch.

default_flash_time

Integer. Optional. The default value is 15 (minutes). In ETHA Light Switch a flash is defined as a period that the light is switched on, uninterrupted by any clock rules. After the flash period the light is switched off, regardless of the clock rules. A flash period can be initiated by long pressing the button (three seconds) or by using the Android app. Long pressing the button will result in a flash period of default_flash_time minutes. Using the Android app, the flash period can be adapted from a preset value of default_flash_time.

shift_solar_times

Boolean (true or false). Optional. The default value is False. Solar times are computed every day in ETHA Light Switch. The following solar times are defined:

Solar midnight. The darkest period of the night. The opposite of solar noon.
Astronomical twilight begin. The time in the morning that the center of the Sun is 18 degrees below the horizon.
Nautical twilight begin. The time in the morning that the center of the Sun is 12 degrees below the horizon.
Civil twilight begin. The time in the morning that the center of the Sun is 6 degrees below the horizon. This is the time most people would call the beginning of twilight.
Sunrise. The moment when the upper limb of the Sun appears on the horizon in the morning. Also called dusk.
Solar noon. The moment when the Sun reaches its highest position in the sky.
Sunset. The moment when the upper limb of the Sun disappears under the horizon in the evening. Also called dawn.
Civil twilight end. Evening civil twilight begins at sunset and ends when the center of the sun reaches 6 degrees below the horizon.
Nautical twilight end. The moment when the center of the sun is 12 degrees below the horizon in the evening.
Astronomical twilight end. The moment when the center of the Sun is 18 degrees below the horizon in the evening.

All these times are calculated as a function of date and location (latitude and longitude) on earth. At certain dates in certain places, however, not all of the solar times are defined. In the far north, for example, even sunset and sunrise can be undefined in the middle of summer, simply because the Sun never disappears below the horizon. Twilight times will then also be undefined. The only solar times that are always defined are solar midnight and solar noon.

So what to do if you have a clock rule to automatically switch on your lamp at civil twilight end, and there is no such thing as a civil twilight end? The option shift_solar_times controls that situation. If shift_solar_times = False that particular clock rule will be dropped altogether. If shift_solar_times = True, however, the clock rule will shift one (or more) solar times. In the morning it will shift up from astronomical twilight begin, until it eventually reaches solar noon, and in the evening it will shift down from astronomical twilight end, down to solar noon. Of course this can give some strange results, so handle with care!

clock_rules_filename

String. Optional. The default is etha-light-switch. This will expand to /path/to/configuration_directory/etha-light-switch.json (default: /etc/etha/etha-light-switch.json). The clock rules of a given time switch will be stored on that time switch (and not in the Android app).

invert_nm_state_led

Boolean (true or false). Optional. The default is False. The state led indicates the state of ETHA Light Switch. The led is turned on when the program starts, is blinking when there is no network connection and indicates with a short blink that a command is received from the Android app. This is the default situation. But sometimes it is desirable that the led doesn’t light up the room (for instance when you want to install ETHA Light Switch in a bedroom). With invert_nm_state_led = True the light on and off states of the led are reversed. If ETHA Light Switch is running, the led will be off, a disconnected network will still be indicated by a blinking led (instead of on/off, the led will be blinking off/on), and a command received from the Android app will still be indicated by a short blink.

latitude

Double-precision floating-point. Optional. The default value is 0 (degrees). Value should be between -90 and 90 (including). Latitude and longitude are necessary to calculate the solar times. You can use Google Maps to determine the coordinates of your location. Just click on your location and a little pop-up will appear with your coordinates. Another method is to leave latitude and longitude at 0 (or omit them) and use the Configuration option in the Android app to get your coordinates from GPS. In the Android app, press on the location button (shown on the right) and wait for a while until the location changes. The longer you wait, the more precise the location will be.

longitude

Double-precision floating-point. Optional. The default value is 0 (degrees). Value should be between -180 and 180 (including). See further under latitude.

time_server

String. Optional. The default value is pool.ntp.org. The hostname of an NTP server. The Raspberry Pi Zero W doesn’t have a hardware clock, so when it is powered up, it needs to get the right time and date from the internet. Fortunately, this is taken care of by the Raspbian (Linux) operating system. This process, however, takes a little time. But when ETHA Light Switch is starting up, it needs to have the correct time and date immediately. That’s why the program makes an NTP call to verify that the correct date and time have been set. While this is not the case, the light switch led blinks, and program execution will be suspended.

The default pool.ntp.org is a cluster of NTP servers known as the NTP Pool. Their recommendation is not to use the pool’s general hostname, but to use a hostname of a local NTP pool (for instance us.pool.ntp.org). Here you can find a list per continent.

mqtt_broker

String. Optional. No default value. The hostname of an MQTT broker. The use of MQTT is explained in MQTT in ETHA Light Switch. If mqtt_broker is not defined, then the ETHA Light Switch Python program will start without MQTT support, so you will not be able to control this time switch with the Android app.

mqtt_broker_port

Integer. Optional. The default value is 1883 if mqtt_broker_scheme = tcp or 8883 if mqtt_broker_scheme = ssl. The port number of the MQTT broker.

mqtt_broker_scheme

String. Optional. Can be either tcp or ssl. The default value is tcp. The protocol used to transmit MQTT messages. Using tcp is not very secure if your MQTT messages will be sent across the internet, since mqtt_username and mqtt_password are not encrypted. In that case it would be best to use ssl. If you use a local MQTT broker on your LAN, however, this is not a problem.

mqtt_username

String. Optional. No default value. The username you’re using with the mqtt_broker. In some cases it isn’t required to use a username and password. This is not advisable, though, since anyone and everyone can then connect to the MQTT broker and control your ETHA Light Switch.

mqtt_password

String. Optional. No default value. The password you’re using with the mqtt_broker.

mqtt_topic_base

String. Mandatory. No default value. Should not begin with or end with a /. This is the same value that is specified on the MQTT broker settings page in the Android app. This is the base value for the MQTT topic. The base will be expanded with other values, depending on whether or not they belong to a group. If mqtt_topic_group is not specified then the following topics apply:

<mqtt_topic_base>/broadcast. On this topic the Android app will send an identify message. All active ETHA Light Switch time switches will respond with a state message on their respective topics.
<mqtt_topic_base>/<mqtt_topic_identification>. On this topic all communication with a single ETHA Light Switch occurs.

If on the other hand mqtt_topic_group ís supplied (and hence group_name is also supplied) then the following topics apply:

<mqtt_topic_base>/broadcast. Same as above.
<mqtt_topic_base>/<mqtt_topic_group>. On this topic messages (on, off and flash) are sent to all active ETHA Light Switch time switches that belong to this group. The time switches answer on their own topic.
<mqtt_topic_base>/<mqtt_topic_group>/<mqtt_topic_identification>. On this topic all communication with a single ETHA Light Switch within the group occurs.

mqtt_topic_identification

String. Mandatory. No default value. This value should be unique within mqtt_topic_base or mqtt_topic_group, depending on whether or not this time switch belongs to a group. See further under mqtt_topic_base.

mqtt_topic_group

String. Optional. No default value. If this option is specified, group_name is mandatory and vice versa. See further under mqtt_topic_base.

gpio_light_switch_led

Integer. Optional. The default value is 0. The GPIO (BCM) pin number to which the light switch led is connected. Can be 0 in the case that you don’t have a light switch led. The functions of the light switch led are:

The primary use of the light switch led is to indicate the state that the lamp connected to gpio_relay is in (on or off).
At the start of the ETHA Light Switch Python program, the program waits for time synchronization to complete. During this period the light switch led will be blinking.
If a message is received from the Android app, the light switch led blinks once (preceded by a blink of the state led).
When a flash timer is active, the led blinks off and on again every three seconds.
If the Raspberry Pi Zero W is going to reboot or shutdown, then both the light switch led and the state led will be turned on and stay on until the Raspberry Pi Zero W nearly has completed the shutdown (or the shutdown phase of the reboot).

gpio_nm_state_led

Integer. Optional. The default value is 0. The GPIO (BCM) pin number to which the state led is connected. Can be 0 in the case that you don’t have a state led. The functions of the state led are:

The state led is on when the ETHA Light Switch Python program is running, except when invert_nm_state_led = True.
The state led is blinking when there is no network connection.
If a message is received from the Android app, the state led blinks once (succeded by a blink of the light switch led).
If the Raspberry Pi Zero W is going to reboot or shutdown, then both the light switch led and the state led will be turned on and stay on until the Raspberry Pi Zero W nearly has completed the shutdown (or the shutdown phase of the reboot).

gpio_relay

Integer. Optional. The default value is 0. The GPIO (BCM) pin number to which the relay is connected that switches the external lamp on and off. Can be 0 in the case that you don’t have a relay connected. There’s not much sense in running an ETHA Light Switch time switch when you don’t switch anything, but this can be useful for testing purposes.

You can connect multiple relays to the ETHA Light Switch. If tou want to switch them simultaneously from within one occurrence of the ETHA Light Switch Python program, you can specify that like this (for instance): gpio_relay = [25, 26].

gpio_button

Integer. Optional. The default value is 0. The GPIO (BCM) pin number to which the button is connected. Can be 0 in the case that you don’t have a button connected. In that case you can only switch the connected lamps on or off by using the Android app, or with the clock rules. The button has more than one function:

A short press of the button switches the lamp alternatingly on or off. A short press of the button is defined as holding the button for less than three seconds. The result of pressing the button will be that the light switch led and the connected lamp(s) will be switched on or off.
As soon as you press the button for more than three seconds (but less than six seconds), the light switch led will blink once (off and then on again). This indicates that the flash timer is started. The flash timer will leave the lamp (and the light switch led) on for the number of minutes specified in default_flash_time. After that time the lamp (and the light switch led) will switch off, no matter what the clock rules dictate at that moment.
When you press the button for six seconds (but less than nine seconds), the light switch led blinks in rapid succession and NetworkManager is restarted. This can be useful in the event the network connection is lost, and NetworkManager isn’t able to reconnect. Restarting NetworkManager will most of the time remedy that.
After NetworkManager has been restarted, the ETHA Light Switch Python program will reload its clock rules. The light switches to the actual state according to the clock rules.
When you press the button for nine seconds (but less than twelve seconds), the light switch led blinks in even rapider succession (twice as fast as the previous time span) and the Raspberry Pi Zero W reboots.
Pressing the button for twelve seconds will result in a shutdown and power off of the Raspberry Pi Zero W. The rapid blinking of the previous phase will stop and both the light switch led and the state led will be turned on and stay on until the shutdown is nearly complete.

The requested action will take place as soon as the button is released within the time span specified, except the last one: the Raspberry Pi Zero W will shutdown and power off as soon as the button is pressed for twelve seconds.

[common] [coordinates] [time] [mqtt] [gpio]