Skip to content

Latest commit

 

History

History
89 lines (56 loc) · 5.93 KB

README.md

File metadata and controls

89 lines (56 loc) · 5.93 KB
Raw

Software

This section of the Wordclock project covers the software running on the clock's ESP32. This page covers the basic features and how to build and deploy from source.

For detailed usage instructions, please refer to the User's Manual.

Features

  • Supports English, French, Italian and Dutch clock faces
  • Web interface over WiFi with captive portal for initial WiFi configuration (see User's manual for details)
  • Can use network time (NTP) or manual setting
  • Interface offers various other options such as display color, light sensor sensitivity, and OTA firmware update
  • MQTT client to control the clock via home automation platforms such as Home Assistant
  • Go beyond time display with text scrolling and an experimental web interface for real-time painting

Demo video

Here's a video showing the Wordclock with 1.0 firmware and its web interface in action. New features were added since, such as MQTT and Paint.

Release binaries

If you are not interested in modifying the source code, you can find prebuilt binaries here that can be flashed on your ESP32 with esptool.py or even directly from Chrome browser with esptool-js

Use the firmware_esp32dev files if you have a custom built clock based on the ESP32 Dev board, or the firmware_nodo files if you purchased a nodo clock kit (which is powered by an ESP32-C3 chip and has the LEDs laid out in a different order).

Flashing with esptool-js

  • Download the latest merged.bin firmware for your platform from the release page
  • Open esptool-js
  • Connect your ESP32 over USB
  • Click "Connect" and select the correct COM port
  • Click "Erase Flash" and let it do its thing
  • Set Flash Address to 0
  • Pick the file you downloaded
  • Click "Program" and wait for the operation to complete
  • Profit

Build with PlatformIO

This is the recommended method as it makes it easy to manage dependencies and build for a specific flavor of ESP32. If you do not want to use PlatformIO, see below for detailed instructions.

  1. Install PlatformIO and VS Code
  2. Load the project in VS Code (select the folder containing platformio.ini)
  3. Verify that the target board in platformio.ini matches your ESP32 hardware
  4. Build and upload

Important: Platform IO builds and flashes multiple bin files (bootloader, partition, firmware). To merge those into a single binary for flashing separately from e.g. esptool or the OTA updater, run pio run -t mergebin from a PlatformIO console and look for the file ending with "merged.bin" in the .pio/build folder.

OTA update

After the firwmare has been flashed over USB once, you can use the OTA feature to flash further updates: build the new binary file, then open the web portal of your clock, click the Firmware update link at the bottom and upload the new firmware.bin file. For OTA we don't use the "merged" version mentioned in the previous section.

  • Pre-built releases can be found here.
  • In PatformIO, the build file is located in .pio\build\<environment name>\firmware.bin.
  • If you are building with Arduino IDE, use Sketch > Export compiled Binary to export the file.

Warning: if the firmware config version displayed at the very bottom of the web interface changes, your settings will be reset. They should otherwise remain.

[Deprecated] Build with Arduino IDE

Note: this project now relies on PlatformIO features such as board-specific configurations and binary data embedding, and will therefore require changes in the code and project files to build with the Arduino IDE, which is why this section is considered deprecated.

Add ESP32 boards

If you want to use Arduino IDE only, you need to install the Arduino core for the ESP32. To do so, the preferred method is to use the Boards Manager and is detailed here.

Once installed, select the ESP32 board from Tools > Board > ESP32 Arduino > ESP32 Dev Module (or whatever is most appropriate for your specific board).

You will also need to rename the wordclock.cpp file to wordclock.ino.

Note: you might also need to install the appropriate USB driver for your ESP32 board (for example if it has a CP210x USB to UART bridge, it's this one).

Add required dependencies

This project relies on several additional libraries that need to be installed in the Arduino IDE. Open the Library Manager (Tools > Manage Libraries...), then search an add the following:

You are now ready to compile and flash the wordclock.ino sketch.

Credits

A large part of this source was based on the code from these two projects (both of which were written for the same hardware) with their explicit permission: