mangavalkandClaude Opus 5.5
58a7cb03c2
- README is the overview; web UI, pages, Home Assistant, how it works, wiring, Nano over WiFi and the recovery app have their own page in docs/. - docs/web-ui.md has a screenshot of every tab, made with headless Edge by tools/make_webui_screenshots.py. - The web UI opens a page in the editor with #pages/<name>. Version 2.7.2. - The reply wire is fitted (flashing the Nano over WiFi works). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.0 KiB
Recovery app
The ESP32 has a small second app, the recovery app (src/recovery). It has its own place on the flash and is never changed by OTA updates. It contains only WiFi, a setup web page and OTA, so the ESP32 can always be reached, even when the clock firmware is broken. It shows what is going on as a short message on the display, and the built-in LED double-blinks.
flash (4 MB): bootloader | nvs | otadata | factory: recovery | ota_0: clock | ota_1: clock | bitmaps
When it starts
| Trigger | Back to the clock |
|---|---|
| The clock firmware can't connect to WiFi (30 s at boot, or 10 min later on) | As soon as the WiFi works again (after at least 1 minute) |
| The clock firmware crashed 3 times in a row | After 10 minutes |
| FlipDot Display Recovery button in Home Assistant | After 10 minutes |
| Switching the power on and off 3 times, each time within 10 s | After 10 minutes |
| There is no working clock firmware (the bootloader falls back to it) | Never by itself |
The setup page can also start the clock right away, or keep the recovery app running ("Stay in recovery").
What the display shows
| Message | Meaning |
|---|---|
Connecting / to WiFi... |
The clock firmware is starting |
Getting / the time... |
Connected, waiting for the time from the internet (NTP) |
No WiFi / 12:34 |
The clock firmware lost WiFi for more than a minute; the time keeps running |
Crashed! / OTA open 15s |
The clock firmware crashed and waits 15 s for an OTA update before it starts again |
Crashed 3x / OTA only |
Repeated crashes without the recovery app installed: only OTA for 10 minutes |
Recovery / reason |
The recovery app started (no WiFi, crashed, requested, power cycled, no firmware) |
WiFi setup: / FlipDot-Setup |
Connect to this WiFi to choose another network, see below |
Recovery / IP address |
The recovery app is connected; open this address for the setup page |
The recovery app switches the display off after each message; the dots keep showing it without power.
WiFi setup. The recovery app keeps trying the stored WiFi. If that fails for 20 s, it
also opens its own WiFi: FlipDot-Setup, with the password SETUP_AP_PASSWORD from
src/esp32/secrets.h. Connect a phone to it; the setup page opens by itself (otherwise go
to http://192.168.4.1). Pick a network, enter the password and save. The new WiFi is
stored in the ESP32's NVS and used by both apps from then on (instead of WIFI_SSID from
secrets.h). The setup page is also reachable on your normal WiFi, at the ESP32's IP
address.
Updating the clock firmware from the recovery app. Upload as usual,
pio run -e esp32 -t upload. On the setup WiFi, add --upload-port 192.168.4.1. The
recovery app writes the firmware to ota_0 and starts it.
Updating the recovery app itself needs USB (pio run -e recovery -t upload). It
should rarely be necessary.
One-time installation (USB)
This changes the flash layout, so it can only be done over USB. It is the last USB flash the ESP32 needs. Best done together with the wiring TODOs, while the display is open anyway.
- Connect the ESP32 over USB (
COM11, seeplatformio.ini). - Erase the flash and install the recovery app:
The recovery app starts (LED double-blinks, the display shows
pio run -e recovery -t erase pio run -e recovery -t uploadRecovery/no firmware), connects to the WiFi fromsecrets.hand shows its IP address. It waits there, because there is no clock firmware yet. - Install the clock firmware over WiFi. This also tests that the recovery app works:
pio run -e esp32 -t upload - Check Home Assistant: the FlipDot Display Firmware sensor should show
2.1.0, testing, ..., and after a minute2.1.0, ok, 0 crashes, recovery ok.
Erasing the flash also clears the NVS: WiFi settings made on the setup page are reset to
the ones in secrets.h.