# How it works

[← Back to the README](../README.md)

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](../src/esp32/README.md#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](web-ui.md#schedule) 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](home-assistant.md).
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](../src/nano/README.md).