Flashing Custom ESPHome Firmware onto an E-Paper HomeButtons Display

TL;DR

How I backed up the stock firmware, worked around an ESP32-S2FH4 flash frequency crash, and got dynamic e-paper dashboards running on a HomeButtons Original with ESPHome.

I have a HomeButtons Original (Hardware Rev 2.3)—a neat little wall-mounted device with physical pushbuttons and a 2.9" GoodDisplay e-paper screen (GDEY029T94, 296x128 monochrome). The stock firmware works fine for basic MQTT button presses, but I wanted full control: custom layouts rendered server-side in Home Assistant and pushed dynamically to the screen.

That meant flashing ESPHome onto it. As usual with custom hardware, it wasn't quite a one-click job, but the end result is rock-solid.

Step 1: Back Up the Stock Firmware

Before touching anything on an ESP32, I always take a full flash backup. If something goes sideways, you want a way back. To get the ESP32-S2FH4 into permanent ROM bootloader mode, you hold the BOOT button (or short GPIO0 to GND), press RESET (or replug USB), and release BOOT.

Then I ran esptool to dump the entire 4MB flash:

esptool --port /dev/ttyACM0 read-flash 0x0 0x400000 stock_firmware_backup_4mb.bin

It takes about 15–30 seconds and gives you a complete safety net.

Step 2: The ESP32-S2FH4 Boot Crash

Here's the part that tripped me up at first. The HomeButtons Rev 2.3 uses an ESP32-S2FH4 (single core, 4MB embedded flash, no external PSRAM). When I compiled a standard ESPHome esp-idf build and flashed it, it wouldn't boot properly.

The culprit was the flash header: ESPHome's generated firmware.factory.bin wrote 0x2f (80MHz, 4MB) into byte 3 of the image headers at 0x1000 (bootloader) and 0x10000 (app), which crashes the ESP32-S2FH4.

In homebuttons.yaml, I explicitly forced 40MHz DIO mode in sdkconfig_options:

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

Just to be 100% sure the binary headers matched, I also wrote a tiny Python script (flash_with_header_patch.py) that patches byte 3 at 0x1000 and 0x10000 to 0x20 (40MHz DIO) before flashing:

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

Once patched and flashed, it booted straight onto Wi-Fi without a hitch—and from then on, OTA updates work normally.

Step 3: Dynamic E-Paper Images via HTTP

Instead of hardcoding fonts and drawing logic in ESPHome's C++ lambda, I wanted to render the 296x128 1-bit monochrome .bmp in Python/Home Assistant and just have the display fetch it.

ESPHome's online_image component handles this cleanly:

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

The waveshare_epaper display component (model: gdey029t94, rotation: 90) simply draws id(remote_bitmap) whenever it's loaded.

On the server side, a lightweight HTTP server (epaper-web on port 8128) serves Home Assistant's /config/www/ directory. Whenever I generate a new /config/www/epaper.bmp with Pillow, I can trigger an instant refresh from any Home Assistant automation:

action: esphome.homebuttons_epaper_refresh_image

Otherwise, it refreshes automatically on boot, every 60 minutes, or when I press Button 1 (GPIO5) or Button 2 (GPIO6). As a bonus, the onboard Sensirion SHTC3 sensor (0x70 on I2C) also reports room temperature and humidity right back to Home Assistant.

Share this post: