--- title: "Flashing Custom ESPHome Firmware onto an E-Paper HomeButtons Display" date: 2026-11-17 tldr: "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." tags: - ESPHome - ESP32 - E-Paper - Home Assistant - Smart Home layout: post.njk lang: en translationKey: flashing-esphome-epaper-homebuttons --- 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: ```bash 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`: ```yaml 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: ```python 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: ```yaml 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: ```yaml 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.