esp32-weather-epd: a battery-powered E-Paper weather display built on the ESP32

The problem: a weather display that runs for months on one charge

Most ESP32 weather projects assume a USB cable. The board stays awake, polls an API, drives a TFT or OLED, and draws tens of milliamps continuously. That is fine on a desk and useless on a wall. This project takes the opposite constraint as its starting point: the device is asleep almost all the time, and the display is the only reason it wakes up.

The README states the power figures directly: roughly 14 microamps in sleep and roughly 83 milliamps during a refresh that lasts about 15 seconds. From those numbers the project claims 6 to 12 months of runtime on a 5000mAh battery at a 30-minute update frequency. That arithmetic is the whole design. If your update interval is 5 minutes instead of 30, the average current rises and the battery estimate stops applying.

The audience is narrow and specific. You need a 7.5 inch E-Paper panel from the supported list, a FireBeetle 2 ESP32-E, a DESPI-C02 adapter board, a BME280 for indoor readings, and a 3.7V LiPo with a JST-PH2.0 connector. The README also lists wires, a soldering iron unless you follow the solder-free component selection path, and a Linux, Windows or macOS computer to build and flash the firmware. This is not a plug-and-play gadget.

How the firmware works: wake, fetch, draw, sleep

The repository layout tells you most of the architecture before you open a source file. There is a platformio/ directory, which means the build is PlatformIO rather than the Arduino IDE. There are fonts/ and icons/ directories for the display assets. There is a cert/ directory, which holds the TLS certificate material needed to talk to OpenWeatherMap over HTTPS.

The data flow is a single cycle. On wake, the ESP32 fetches weather data from the OpenWeatherMap API, takes indoor temperature and humidity from the onboard sensor, refreshes the panel, and goes back to sleep. The README describes one part of that frame in detail: the hourly outlook graph in the bottom right shows a line for temperature and shaded bars for probability of precipitation, or optionally precipitation volume.

Because the panel is the slow part, the 15-second refresh dominates the awake time. E-paper also has a known behaviour that the README acknowledges indirectly: panels with additional colors take longer to refresh, which reduces battery life. The recommended panel, the Waveshare 7.5in v2, is black and white.

Configuration is broad. The README lists multiple languages, units, time and date formats, AQI scales and personalization options. That breadth is a trade-off: it means the firmware carries tables for units and locales, and every added option is another path through the rendering code that someone has to keep working.

Installing esp32-weather-epd and getting a first frame on the panel

The README points to a Setup Guide with three parts: wiring, configuration plus compilation and upload, and the OpenWeatherMap API key. What the repository does tell you is where the build lives: the platformio/ directory holds the project configuration, and the README states that a Linux, Windows or macOS computer is needed to configure and install the ESP32 firmware. Follow the Setup Guide's Configuration, Compilation, and Upload section for the exact steps for your machine.

Before any of that produces a useful image, you need an OpenWeatherMap API key, which the README treats as its own setup step. Without a valid key the device will surface an API error rather than weather data.

The README documents the error states you are likely to hit on a first attempt, each with its own section: Low Battery, WiFi Connection, API Error, and Time Server Error. Those four cover the realistic first-run failures, and they are worth reading before you power the board rather than after.

Expect the first refresh to take about 15 seconds, and expect the panel to hold the last frame after the board goes back to sleep.

Panel support is the real constraint, and v1 panels are half-supported

The panel support table is the most important page in the README, and it is where most failed builds will originate. The recommended configuration is a Waveshare 7.5 inch e-paper v2 or the equivalent Good Display GDEY075T7, both 800x480 black and white. Red/black/white panels and 7.3 inch seven-color panels are listed as supported, with the caveat that extra colors mean longer refreshes and shorter battery life.

The sharp edge is at the bottom of the table. The Waveshare 7.5 inch e-paper v1 and the Good Display GDEW075T8 are 640x384, and the README describes them as limited support with some information not displayed, pointing at a demo image to show what is lost. If you already own one of those panels, this project will run but the layout will not fit properly.

The README also warns against Waveshare HATs revision 2.2 and 2.3 and recommends the DESPI-C02 adapter board instead. Buying the wrong adapter is an easy mistake to make when ordering parts from a list, and it is not something the firmware can compensate for.

One more limitation sits outside the README text: the project has no published releases, so there is no packaged binary to download. You build from source. The last push to the repository was on 2026-07-22.

Where esp32-weather-epd is the wrong tool

If you want a weather dashboard with a touchscreen, charts you can tap, or a web interface, this is the wrong project. The output is a static image refreshed on a timer. There is no interaction beyond an optional push button for reset, and the README frames that button as a convenience for mounting a reset switch on the enclosure, not as an input method.

If you want to avoid a toolchain, this is also the wrong project. It is C firmware built with PlatformIO, and the setup guide assumes a Linux, Windows or macOS computer. A beginner looking for an ESP32 weather station to assemble from a kit will find the component list, the soldering, the adapter board choice and the API key setup to be four separate hurdles before the first image appears.

If your panel is a 640x384 v1, the README marks it as limited support with some information not displayed; panels outside the support table are not listed.

Finally, if you need indoor readings without extra hardware, note that the BME280 is a separate component. The ESP32 itself is not the source of the indoor temperature and humidity values on the display.

How it compares with ESPHome and Home Assistant weather dashboards

The closest alternative in practice is an ESP32 running ESPHome and feeding a Home Assistant dashboard, or driving an E-Paper panel as a Home Assistant display node. The difference in approach is where the logic lives. ESPHome keeps the device thin and puts automations, data sources and rendering decisions on a Home Assistant server, so you can change what is shown without reflashing. This project puts everything on the device: it talks to OpenWeatherMap directly, renders locally from its own fonts and icons, and needs no server at all.

That single difference drives the rest. No server means no always-on machine in the house and no network dependency beyond WiFi and the weather API, which is what makes the 14 microamp sleep figure meaningful. It also means changing the layout requires editing C code, regenerating font and icon assets, and reflashing over USB. With ESPHome you would edit YAML in a browser.

A second alternative is any of the ESP32 weather station projects built around a TFT or LCD. Those refresh faster and can animate, at the cost of continuous power draw. E-paper is chosen here precisely because it holds an image with no power, and the README's battery claims only make sense under that assumption.

Maintenance, licence and what you are taking on

The repository is not archived and the last push was on 2026-07-22, so the code has been touched recently enough that the project is not abandoned. The repository has no published GitHub releases, which means upgrades arrive as commits on the main branch rather than tagged versions. You pull, rebuild, and reflash. Keep your own copy of a working configuration before you update.

The upgrade cost is mostly in configuration drift. The README advertises customization across languages, units, time and date formats, AQI scales and personalization options, and each of those is a setting you re-check after a pull. Fonts and icons are committed assets, so a layout change can mean regenerating them.

Licensing is GPL-3.0. The practical implication for a hobbyist building one unit for a wall is minimal. The implication for anyone shipping a product based on this firmware is larger, because GPL-3.0 carries source-disclosure obligations for distributed derivative works, including the firmware you flash onto hardware you sell. That is a question for a lawyer, not for this article, but it is worth resolving before you design an enclosure around the code rather than after.

The README also notes that some component links are affiliate links that support the project. That does not change the licence or the code, but it is worth knowing when you follow the parts list.

Editorial conclusion

Adopt it if you already own a supported 7.5 inch black-and-white Waveshare or Good Display panel and are comfortable wiring a BME280 and a LiPo to a FireBeetle 2 ESP32-E, because the firmware, fonts, icons and certificate bundle are already wired for that exact combination. Do not adopt it if you want a kit you assemble without a build toolchain, if you need a 640x384 v1 panel to show everything, or if you expect a web dashboard instead of a static image. Before ordering parts, verify three things: that your panel model appears in the panel support table, that you have an OpenWeatherMap API key, and that the GPL-3.0 licence terms suit a device you may want to sell.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. lmarzen/esp32-weather-epd on GitHub
4. README