Files
Flipdot-display/docs/how-it-works.md
T
mangavalkandClaude Opus 5.5 a91d2550d7 Game of Life page element and built-in page
A new page element runs Conway's Game of Life in an area (the whole display
by default), one per page. Start: random dots, one pattern, or the icons
whose names start with a text in turn or in random order. Edges: wrap
around, dead, or a hidden margin where gliders fly out of view (leftovers
that stay put in the margin are cleared, so a glider gun runs cleanly).
It restarts when the board is still or repeats within 16 generations
and/or after a number of generations, after a hold time (an empty board
at once).

logic/life holds the board and timing (tested), display/life_player runs
the board of the shown page, ticked before each frame; frames are paced
like scrolling text. The element reuses existing fields, so the page
format stays the same. The Icons tab has a library of 17 LifeWiki
patterns (checked with a simulation), and the built-in page "Game of
Life" shuffles through the life_ icons. About 12 KB flash, 8 KB RAM.

Version 2.17.0, tested on the display over OTA.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 17:52:25 +02:00

3.0 KiB
Raw Blame History

How it works

← Back to the README

  1. ESP32 boot. The ESP32 connects to WiFi and starts ArduinoOTA. After a crash it runs only OTA for 15 seconds, and after repeated crashes it goes to safe mode. Bad OTA firmware is rolled back automatically, see Keeping OTA alive. It then switches the display relay on, waits for the Nano's READY message (at most 3 s), shows "Connecting...", starts NTP and connects to MQTT.
  2. Clock. Once the time is synced, the ESP32 sends a new frame whenever the screen changes, mostly once a minute:
    • 08:00–23:30: the page: the chosen page (by default the built-in Clock page, Pikachu with a thought bubble showing HH:MM, yawning from 17:00), or what the schedule and rules pick.
    • Game of Life (a page element): the ESP32 runs the board (logic/life) and sends a frame per generation with only the changed dots. Like scrolling text, the next frame waits until the Nano has received and flipped the last one, so a busy board runs slower than the chosen speed. Only the shown page runs; it pauses while the display is off. Still or repeating boards are found by comparing a hash of the board with the last 16 generations. With the hidden margin, gliders that leave the area are cleared at the outer edge, and leftovers that stay put in the margin are cleared after 12 generations, so a glider gun keeps running cleanly.
    • Slow mode (a switch in Home Assistant and the web UI, for less noise): the display only changes every 1, 2, 5, 10, 15, 20, 30 or 60 minutes, on the clock (15 minutes = :00, :15, :30 and :45). 30 seconds after each update the relay turns the display off; the dots keep the image. Page changes wait for the next update too, except for rules with "show at once in slow mode": while their page is shown, the display works normally.
    • 23:31–08:00: the screen is cleared (or shows the off image chosen in the web UI) and power is cut after 30 seconds.
  3. Home Assistant: switches, dropdowns and sensors over MQTT, see Home Assistant.
  4. Nano. The Nano reads commands from the serial line and updates its frame buffer. On D it flips only the dots that changed, in small steps so it never stops reading the serial port. Every 2 minutes (Settings, "Dot refresh") it flips every dot once more to fix dots that did not flip.
  5. Frame check. After a frame the ESP asks the Nano for a checksum of its image and compares it with what it sent. When they differ (lost bytes can shift the picture), the Nano doesn't answer, or it restarted, the ESP sends the whole image again. It also does that every 10 minutes (Settings, "Image resync"); only dots that differ flip, so normally nothing changes. The counts are on the System tab.

The serial protocol is described in src/nano/README.md.