epaper-countdown

A small desk device that counts down to upcoming events on a 4.2" e-paper screen. Events are added and edited from a built-in web page. It runs on USB power and keeps time over Wi-Fi (NTP), with a battery-backed real-time clock so the countdowns stay correct through outages.

Hardware

• ESP32 Feather V2 (Adafruit 5400)
• eInk Feather Friend (Adafruit 4446)
• 4.2" 400x300 mono e-paper, SSD1683 / Good Display GDEY042T81 (Adafruit 6381)
• DS3231 RTC over STEMMA QT, with a CR1220 coin cell
• Panel-mount momentary button

The Feather and Friend socket together. The button and the panel's BUSY line are soldered to the Friend's header pads. Wiring and the exact GPIO map are in docs/pinmap.md.

How it works

The screen shows the soonest events. One event gets a large layout; two to four share a list. The event happening today is shown on an inverted bar. Up to 16 events are stored on the device; the web page manages all of them and the panel shows the nearest four.

Time comes from NTP and is mirrored to the RTC every few hours. If Wi-Fi drops, the device keeps counting from the RTC, shows an OFFLINE marker, and reconnects on its own when the network returns.

The button: a short press repaints the screen, a ~2 second hold clears the saved Wi-Fi and reboots into setup.

Build and flash

PlatformIO. From firmware/:

pio run -t upload      # build and flash the firmware
pio run -t uploadfs    # upload the web page to the device
pio device monitor     # serial log at 115200

Two build environments:

• adafruit_feather_esp32_v2 (default) drives the real panel.
• headless prints the layout to the serial monitor instead, for working without a panel attached.

First-time setup

On first boot with no saved Wi-Fi, the panel shows a QR code. Scan it with a phone to join the device's setup network, then pick your Wi-Fi and enter the password on the page that opens. The device reboots and joins.

After that it is reachable at http://countdown.local.

Layout

firmware/    PlatformIO project (ESP32 Feather V2)
  include/   config.h: pins, time zone, hostname, version
  src/       main + modules (store, timekeeper, provisioning, web, display)
  data/      web page and seed events, uploaded to the device filesystem
docs/        design notes, bill of materials, pin map
enclosure/   3D model and build notes

Notes

The web page (firmware/data/index.html) is one self-contained file with no external dependencies, so it loads on a LAN with no internet. Events are stored in NVS, not the filesystem, so uploading a new web page does not erase them.

Firmware and the web page are versioned separately. The device shows both versions in its settings menu. Time zone is set in config.h (currently America/New_York).

License

Firmware, web UI, and documentation are under the MIT License (LICENSE). The enclosure design files in enclosure/ are under Creative Commons Attribution 4.0 (CC BY 4.0); see enclosure/LICENSE.

Acknowledgments

The firmware and web interface were written by Claude Code, Anthropic's command-line coding agent, working under my direction. I set the requirements, made the design and hardware decisions, and did the soldering, assembly, and testing on the physical device; the agent wrote and revised the code as I reviewed the results on real hardware. Commits authored by the agent carry a Co-Authored-By line. The commit history was squashed to a single starting point before this repo was made public, so it does not reflect the original step-by-step development.