Say "Wortuhr" where somebody searching for one can read it

README.md

@@ -1,4 +1,4 @@
-# Wordclock
+# Wordclock — a German word clock (Wortuhr)
 
 [![CI](https://img.shields.io/github/actions/workflow/status/AndreasBur/Wordclock/ci.yml?branch=master&label=CI&logo=github)](https://github.com/AndreasBur/Wordclock/actions/workflows/ci.yml)
 [![static analysis](https://img.shields.io/github/actions/workflow/status/AndreasBur/Wordclock/static-analysis.yml?branch=master&label=static%20analysis&logo=github)](https://github.com/AndreasBur/Wordclock/actions/workflows/static-analysis.yml)
@@ -12,9 +12,15 @@
 ![Code size](https://img.shields.io/github/languages/code-size/AndreasBur/Wordclock)
 [![License](https://img.shields.io/github/license/AndreasBur/Wordclock)](LICENSE)
 
-A word clock based on Arduino: 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.
+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"](docs/images/simulator.png)
 
@@ -24,6 +30,27 @@ 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, plus 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 |
+
+## 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 |

docs/_config.yml

@@ -0,0 +1,15 @@
+# GitHub Pages serves this directory as the project site. The theme is the one
+# GitHub hosts itself: a remote_theme would need a Gemfile and a build step, and
+# nothing here wants a Ruby toolchain in the repository.
+theme: jekyll-theme-primer
+
+title: Wordclock — a German word clock (Wortuhr)
+description: >-
+  Word clock firmware for ESP32-S3, RP2350 and AVR128DA48. An 11x10 German
+  letter grid on WS2812 LEDs, configured from a phone over WiFi, with NTP time,
+  automatic brightness and updates over the air.
+
+# The pages under images/ are assets, not documents, and the repository's own
+# READMEs are reached through GitHub rather than through the site.
+exclude:
+  - README.md

docs/index.md

@@ -0,0 +1,30 @@
+# Wordclock — a German word clock (Wortuhr)
+
+A word clock that spells the time out in German words: an 11×10 grid of letters
+on WS2812 LEDs, driven by one firmware that runs on an ESP32-S3, a Raspberry Pi
+Pico 2 W (RP2350), an AVR128DA48 — and on a PC, where a simulator draws the
+matrix in a window so the clock can be built and debugged without hardware.
+
+![The simulator window, showing 16:20 as "ES IST ZEHN VOR HALB FÜNF"](images/simulator.png)
+
+The window above 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.
+
+## Reference
+
+- [Serial command reference](serial-commands.md) — every command the clock
+  answers, over the serial port and over the web console alike.
+- [Fonts](fonts.md) — the bitmap font table format, and how to regenerate one.
+- [Roadmap](roadmap.md) — what is planned, why, and what each item touches.
+
+## Auf Deutsch
+
+Eine Wortuhr, die die Zeit in deutschen Worten anzeigt: 11×10 Buchstaben,
+WS2812-LEDs, Konfiguration per Handy über WLAN, Zeit über NTP, automatische
+Helligkeit und Update over the air. Die Firmware läuft auf ESP32-S3, Raspberry
+Pi Pico 2 W und AVR128DA48 — und im Simulator auf dem PC, ganz ohne Hardware.
+
+## The code
+
+The firmware, the three hardware backends, the simulator and the build
+instructions are on GitHub: [AndreasBur/Wordclock](https://github.com/AndreasBur/Wordclock).