Development EN

🇩🇪 Deutsch | 🇬🇧 English

Development

Pull requests for new languages, front layouts or bug fixes are welcome.

Project structure

Folder	Contents
src/, include/	Firmware. src/WordClock.cpp is the entry point
include/WordClockTypes/	one header per front layout
include/Render/	Colour and transition stages of the display
webpage/	Web interface (HTML, CSS, JavaScript, language files), minified with Grunt during the build and embedded into the firmware
test/	Host tests without PlatformIO
svg/, 3D_Model/	Templates for fronts and housings
docs/	Manual as LaTeX/PDF

Build and test

npm ci                 # once, for building the web interface
pio run                # all three environments, like the CI
pio run -e ESP8266     # only one environment
bash test/run.sh       # host tests with address and UB sanitizer

Code formatting

The project uses clang-format with the configuration in .clang-format. The CI checks with clang-format 11; newer versions format some places differently.

clang-format -i $(git ls-files '*.h' '*.hpp' '*.cpp' '*.ino')

CI

Workflow	Checks
PlatformIO CI	Build for ESP8266, ESP32 and ESP32-C3
Run clang-format Linter	Formatting
Nightly Firmware	Daily build with firmware artifacts

All three must be green before a PR is merged.

New front layout

1. Put the layout file as .hpp into include/WordClockTypes/. The build includes all files there automatically via include/ClockType.gen.h. At the end of the file is the instance, e.g. De10x11Alternative_t _de10x11Alternative;.
2. Add the layout to CLOCK_TYPES_LIST in include/WordClockState.h:

   X(Ger10x11Alternative, 13, _de10x11Alternative, "de-10-11-alt")

   The parameters are the name of the enumeration, a unique ID (next free number), the name of the instance and the i18n key. The list is grouped by language.
3. Add the display name under the i18n key in webpage/language/*.js in the section view.front. The selection list of the web interface is generated automatically.
4. Generate the front plate with python3 svg/createFrontSVG.py <Name>, see Front layouts.
5. Optionally add a commented-out DEFAULT_LAYOUT line in include/Config.h and list the language in Front layouts.

Releases

A release contains one .bin per chip (ESP8266_V<Version>.bin, ESP32_…, ESP32C3_…) and SHA256SUMS. The changes are in CHANGELOG.md; the release text is the section of the respective version.