Flashing Custom ESPHome Firmware onto an E-Paper HomeButtons Display
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.