User Guide
If an important event occurs, a message is displayed for about 5 seconds at the bottom of each screen. Typically you only see these as the clock starts up, typically in this order:
- setup...
- Connecting... - The clock is trying to connect to WiFi
- The clock's SSID
- The clock's IP address
- AP Destroyed - This only if the clock created an access point because it couldn't connect to WiFi. The access point is closed 30 seconds after it successfully connects.
- NTP time received...
Remember that hostname in the config portal? Go to elekstubeips.local (or whateverhostnameyouentered.local) and you will see this display. If the device you are on doesn't recognize .local hostnames, you will need the IP address that is displayed briefly when the clock connects to WiFi (if you don't remember it, just unplug the clock and plug it back in).
Clicking on the three bars at the top left of the page allows you to navigate to each screen:
When you make a change with this GUI it is immediately reflected in the clock display, and any change you make directly on the clock will also be immediately reflected in this GUI. You don't need to hit a save or a set button. The changes you make will also be saved to non-volatile storage every 60 seconds or so, so if you cycle the power on the clock it will come back up in the same state.
You can set the clock display format using the clock menu. All changes are immediately reflected in the clock display. A key field here is the Timezone Definition, this sets the timezone and the DST rules. Follow the link on the GUI to find the right string for your location:
This is the backlight configuration screen. You can select different effects from the drop down and configure each one:
This screen allows you to change the clock face and the weather icons.
- Select either Clock Faces, Weather Icons or Slide Show at the top to see the list for each.
- The current clock face/icon set is hilighted in blue, click on another one to change it. Changing takes a few seconds (it has to unzip the new images), you will see circular meters displayed showing the progress.
- You can upload additional clock faces by clicking on the Upload button.
- You can delete clock faces by clicking on the trash can icon - you can't delete the currently selected set.
You can find additional clock faces here:
- https://github.com/judge2005/EleksTubeIPS/tree/main/more_faces
- https://github.com/Spider19996/Tube-Clock-Faces
You can also make your own either using your own images or using others available on the internet. There is explained elsewhere in this documentation.
The full set of weather icons is available at https://github.com/judge2005/EleksTubeIPS/tree/main/weather_icons
There are only two slide sets provided with the firmware. They are:
- anime_female
- blank
blank is there only to free up space on the clock if you aren't displaying images.
This screen allows you to configure the weather forecast shown when Display mode is set to weather.
The weather information is retrieved from openweathermap.org using version 2.5 of their API. You will need to get an API key from them to use with this software. This free plan allows you to make 1,000,000 calls to their API per month. That is over 32,000 calls per day, or around 1 call every 3 seconds. The firmware makes a call once every 30 minutes, so you could run several clocks with the one API key and not worry.
The code for retrieval of the weather data is well encapsulated, so if you have some other source of data you would prefer to use, you could always write a class to do so.
On this screen you will need to provide:
- Your API key
- The latitude and longitude you want the weather forecast for. It isn't hard to get this from google.
- Choose Imperial for farenheit and Metric for celsius. Openweathermap reports the temperatures in Kelvin, but I didn't think anyone would want to display those.
You can also click the Get Weather button to force an update if you want to. The display can take over 10 seconds to redraw with the new data.
The Foreground Color section is used to control the color of the monochrome weather icons. You can tweak this to match the number icons used by the clock
There are a choice of two screen savers:
- Blank, which turns the power off to the displays, but not the LEDs
- Matrix, which displays a digital rain screen saver based on the effect used in the Matrix movies Other feature include:
- You can adjust the idle time before the screen saver comes on from 1 to 120 minutes, or never.
- You can trigger the screen saver manually by clicking the power button.
- Any interaction with the clock will cancel the screen saver, i.e. click any button or interact with the clock using the web GUI
This just turns the power off to the displays. The web page looks like this:
You configure many aspects of this including:
- The animation speed
- The color, brightness and saturation
- Enable/disable color cycling This is what the config screen looks like:
This is what the display looks like:
Starting v1.5.0 the clock exposes some functionality using MQTT and Home Assistant Discovery. Specifically it exposes controls for movement and luminance sensors:
- The display brightness can be set using MQTT, allowing you to use a luminance sensor to control the screen brightness (for example)
- The screen saver timer can be reset using MQTT, so if you set a delay timer for when the screen saver starts, you can use a movement/occupancy sensor to reset the timer whenever there is movement detected.
To use this, set the MQTT broker connection information in the MQTT screen:
The clock will publish Home Assistant Discovery messages to MQTT, so if you have MQTT integrated with Home Assitant, the clock will automatically appear as a device with several entities:
These are the control topics (replace with the clock's SSID):
- clock/<SSID>/set/brightness - should be in the range 10 through 255
- clock/<SSID>/set/screen_saver - should be the string "ON" or "OFF"
- clock/<SSID>/set/screen_saver_delay - should be a number in the range 0 through 120 - it is the time in minutes with 0 meaning always off
- clock/<SSID>/set/custom - should be a 6 character string, for example "10_99_2" would display '10 99 2'
- String format:
- numbers 0-9,
- ':' for colon
- ' ' and '_' for space
- 'a' and 'p' for AM and PM
- send 'clear' or empty string to stop displaying custom data
- String format:
- Backlight control
- clock/<SSID>/set/backlight_hs - sets the hue and saturation of the backlight. Format is ,. hue is a floating point number in the range 0 to 360. saturation is a floating point number in the range 0 to 100.
- clock/<SSID>/set/backlight_state - "ON" or "OFF"
- clock/<SSID>/set/backlight_brightness - 0 through 255
- Underlight control - only availble for the IPSTube firmware
- clock/<SSID>/underlight_hs - sets the hue and saturation of the underlight. Format is ,. hue is a floating point number in the range 0 to 360. saturation is a floating point number in the range 0 to 100.
- clock/<SSID>/underlight_state - "ON" or "OFF"
- clock/<SSID>/set/underlight_brightness - 0 through 255
These are the discovery topics:
- homeassistant/number/<SSID>/brightness/config
- homeassistant/switch/<SSID>/screen_saver/config
- homeassistant/number/<SSID>/screen_saver_delay/config
- homeassistant/text/<SSID>/custom/config
- homeassistant/light/<SSID>/backlight/config
- homeassistant/light/<SSID>/underlight/config
These are the state topics:
- clock/<SSID>/persistent/state - this is everything that can be configured using the web GUI
- clock/<SSID>/volatile/state - this includes the brightness, screen saver state and custom display state
With this screen you can:
- Change the hostname of the clock, which is essential if you have more than one clock of the same type on your network. The clock will restart if you change the hostname.
- Enable the Access Point. This allows you to modify which network the clock is connected to, and allows you to modify the hostname of the clock.
This screen is for the data nerds amongst you. It shows interesting information about the clock such as IP address, MAC address, Program size, free heap, file system size, free space on the file system, last time it synced the time with NTP etc. etc.
You can control some aspects of the clock using the buttons on the clock. You can:
- Change the clock face
- Change the weather icons
- Switch between time/date/weather display
- Run the screen saver
- Override the on/off state of the clock (turn it off if it is on or turn it on if it is off)
- Briefly turn the clock on if it is off.
Off means it is in the off period set in the web GUI, rather than that the screen saver is running:
- Click or pressing any button will display the time/date/weather at full brightness for 10 seconds.
- Long pressing the power button will turn the clock back on until you either long press it again, or the until the end of the next on period.
Clicking any button (or using the web GUI) will turn the screen saver off.
- Clicking the power button will turn the screen saver on.
- Long pressing the power button will turn the clock off (i.e. change the display to whatever you have configured for the off period in the web GUI) until you either long press it again, or until the end of the next off period.
- Clicking the mode button will cycle through the time/date/weather displays.
- Long-pressing the mode button will draw the Clock Faces menu if you are on the time or date display, or draw the Weather Icons menu if you are on the weather display.
- Long press the mode button again to exit the menu without making a change
- Press the left and right buttons to move up and down(!) in the menu. Note a little arrow is displayed to indicate if there are more items off the bottom or top of the menu.
- Click the mode button to select an item - the menu will be removed and the clock face/weather icons will change if you selected a different one.
