wordclock

WordClock User’s Manual

First time use

When you are powering the device for the first time after flashing the firmware, it will create its own WiFi Access Point with SSID WordClock.

Use your smartphone (or tablet, or computer) to detect the WiFi network, and connect to it by using the password password (or 12345678 in the old 1.0 firmware).

Configuration page (Config portal)

After a successful connection to the Access Point, a configuration page should show up in your web browser (there might be a notification to tap).

It should look a bit like that:

Note: At this point even if your home network is not configured, the clock is already useable in an offline manner, especially if you have a battery cell and RTC module.

Except for password fields, you will see the item values previously set (or for first time setup, the factory default).

Password fields

On password fields you will never see any previously set values. You can reveal a password you just entered by clicking the 👁️ (eye emoji). You can then click a second time to hide the text, which is recommended before submitting the configuration form, as browsers might save clear text values to use them as suggestions.

Some fields are protected with constraints, and a validation check is performed. In case there is an error in the validation of any field, nothing is saved and a red message should appear next to the field that caused an error. You will need need to re-enter values for filled-out passwords in this case.

Configuration options

Here are the available configuration options.

Network

The Network section will show at the top of the page if it has not been configured before, and will afterwards move to the bottom (as shown in the screenshot above) since it probably doesn’t need to change it very often.

Display

Time

API

Enables a non password-protected API and experimental paint web interface.

MQTT

You can enable the MQTT client and configure your server’s adress, login and password here. For more details on this feature, see the dedicated section below.

Note: When this is enabled, any configuration changes will cause a reboot of the clock. Therefore it is recommended to turn it off when playing with other settings in order to avoid having to wait for the clock to reboot and reconnect to your WiFi every time.

Connecting to a WiFi network

When you have successfully set the WiFi configuration fields, the device will try to connect to it.

If the connection fails, the device will fall back to Access Point mode. This means that the device will form its own WiFi network again, to which you can connect to and try to correct the network setup. This time you will see the Clock name value as the access point name (SSID) - WordClock if you haven’t changed it - and you need to use the AP password that you should have configured previously.

Note that in such a case where the configured WiFi network is not connecting, the device will fall back to Access Point mode only for a few seconds as it will periodically retry connecting to it. After all, maybe your configuration was OK and it’s your WiFi that was down 🙂.

Once you connect in Access Point mode, it will be kept running as long as any device is connected to it. You’ll need to disconnect your device from it for the clock to continue its operation (ie reboot).

Configuration in connected mode

After the clock successfully connects to the configured WiFi network, the temporary Access Point is terminated, but you can still access the clock using its IP address.

To determine the IP address of your clock, you might want to consult with your WiFi router (it might also be possible to use a local domain such as wordclock.lan, wordclock.home or wordclock.local, but this mostly depends on your router so your mileage may vary).

When you want to access the Config Portal of the clock via a home WiFi network from your web browser, a login prompt will be displayed, where you need to enter:

You will then land on the same configuration interface as seen in Access Pont mode.

Security notes connecting from WiFi network

The clock currently doesn’t support SSL. To make things a bit more secure and avoid compromission, you can:

API

The API is disabled by default because it is not secured. It was created to allow the Paint web interface to work, but could be used directly as well.

When enabled, the following routes are activated:

MQTT client

MQTT is a lightweight publish-subscribe protocol designed for resource-constrained devices and low-bandwidth networks, commonly used in IoT applications. MQTT clients talk via an MQTT broker (see here for Home Assistant instructions).

The clock’s MQTT client can be enabled and configured from the web UI. Note that the clock will reboot after changing any setting if MQTT is enabled.

Topics are prefixed with the name defined as Clock name in the web UI settings (but converted to lowercase and with spaces removed). The default prefix is therefore wordclock.

State topics

Command topics

Matrix paint (experimental)

Text scroller (experimental)

Home Assistant configuration

Below is an example configuration for Home Assistant using light and sensor MQTT integrations.

mqtt:
  - light:
      name: "Wordclock"
      availability_topic: "wordclock/availability"
      state_topic: "wordclock/light/switch"
      command_topic: "wordclock/light/switch/set"
      rgb_state_topic: "wordclock/light/color"
      rgb_command_topic: "wordclock/light/color/set"
      qos: 0
      optimistic: false
  - sensor:
      name: "Light sensor"
      availability_topic: "wordclock/availability"
      state_topic: "wordclock/sensor/ldr"

Entities can then be arranged in a dashboard card like this one:

(the icon used for the button is mdi:apps-box)

Paint

Note: This is an experimental feature. Payload format, palette and APIs might change.

When the API toggle is enabled, a web interface becomes available at http://<clock ip>/paint.

It is a basic real time drawing tool that allows you to take control of the clock’s LED matrix. While it is fun to just play with, it is meant to easily create custom icons to be used in a home automation setup.

To keep thing simple, the system works with 16 preset colors based on the original 4-bit palette of the 1987 Macintosh II:

0 — white 1 — yellow 2 — orange 3 — red 4 — magenta 5 — purple 6 — blue 7 — cyan
8 — green 9 — dark green a — brown b — tan c — light grey d — medium grey e — dark grey f — black

Source: Wikipedia

Other buttons:

Payload format

At the bottom of the page, a text version of the image payload is displayed, so it can be copied and used in direct MQTT or HTTP GET calls, for example to be used in home automation scenarios.

The payload is a string of 110 characters, one for each LED/pixel in the 11x10 matrix, starting from the top left corner. Allowed values are:

Text scroller

Note: This is an experimental feature. Parameters might change.

This feature scrolls a text on the display (only ASCII characters are supported) then goes back to displaying the time (demo video). It accepts a string of any length between 1 and 200 characters.

It can be used from the API and from MQTT. Both options support the same parameters.

Parameters

The feature supports a few optional parameters:

API

When the API endpoint is enabled in the settings, you can hit http://<clock IP>/api/text/set/<custom text> and pass the optional settings as query parameters. For example to scroll the message Hello from API :) in red color, scrolling backwards with 100ms delay, you’d do:

http://<clock IP>/api/text/set/Hello%20from%20API%20%3A)?color=3&delay=100&rtl=1

Note: the API endpoint can handle URI-encoded characters.

MQTT topic

The MQTT command topic is wordclock/light/text/set and its paylod is expected to be a JSON string containing the text value to scroll alongside any supported optional parameters. For example:

{"text":"Hello from MQTT :)","color":"3","delay":100,"rtl":1}

Credits

Parts of this page are inspired from the template manual provided by IotWebConf.

This site is open source. Improve this page.