Skip to content
theAndreasPublic

About

Wortuhr / word clock firmware for ESP32-S3, RP2350 and AVR128DA48: 11x10 German letter grid, WS2812 LEDs, web panel and console over WiFi, OTA updates, NTP time, automatic brightness — plus a desktop simulator that runs the entire firmware on a PC.

Topics

Resources

Stars

1 star

Watchers

2 watching

Forks

Latest commit

 

History

953 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wordclock — a German word clock (Wortuhr)

CI static analysis Wordclock Last commit Contributors

Platforms C++17 CMake PlatformIO Code size License

A word clock based on Arduino — a Wortuhr, which is what the German builds of this idea are called: an 11×10 grid of letters that spells out the time in German ("ES IST FÜNF NACH ZEHN"), with animations, overlays (date, temperature, text) and a serial command interface.

The same firmware drives WS2812 LEDs from an ESP32-S3, a Raspberry Pi Pico 2 W (RP2350) or an AVR128DA48, and on the first two a phone configures it over WiFi: two pages the clock serves itself, NTP time with a time zone, automatic brightness from a light sensor, and firmware updates over the air.

The simulator window, showing 16:20 as "ES IST ZEHN VOR HALB FÜNF"

The whole firmware runs on a PC as well: the simulator draws the matrix in a window and routes the serial interface to the text boxes beside it, so commands can be sent and answers read without any hardware. Above it shows 16:20, which German says as zehn vor halb fünf — ten before half five, the kind of wording the word tables have to cover.

What it does

  • Time in words — an 11×10 German letter matrix, driven from a font table the clock reads at runtime.
  • Boards — ESP32-S3, Raspberry Pi Pico 2 W (RP2350), AVR128DA48: one firmware, one core, three backends.
  • LEDs — WS2812 / NeoPixel, shaped by the RMT peripheral on the ESP32 and by the CCL on the AVR.
  • Configuration — a web panel and a command console the clock serves itself over WiFi, and the same commands over the serial port.
  • Time source — NTP with a time zone on the networked boards, a DS3231 on the AVR.
  • Brightness — automatic, from a BH1750 light sensor, with a night switch.
  • Updates — over the air, from the panel, on the networked boards.
  • No hardware needed — the simulator runs the whole firmware on a PC and serves the same pages a clock does.

Auf Deutsch

Eine Wortuhr, die die Zeit in deutschen Worten anzeigt — 11×10 Buchstaben, WS2812-LEDs, Konfiguration per Handy über WLAN, Update over the air. Die Firmware läuft auf ESP32-S3, Raspberry Pi Pico 2 W und AVR128DA48, und ohne Hardware im Simulator auf dem PC. Die Dokumentation ist englisch, die Uhr spricht deutsch.

Repository layout

Directory Purpose
src/ Single source of truth for the clock logic — platform-agnostic (animations, clock, display, scheduler, overlays, communication).
test/ The regression tests of the core, built against the simulator's backend and run without a display, and the fuzzers of the two ways data from outside reaches it.
docs/ Reference documentation: the serial command reference, the font tables, the roadmap of what is still open, the comparison with the other published word clocks, the measured decisions and how the code is documented.
assets/ The icon's SVG masters and the script that generates the .ico, the .xpm and docs/images/logo.png from them.
web/ The two pages a networked clock serves: the panel at / for what is changed often, the console at /console for every command. Compiled into the firmware by platform/scripts/embed_web.py — the clock has nowhere to fetch anything from. See its README.
platform/simulator/ wxWidgets desktop backend: renders the matrix in a window so the firmware can be developed and debugged on a PC.
platform/esp32/ On-device backend: WS2812 over the RMT peripheral, time from NTP. Built with PlatformIO — see its README.
platform/rp2350/ On-device backend for the Raspberry Pi Pico 2 W, derived from the ESP32 one. Built with PlatformIO — see its README.
platform/arduino/ What the two Arduino backends share: the real-time clock on the system clock, and the BH1750 and DS3231 drivers, written once against Wire. Each backend opens the bus its core's way in its own I2cBus.cpp.
platform/avr-dx/ On-device backend for the AVR128DA48: WS2812 shaped by the CCL, time from a DS3231. Built with CMake and a cross toolchain file — see its README.
tools/ documented-sizes.py, which compares every size this repository claims against a build and fails the pull request that made one stale; beside it the template's scripts, tidy.sh, self_contained_headers.py, coverage.sh and fuzz.sh among them, which tools/project.sh tells what Wordclock is.

The tool that generates the bitmap font tables lives in its own repository, theAndreas/FontCreator — see docs/fonts.md for the table format and how to regenerate one.

Architecture

The firmware core reaches the hardware only through header names (Arduino.h, Pixels.h, RealTimeClock.h, BH1750.h, DS3231.h, Storage.h, System.h, PowerSwitch.h), resolved via the include path. Each platform under platform/ supplies those headers with its own implementation — a compile-time swap with no runtime cost. See platform/avr-dx/README.md for the contract.

Building

The quickest way needs nothing installed but VS Code: open the repository, run Dev Containers: Reopen in Container and pick the configuration matching the host — Linux/X11 on native Linux, WSL2/WSLg when VS Code runs in WSL2. The container brings the toolchain and wxWidgets, CMake configures on open, and the WSLg configuration forwards the GUI to the Windows desktop without an extra X server. See .devcontainer/README.md for what the configurations share, how to add a site-specific one on an internal base image, and why changing the shared settings needs a container rebuild.

Without a container the same works, through the presets of CMakePresets.json - one per platform and kind of build, and what CI calls as well:

cmake --workflow --preset default      # configure, build, test - into build/host/
./build/host/bin/Wordclock
cmake --list-presets=all               # avr, clang, sanitize, coverage, fuzz, ci-*

Or through the Makefile, which is the index over the presets and everything that is not CMake: make lists every target, make tests is the line above, make run starts the window, and make check is everything CI runs.

That way requires CMake ≥ 3.25 for the presets, Ninja, a C++17 compiler and wxWidgets 3.x (GTK on Linux). Without the presets the platform is the PLATFORM switch, -DPLATFORM=simulator by default. See the simulator README for details.

The on-device platforms are not built with CMake. The esp32 and rp2350 platforms use PlatformIO:

pio run -t upload -d platform/esp32
pio device monitor -d platform/esp32

pio run -t upload -d platform/rp2350     # hold BOOTSEL on the first upload

The avr-dx platform uses the same CMake, but cross-compiles — so its toolchain has to be named when the build directory is created, because a compiler cannot be swapped afterwards. Its preset does that, which is the way to flash it, and its test is the documented sizes against the image just built; make stack adds up its stack:

cmake --workflow --preset avr          # into build-avr/
cmake --build --preset avr --target flash

The two web pages

The pages in web/ need a clock behind them to show anything, and the simulator is one: it serves them itself, on localhost, from the binary that draws the window.

cmake --build --preset default && ./build/host/bin/Wordclock     # http://localhost:8080/

The panel is at / and the console at /console, answered out of the same WebFrontend a clock answers them from — so what the browser sees is what a clock would send, with no board and no second process. The window and the browser then show the same clock, which is worth more than either alone: the window is colour-accurate, the pages are what somebody actually uses.

/update is answered too, and honestly: nothing is installed, because a desktop has no second partition — what it stands in for is the panel's progress and its two outcomes, which is the part of that card nothing else can reach without a board.

There used to be a second way, platform/esp32/test/run.sh serve, which put node in front of a host build of the ESP32 backend. It is gone: node did all the HTTP and the web socket there, so what it exercised was the pages and the firmware core — exactly what the simulator now does with one binary and a real server.

Checks

Every pull request runs three workflows, and the three badges above say separately whether the code builds, whether it reads clean, and whether what only Wordclock has works. The first two are the template's, as copier update keeps them; the third is Wordclock's own.

.github/workflows/ci.yml builds and tests:

Job make What it does
Lint lint The template's tools/lint.sh: clang-format and the indentation of the Doxygen blocks, cpplint with what CPPLINT.cfg filters and why, shellcheck over every shell script, ruff over every Python one and actionlint over the workflows. make fmt formats in place
Host tests tests, sanitize, coverage The simulator and the core tests with -Werror; again under AddressSanitizer and UndefinedBehaviorSanitizer; and with --coverage, with both backends' host suites through coverage_suites() of tools/project.sh, failing below its COVERAGE_MINIMUM of lines, branches and conditions
Host tests by clang clang The simulator and the core tests compiled by clang, which warns about other things
Examples examples, stack The image of every target of tools/project.sh - the AVR128DA48's by CMake, the ESP32-S3's and the RP2350's by PlatformIO - failing on a warning in Wordclock's own files; and the AVR's deepest stack against the RAM it leaves free, out of the call graph its link writes

.github/workflows/static-analysis.yml reads the code rather than building it:

Job make What it does
clang-tidy tidy The template's tools/tidy.sh: each target through its own compile database, then the tests with the simulator, then the fuzzers. Which checks and why the others are off is in .clang-tidy
cppcheck cppcheck Parses src/ by itself, which is what reaches the template instantiations and container bounds the clang checks do not follow. Its two suppressions and their reasons are in .cppcheck-suppressions
Headers on their own headers Every header of src/ and platform/ compiled on its own, by each target's compiler and the host's, through tools/self_contained_headers.py
Fuzzers fuzz libFuzzer, under the same two sanitizers, over the two ways data from outside reaches the firmware: a command line as a browser's web socket frame brings it, and a stored settings blob. Three minutes each per pull request, from the corpus the runs before left in the cache. The fuzzers are in test/fuzz/, their options beside them

.github/workflows/wordclock.yml is what the template's targets do not reach, its targets in tools/project.mk:

Job make What it does
Web pages in a browser web tools/web-smoke.py: the panel and the console in Chromium against the simulator, at 390 and 1280 px — no console error, nothing wider than the window, a command typed in the console answered
The backends' host suites host-esp32, host-rp2350, host-clang, host-sanitize, tidy-host-suites platform/esp32/test/run.sh and platform/rp2350/test/run.sh — each backend against the stand-ins in its test/stubs, no board needed — by g++, by clang and under the sanitizers, and their names through the database run.sh compiledb writes
Web page linters web-lint html-validate over both pages as whole documents and eslint over the scripts inline in them, at the versions package-lock.json pins. What each checks and leaves out is in .htmlvalidate.mjs and eslint.config.mjs
Doxygen blocks docs The template's tools/docs.sh, once per backend: a block Doxygen cannot read, a parameter without its \param, an entity without a block
Firmware examples, documented-sizes Every target's image again, every size the documentation states against them through tools/documented-sizes.py, and the images kept: the .hex and .elf of the AVR, the ESP32-S3's update and factory images, the RP2350's .uf2 and update image. release.yml publishes them for a tag

A firmware build looks redundant next to the host tests and is not: those compile the same sources with the host's compiler and libc, so anything the target's toolchain has a different opinion about passes them. timegm, which newlib does not declare, broke the firmware while every host test stayed green. That argument carries furthest for the AVR, an 8-bit freestanding target with more opinions than either of the others.

Each job is a target of the Makefile, the template's, or of tools/project.mk, Wordclock's own, and the workflows run nothing else, so the column above is also what to type before pushing. Nothing in them needs a display, a board, or anything the dev container does not carry:

make lint                     # clang-format, cpplint, the scripts: seconds, no build
make tidy                     # clang-tidy over every target, the tests and the fuzzers
make check                    # every job of the three workflows, warnings as errors
make fuzz FUZZ_SECONDS=300    # longer than the three minutes a pull request gets

The fuzzers go on from the corpus the run before left in build/fuzz/work.

License

GPL-3.0-or-later — Copyright (c) 2017-2026 Andreas Burnickl, the licence of Utl and MaxMatrix as well. The dependencies the firmware links against keep their own licences, and each of them may be combined with the GPL: the Arduino cores are LGPL-2.1, ESPAsyncWebServer is LGPL-3.0-or-later and wxWidgets carries the wxWindows Licence. None of them is redistributed here; PlatformIO and CMake fetch them at build time. A release carries the source of its tag beside the firmware, as GitHub attaches it to every release.

About

Wortuhr / word clock firmware for ESP32-S3, RP2350 and AVR128DA48: 11x10 German letter grid, WS2812 LEDs, web panel and console over WiFi, OTA updates, NTP time, automatic brightness — plus a desktop simulator that runs the entire firmware on a PC.

Topics

Resources

Stars

1 star

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages