App manual – Main screen of the Android app

When starting the Android app, the main screen is blank, showing a progress bar while the app is waiting for time switches to respond to an identify (broadcast) message. When the first reponse arrives, the main screen shows (and updates) all the ETHA Light Switch time switches that answer this broadcast query from the Android app with a state message.

The time switches are first ordered according to the MQTT broker on which they answered the broadcast query, then according to the group to which they belong (that is, group_name, not mqtt_topic_group (see Configuring ETHA Light Switch)), and finally on their name (light_name, not mqtt_topic_identification).

If a time switch has been active previously but is now not accessible, it is grayed out. When you click on such time switch, you’ll get an error message with the reason why it is inaccessible.

To refresh the main screen you can swipe down. The list of time switches is cleared, and a new identify message is broadcast. Active time switches will reply, inactive ones obviously not.

On this main screen there are numerous options. With all of these options, at least one MQTT message is sent to the ETHA Light Switch Python program and the Android app waits until a response is received. While waiting a progress bar is shown. You can interrupt the progress bar by pressing outside of it, or by pressing the (Back) button of your device. The ETHA Light Switch Python program shows that a message has arrived by blinking both leds alternately. This is true for almost all messages except for the on, off and flash messages.

What follows is a description of all options:

Toggle on-off

Toggle the time switch (and thus the connected lamp(s)) on or off. You can press on the toggle button itself, or on the name of the time switch. That makes no difference. As a result of pressing the toggle button or the name of the time switch, a command is send to the time switch. Every time a command is send, you’ll (most of the time briefly) see a progress bar shown on a dimmed background, waiting for a response to arrive (shown on the right).

When the answer (a state message) from the time switch arrives, the progress bar is removed, and the on-off toggle will then reflect the new state of the time switch (this happens only after the answer is received, not before).

Switch group or MQTT broker on or off

With these buttons (on the MQTT broker or group level) all time switches (and their lamps) belonging to that MQTT broker or group are switched on or off. These buttons are not toggles: they switch on or off. So when some time switches belonging to the group or MQTT broker are already switched on or off, they won’t change state.

Flash on

This button is used to send the flash message to a time switch. 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. See here for more.

After pressing the flash button, a dialog pops up asking for the time of the flash in minutes. Initially this time will be set to the default flash time. This value has been preset in the configuration (default_flash_time). You can enter a flash time from 0 to 1439 minutes (1439 minutes is 23 hours and 59 minutes). To enter values greater than 59 minutes, press on the hour field. Pressing ok sends the flash message to the time switch. The connected lamp switches on and stays on until the flash timer ends. Then the lamp switches off. This happens regardless of the clock rules. While the time switch is in flash mode, the light switch led blinks off shortly and then on again every 3 seconds.

You have several options to cancel a flash timer:

• Switch the time switch (and the connected lamp) off.
• Switch the time switch (and the connected lamp) on. This can’t be done witch the toggle switch, nor with the button on the ETHA Light Switch, because then you’ll only be reversing the state (and the light is already on), but you can do that by turning all time switches on in the group or MQTT broker to which they belong to (see above).
• Reload the clock rules (see below). When the clock rules are reloaded, the time switch cancels the flash timer and continues with the clock rules. When the light should be on according to the clock rules, the light stays on, otherwise the light switches off. The same happens when you restart the ETHA Light Switch Python program or when you reboot the Raspberry Pi Zero W altogether (see also below).
• Start a new flash timer (with the button of the ETHA Light Switch or through the Android app). The old one will then be canceled.

Flash group or MQTT broker automatic

This will send a flash message to all time switches in the group or connected to the MQTT broker. You will not be asked for a flash time, but all time switches will start a flash timer according to their respective default values. Pressing this button again cancels the flash timer and starts a new one.

Clock rules indicator

These buttons indicate the state of a time switch according to its clock rules. They don’t indicate the real state of the time switch, because a time switch can be on while the clock rules indicate an off state.

• This button indicates that, according to the clock rules, the light is switched off. This is not an indication of the real state however, because the light can also be switched on as a consequence of a button press or a flash timer.
• According to the clock rules, the light should be switched on at the moment.

In both the cases above, the button not only indicates the state of the light according to the clock rules, but by pressing the button you can view and edit the clock rules of this time switch (see below).

• This button looks like the one above, except that it doesn’t have the “alarm bells”. This button also has the same meaning as above, but pressing it leads to an error message (see below). The reason for this is that the ETHA Light Switch Python program on the other end runs as a so-called “satellite” (see here). A satellite time switch can have its own clock rules (in which case the button above is shown, and the clock rules are editable), but in this case the clock rules are shared with the “main” ETHA Light Switch Python program and can only be shown and edited there.
• According to the clock rules, the light should be switched on at the moment.

In these cases, the button can’t be used to view and edit the clock rules of this time switch.

The error screen above is shown when you try to view or edit the clock rules of a time switch which doesn’t have its own set of clock rules. To remove this message, simply press on a space outside the message.

Other options

Pressing the button with the Raspberry Pi logo opens the following menu:

Even more options are available now:

Scheduled events

Pressing this button shows all events scheduled for this time switch. The events are collected from the time switch, so you have to reckon with a short delay during which a progress bar is shown. After that a popup opens showing all events known to the ETHA Light Switch Python program on the Raspberry Pi Zero W:

Events are a direct result of the clock rules you’ve set. See Converting clock rules to events for an explanation of that process.

Only events in the near future (at most two days) are shown. The dates and times are shown in the local time zone (that is, the local time zone of the Raspberry Pi Zero W, not of your Android device) at the moment of the event. So if you’re currently in a daylight saving time zone, events for tomorrow can be in the standard time zone and vice versa.

Events sometimes require further explanation. This is done in footnotes. Possible footnotes are:

• Schedule next events. At the event denoted by the footnote, the next parsing of the clock rules into events will be done.
• Irrelevant because of previous state. This event switches nothing because the light is already on or off. This could be the case when the light is switched on or off manually.
• Irrelevant because of flash timer. In this case the flash timer ends after the event. A flash timer always takes precedence over events.
• End of flash timer. At this time the light will be switched off because the flash timer ends.

Solar times

Pressing this option opens a dialog asking you for the date for which you want to know the solar times (see here for an explanation of solar times). The dialog defaults to your current local date, but that date is interpreted as being UTC:

The solar dates are then collected from the time switch (so the popup starts with the progress bar), and then the solar times of that particular time switch are shown. The date is repeated (again, interpreted as UTC) and the location for which the solar times are calculated. The location is shown here in degrees, minutes and seconds (and fractions of seconds), as prescribed in the ISO 6709 standard. All dates and times of solar times are shown in the local time zone of the Raspberry Pi Zero W.

Configuration

This will show certain aspects of the configuration of the ETHA Light Switch Python program. You can also change these configuration options. See below.

Reload

Pressing this button will reload the clock rules file on the Raspberry Pi Zero W. It has the same effect as entering the Linux command systemctl reload etha-light-switch in an SSH terminal. This also reparses the clock rules into events (see Converting clock rules to events), cancels a contingent flash timer, and switches the state of the light (on or off) in accordance with the clock rules.

Restart

Pressing this button will restart the ETHA Light Switch Python program on the Raspberry Pi Zero W. It is the same as entering the Linux command systemctl restart etha-light-switch in an SSH terminal. As a matter of fact, the ETHA Light Switch Python program does precisely that. That is also the reason this option can be grayed out (and nothing happens when you press it): if the ETHA Light Switch Python program is not started through systemd (but, for instance, from the command line), the ETHA Light Switch Python program cannot restart itself.

Reboot

Pressing this button will reboot the Raspberry Pi Zero W this ETHA Light Switch Python program is running on. After the acknowledgement that the message is received, both LEDs on the ETHA Light Switch are turned on. They will be turned off when the shutdown of the Raspberry Pi Zero W is nearly complete. The state LED will be turned on as soon as the Raspberry Pi Zero W has completed the reboot and ETHA Light Switch Python program has started up.

Poweroff

Pressing this button will shutdown and power off the Raspberry Pi Zero W this ETHA Light Switch Python program is running on. After the acknowledgement that the message is received, both LEDs on the ETHA Light Switch are turned on. They will be turned off when the shutdown of the Raspberry Pi Zero W is nearly complete. A few seconds after that, the power off is complete. You can now safely remove the ETHA Light Switch from the wall socket.

Main menu

On top of all this, the main screen also has its own main menu. You can access it via the menu button.

The choices here are:

MQTT brokers

This takes you to the MQTT brokers screen, where you can add, modify and remove connections to MQTT brokers.

Help

This button exists on all pages of the ETHA Manager Android app. It takes you to the appropriate page on this website. The webpage will be opened in the app itself (no external internet browser will be used).

Settings

This button leads to the settings page of the ETHA Manager Android app.

App manual

This button opens the homepage of the ETHA Manager Android app manual. The webpage will also be opened in the app itself.

ETHA website

This button opens the homepage of www.etha.erik.terwan.nl. This time an external internet browser will be used.

Donate

This button takes you to www.paypal.me/ErikTerwanSr in an external internet browser, where you can buy me a cup of coffee or a box of cigars to show your appreciation for developing and publishing this project. For the time being this can only be done through PayPal because other options are too expensive.