Flipdot-display/docs/recovery.md

Recovery app

← Back to the README

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.

1. Connect the ESP32 over USB (COM11, see platformio.ini).
2. Erase the flash and install the recovery app:

   pio run -e recovery -t erase
   pio run -e recovery -t upload
   

   The recovery app starts (LED double-blinks, the display shows Recovery / no firmware), connects to the WiFi from secrets.h and shows its IP address. It waits there, because there is no clock firmware yet.
3. Install the clock firmware over WiFi. This also tests that the recovery app works:

   pio run -e esp32 -t upload
   

4. Check Home Assistant: the FlipDot Display Firmware sensor should show 2.1.0, testing, ..., and after a minute 2.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.