Eigene ESPHome-Firmware auf ein E-Paper HomeButtons-Display flashen
Wie ich die Original-Firmware gesichert, einen Boot-Crash beim ESP32-S2FH4 behoben und dynamische E-Paper-Dashboards mit ESPHome auf einem HomeButtons Original zum Laufen gebracht habe.
Ich habe ein HomeButtons Original (Hardware Rev 2.3) – ein schickes kleines Wandgerät mit physischen Tastern und einem 2,9-Zoll-E-Paper-Display von GoodDisplay (GDEY029T94, 296x128 Pixel, monochrom). Die mitgelieferte Firmware funktioniert für einfache MQTT-Tastendrücke ganz gut, aber ich wollte volle Kontrolle: eigene Layouts, die serverseitig in Home Assistant gerendert und dynamisch ans Display geschickt werden.
Also musste ESPHome drauf. Wie bei Custom-Hardware üblich, war das nicht ganz mit einem Klick erledigt – aber das Ergebnis läuft jetzt absolut stabil.
Schritt 1: Original-Firmware sichern
Bevor ich auf einem ESP32 irgendetwas überschreibe, ziehe ich immer ein komplettes Flash-Backup. Falls etwas schiefgeht, willst du einen Weg zurück haben. Um den ESP32-S2FH4 in den permanenten ROM-Bootloader-Modus zu bringen, hältst du die BOOT-Taste gedrückt (oder brückst GPIO0 auf GND), drückst RESET (oder steckst USB neu an) und lässt BOOT wieder los.
Danach habe ich mit esptool die kompletten 4 MB ausgelesen:
esptool --port /dev/ttyACM0 read-flash 0x0 0x400000 stock_firmware_backup_4mb.bin
Das dauert etwa 15–30 Sekunden und gibt dir ein komplettes Sicherheitsnetz.
Schritt 2: Der Boot-Crash beim ESP32-S2FH4
Hier bin ich am Anfang kurz gestolpert. Im HomeButtons Rev 2.3 steckt ein ESP32-S2FH4 (Single-Core, 4 MB interner Flash, kein externes PSRAM). Als ich einen Standard-ESPHome-Build mit esp-idf kompiliert und geflasht habe, wollte das Ding einfach nicht booten.
Der Grund war der Flash-Header: ESPHome hat in der firmware.factory.bin bei 0x1000 (Bootloader) und 0x10000 (App) jeweils 0x2f (80 MHz, 4 MB) in Byte 3 geschrieben – und genau das lässt den ESP32-S2FH4 abstürzen.
In der homebuttons.yaml habe ich deshalb in den sdkconfig_options explizit 40 MHz DIO erzwungen:
esp32:
board: esp32-s2-saola-1
variant: esp32s2
cpu_frequency: 80MHz
framework:
type: esp-idf
sdkconfig_options:
CONFIG_ESPTOOLPY_FLASHFREQ_40M: y
CONFIG_ESPTOOLPY_FLASHFREQ_80M: n
CONFIG_ESPTOOLPY_FLASHMODE_DIO: y
CONFIG_ESPTOOLPY_FLASHMODE_QIO: n
CONFIG_ESP_BROWNOUT_DET: n
Um ganz sicherzugehen, habe ich mir noch ein kleines Python-Skript (flash_with_header_patch.py) geschrieben, das Byte 3 an 0x1000 und 0x10000 vor dem Flashen auf 0x20 (40 MHz DIO) patcht:
for off in [0x1000, 0x10000]:
if data[off] == 0xe9:
print(f"Patching header at {hex(off)}: was {hex(data[off+3])} -> setting to 0x20 (40MHz DIO)")
data[off+3] = 0x20
Einmal gepatcht und geflasht, ist das Board sofort ins WLAN gekommen – und ab da funktionieren OTA-Updates ganz normal.
Schritt 3: Dynamische E-Paper-Bilder per HTTP
Statt Schriftarten und Zeichenlogik mühsam in ESPHomes C++-lambda zu pflegen, wollte ich lieber ein 296x128 Pixel großes 1-Bit-Monochrom-.bmp in Python/Home Assistant rendern und vom Display einfach abholen lassen.
Genau dafür gibt es in ESPHome die online_image-Komponente:
image:
- platform: online_image
url: "${image_url}"
id: remote_bitmap
format: BMP
type: BINARY
buffer_size: 4096
update_interval: 60min
on_download_finished:
- logger.log: "New online image downloaded successfully, refreshing e-paper screen..."
- component.update: epaper_display
Das waveshare_epaper-Display (model: gdey029t94, rotation: 90) zeichnet dann einfach id(remote_bitmap), sobald das Bild geladen ist.
Auf der Serverseite liefert ein schlanker HTTP-Server (epaper-web auf Port 8128) das /config/www/-Verzeichnis von Home Assistant aus. Sobald ich mit Pillow eine neue /config/www/epaper.bmp erzeugt habe, kann ich das Display per Home-Assistant-Automation sofort aktualisieren:
action: esphome.homebuttons_epaper_refresh_image
Ansonsten aktualisiert es sich beim Booten, alle 60 Minuten oder wenn ich Button 1 (GPIO5) bzw. Button 2 (GPIO6) drücke. Als netten Bonus liefert der verbaute Sensirion SHTC3-Sensor (0x70 am I2C-Bus) auch noch Raumtemperatur und Luftfeuchtigkeit direkt an Home Assistant.