# IDEA.md – an e-ink info board of your own This is a self-contained brief. Give it in full to Claude Code (or a similar tool) to build an implementation of your own. It draws on Paper Mono, apps of my own for M5Stack's Paper Mono e-ink card, designed in Claude Design and built with Claude Code. ## 1. What to build A small info board at home on a battery-powered e-ink card: clock, weather, departures, shopping list and more apps on a screen that draws little power and is always visible. Three parts: - **The program on the card** (Arduino/C++): fetches what to show, draws, sleeps. The clock ticks locally. An app picker on the card. - **A hub** (server): fetches and simplifies data – weather, departures, calendar, news – and gives each card its app, settings and data. - **An admin** (web): choose the app and configure each card, with a preview that is exactly what the card shows. Apps in Paper Mono: clock (with egg timer), shopping list, weather, calendar (ICS), departures, message board, news (RSS), countdown, guest Wi-Fi with a QR code, sun and moon, and messages between cards over LoRa radio. **Not**: over-the-air firmware updates, multiple users with roles. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **The card**: M5Stack Paper Mono (ESP32-S3, 8 MB PSRAM, 480 × 800 e-ink with four grey levels, touch screen, battery). The Arduino core and M5Unified/M5GFX. Compile and upload with `arduino-cli`. - **Important: a portable drawing core in C++** that draws every app into a 1-bit buffer and is compiled three ways: for the card, to **WebAssembly** for the admin's preview, and for the PC for tests. The same code gives the same pixels. No Arduino code in the core. - **The core's input is JSON**: app, variant, status, battery, time, time zone and the app's data. Demo data belongs on the server, not in the core. - **The hub**: PHP and MariaDB. The card fetches its state with ETag/304, so nothing is sent when nothing has changed. The hub fetches from the weather service, the transit API, ICS and RSS and caches. - **The admin**: React and Vite, with the core as WebAssembly for every preview. No external requests – the fonts are local. ## 3. Decisions that turned out to matter **Design first, with a reference renderer.** Let the design tool draw the screens with a renderer in JavaScript, and port it line by line to C++. Mimic JavaScript exactly: coordinates as `double`, rounding like `Math.round`, integer conversion like `|0`, text counted in characters, stable sorting. **A ground truth from the design.** Run the design's renderer in a real browser and save exact image buffers for every screen (65 in Paper Mono). The core must get all of them right, both on the PC and as WebAssembly, after every change. Fonts and icons are generated from the same export. **The card light-sleeps between fetches**, and the clock is drawn from the card's own clock. How often the card fetches is chosen per card in the admin. **No secrets in the program.** The same program on every card: the card generates its own key and is paired by comparing a code on its screen in the admin. Wi-Fi and the hub's address are set from a phone via a QR code and a portal on the card. **The battery is visible.** An hourly log, estimated battery life per app, the LED shows the level, and an email with a picture of the screen when it's time to charge. ## 4. Pitfalls - **Always draw inside a transaction** (`startWrite()`/`endWrite()`). Otherwise the graphics library refreshes the e-ink screen after every draw call, and an image with ten parts flashes ten times. - **The touch screen may be rotated.** In M5GFX 0.2.30 the touch coordinates are converted although they already match the image. Fix it after `M5.begin()`, and test the touch screen after every library update. - **Startup takes 14.5 s with default settings** – three full clears of the screen. With `clear_display = false` and the fastest mode for the first image it takes 4 s. - **Choose the refresh mode by purpose**: the quality mode (3.45 s, flashes) now and then to clear ghosting, the fastest mode (79–167 ms) for interaction. - **The serial port seems dead** at first because startup takes so long, and `arduino-cli monitor` writes nothing from WSL. Read the port another way (for example via PowerShell in UTF-8) and wait longer. - **Test sleep and battery without the USB cable.** With the cable in, the ESP32-S3 sometimes never wakes from light sleep. - **Fonts without å, ä, ö.** Check that the font has the characters you need. - **Don't use names like `min`, `max` or `PI` in the core** – they're macros on the card. - **Under WSL, file changes on a Windows drive aren't watched.** Let the dev server poll. ## 5. Requirements and measurements - From startup to the first image: around 4 s. - Awake around 2 s per fetch (Wi-Fi about 1.1 s, HTTPS about 0.6 s). - Battery: a stable 10–11 days per charge in the latest measurements; the goal is 14 days. - Ground truth: every screen right, 0 errors. ## 6. How it's verified - The core's ground-truth test on the PC and as WebAssembly after every change to the core. - Compiling and uploading to the card, and a human trying it on the card. - Measurements on the hardware for sleep, time awake and battery – without the cable. - The admin in a real browser. ## 7. Way of working - **Phases**: first a spike that tests the plan's biggest uncertainty on the hardware (light sleep, Wi-Fi, HTTPS, battery), then the drawing core, the server and the firmware client, the admin, the apps and deployment. - **Write the lessons about the hardware and the libraries down** in the project's instructions, so they aren't discovered again. - **One task at a time**, with the measurement in the closing comment. ## 8. The prompt > Build an info board for [M5Stack Paper Mono] with [clock, weather, departures and shopping list]: a program on the card that fetches, draws and sleeps, a hub in [PHP and MariaDB] that fetches the data, and an admin in [React] with a preview that is exactly what the card shows. > > Read all of IDEA.md below first. > > Work like this: > 1. Start with a spike on the hardware: light sleep, Wi-Fi, HTTPS and battery. Measure before anything else is built. > 2. Write a portable drawing core in C++ that compiles for the card, to WebAssembly and for the PC, and test it against a ground truth. > 3. Let me try it on the card, and write down every lesson about the hardware. > > [paste IDEA.md here]