Skip to content

Installation EN

Jump to bottom
David Panusch edited this page Oct 27, 2026 · 1 revision

🇩🇪 Deutsch | 🇬🇧 English

Installation

There are two ways to get a finished clock:

  • Compile it yourself: This is the only way to adapt the clock to your layout, language and hardware via Configuration (include/Config.h). For most builds this is the right way.
  • Flash pre-built firmware: faster, but with a default configuration compiled in.

Many USB boards (NodeMCU, Wemos D1 Mini) need a driver for CH340 or CP210x. Use a data cable for flashing, not a charge-only cable.

Compile it yourself

You need PlatformIO (Core or IDE), Node.js and Git. Node.js is needed to build the web interface.

The environments in platformio.ini are called ESP8266, ESP32 and ESP32C3.

Windows (VS Code)

  1. Install PlatformIO IDE (it brings Visual Studio Code along), plus Node.js and Git.
  2. A PlatformIO icon (an ant head) appears on the left in VS Code.
  3. Choose Quick Access → Miscellaneous → Clone Git Project and enter https://github.com/ESPWortuhr/Multilayout-ESP-Wordclock.
  4. Under Projects, add the project with Add Existing and open it.
  5. Connect the ESP via USB. Under Project Tasks, expand the matching environment and choose General → Upload.

The first build takes a few minutes because PlatformIO downloads all libraries. In the end, SUCCESS appears.

macOS

brew install platformio node
git clone https://github.com/ESPWortuhr/Multilayout-ESP-Wordclock.git
cd Multilayout-ESP-Wordclock
pio run -e ESP8266 -t upload

Linux

python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)"
sudo apt install npm git
git clone https://github.com/ESPWortuhr/Multilayout-ESP-Wordclock.git
cd Multilayout-ESP-Wordclock
pio run -e ESP8266 -t upload

To access the serial port, add your user to the dialout group (sudo usermod -a -G dialout $USER) and log in again.

Pre-built firmware

The releases page has one file per chip, e.g. ESP8266_V5.0.0.bin, plus SHA256SUMS for verification.

Default configuration: German layout Ger10x11Alternative, GRB LEDs, RTC DS3231, I2C off. Layout, LED type and much more can then be changed in the web interface. A different RTC (e.g. DS1307) or Wi-Fi credentials compiled in require your own build.

Update over Wi-Fi (OTA)

If the clock is already running firmware, the update works without a cable:

  1. Open http://<clock-IP>:81/update (port 81).
  2. Select the .bin file and upload it.
  3. The clock restarts. Settings are kept, unless the changelog announces a reset (when switching from 4.x to 5.x).

If WEB_PROTECTED is active, the update page asks for WEB_USER and WEB_PASSWORD.

Serial flashing with esptool

For a new board or a clock that no longer starts. Prerequisite: pip install esptool.

# ESP8266 (NodeMCU, Wemos D1 Mini)
esptool.py --chip esp8266 --port /dev/ttyUSB0 write_flash 0x0 ESP8266_V5.0.0.bin

# ESP32 and ESP32-C3: the file contains only the application
esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash 0x10000 ESP32_V5.0.0.bin

On Windows the port is called COM3 or similar, on macOS /dev/cu.usbserial-*.

Flashing in the browser

Tool Note
esptool-js Official browser version from Espressif, enter file and offset by hand
esp.huhn.me Simpler interface, also with a free offset

The same offsets apply as with esptool. Web Serial only works in Chromium browsers (Chrome, Edge, Opera) over HTTPS. Close all serial monitors beforehand.

Blank ESP32 or ESP32-C3

The offset 0x10000 writes only the application. A completely blank chip additionally needs the bootloader (0x1000, on the ESP32-C3 0x0) and the partition table (0x8000). These files are not part of the release. In that case flash once with pio run -e ESP32 -t upload; after that, updates work over Wi-Fi.

Nightly builds

For every state of main, Actions → Nightly Firmware builds the firmware for all three chips. Under Artifacts of the latest successful run you find firmware-ESP8266, firmware-ESP32 and firmware-ESP32C3.

  • The archive contains the .bin (<Chip>_V<Version>_<Commit>.bin), a .sha256 checksum and the .elf for resolving crash backtraces.
  • Download only with a GitHub login, deleted after 14 days.
  • Untested development snapshots. For a stable clock, use the release.

Switching from 4.x to 5.0.0

The update resets all settings to default values. Note down hardware pins, MQTT, OpenWeatherMap and layout beforehand. The “Corners” minute variant no longer exists; the 11 × 11 layouts use the normal minute LEDs.

Next: Setup

🇩🇪 Deutsch

🇬🇧 English

Repository · Releases

Clone this wiki locally