esp32-weather-epd: Low-Power E-Paper Weather Display on an ESP32
A low-power E-Paper weather display powered by an ESP32 microcontroller. Utilizes the OpenWeatherMap API.
At a glance
- What is it?
- esp32-weather-epd is a firmware project for a battery-powered weather display built with a WiFi-enabled ESP32 microcontroller and a 7.5-inch E-Paper screen. It fetches weather data from the OpenWeatherMap API and reads indoor temperature and humidity from a BME280 sensor, targeting makers who want a months-long-running wall display without a constant power cable.
- Who is it for?
- esp32-weather-epd is a good fit for makers who want a polished, long-running weather display without designing firmware from scratch. The hardware list is specific enough that assembling a compatible set of components requires careful part matching, particularly the adapter board and the E-Paper panel revision.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 69 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 30, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The Design Goal: Months of Battery Life with a Readable Display
E-Paper displays draw power only when their pixels change, which makes them well-suited for battery-powered devices that refresh infrequently. esp32-weather-epd exploits this property to build a weather display that runs for months between charges. The README states the device draws approximately 14 microamps during deep sleep and approximately 83 milliamps during the roughly 15-second refresh period. With a 5000mAh LiPo battery and a 30-minute update frequency, the README documents a runtime of 6 to 12 months.
The display is a 7.5-inch E-Paper panel at 800x480 pixels. The firmware also reads an onboard BME280 sensor for indoor temperature, humidity, and pressure, so the screen shows both outdoor forecast data and indoor conditions. The design targets a finished, standalone device that can sit on a shelf or hang on a wall without a power cable.
Required Hardware Components
The README specifies a precise set of components. The recommended microcontroller is the FireBeetle 2 ESP32-E, chosen for its low-power design, USB-C port, and onboard battery management circuit. The display connects through a DESPI-C02 adapter board; the README notes that Waveshare HATs revision 2.2 and 2.3 are not recommended as substitutes.
The sensor is a BME280, which measures temperature, humidity, and pressure and is compatible with both 3.3V and 5V logic. The battery is a 3.7V LiPo with a JST-PH2.0 connector; any capacity works, but the 6-plus-months runtime figure assumes 5000mAh.
The firmware supports multiple E-Paper panel variants across three color configurations:
- Black and white panels: Waveshare 7.5-inch v2 (800x480, recommended) and Good Display GDEY075T7 (800x480) - Three-color panels with red accent: Waveshare 7.5-inch B and Good Display GDEY075Z08 - Seven-color panels: Waveshare 7.3-inch ACeP F and several Good Display equivalents
The README notes that panels with additional colors have longer refresh times, which reduces battery life. The version 1 Waveshare panel (640x384 pixels) has limited support and cannot display all information shown in the recommended configuration.
Configuration and Firmware Upload
The repository uses PlatformIO as its build system, with the configuration in the platformio/ directory. The general workflow is to clone the repository, edit the configuration file to set WiFi credentials, the OpenWeatherMap API key, units, language, and display preferences, then build and flash with PlatformIO.
The README documents several configuration options: multiple display languages, metric and imperial units, time and date formats, AQI scale selection, and personalization options. The hourly outlook graph at the bottom right of the display shows temperature as a line and precipitation probability as shaded bars; the README notes this can optionally show precipitation volume instead.
An OpenWeatherMap API key is required. The README dedicates a section to obtaining one, because the key must be acquired before the firmware can fetch weather data. The README also covers troubleshooting for four specific error conditions that the display shows on screen: low battery, WiFi connection failure, API error, and time server error. Each condition shows a labeled message on the E-Paper display rather than silently failing.
Wiring and Assembly Considerations
The README provides a wiring guide for connecting the FireBeetle 2 ESP32-E to the DESPI-C02 adapter board and the BME280 sensor. The project requires basic electronics work. The README notes that jumper wires can minimize or avoid soldering if the components with pre-soldered headers are selected, but a soldering iron is needed for the default component selection.
For the enclosure, the README describes the author's DIY wooden stand as an example: a hollowed piece of wood with a short USB extension cable for charging without disassembly, a wired reset button for manual refresh, a 3D-printed cover held by magnets, and a thin acrylic panel to support the E-Paper screen. Measurements are provided (depth 63mm, height 49mm, width 170.2mm, 80-degree screen angle). The README also references community-contributed 3D printable enclosure designs; the README does not list all of them.
The reset button is optional. If not wired to the enclosure exterior, the on-board reset button on the ESP32 module serves as the manual refresh trigger.
Limitations and Failure Modes
The display refresh cycle is about 15 seconds, during which the device consumes around 83 milliamps. More frequent updates shorten battery life proportionally. The 6-to-12-month estimate assumes 30-minute intervals; hourly updates would roughly halve that runtime.
The seven-color E-Paper panels have longer refresh times than black-and-white panels. The README does not state exact refresh durations for the color variants, but longer refresh time means more energy consumed per cycle, reducing battery life below the documented figures.
The firmware depends on the OpenWeatherMap API. Changes to that API's endpoint structure, authentication requirements, or plan restrictions will break the firmware's ability to fetch data. The README does not document which specific API endpoint or plan tier the firmware targets, so users must verify compatibility when the OpenWeatherMap service changes its offering.
Finally, the project has no releases in the GitHub release system. The firmware is built from source using PlatformIO. Users who are not comfortable with embedded development toolchains should expect a non-trivial setup process.
Comparison with Commercial Weather Displays and Other ESP32 Projects
Commercial E-Paper weather displays exist from vendors like Inkbird and Xiaomi. The difference from esp32-weather-epd is control: commercial displays are fixed-function, show only what the manufacturer designed, and depend on the manufacturer's cloud service. esp32-weather-epd is fully configurable at the firmware level, displays custom AQI data, and can be adapted to use a different weather API by modifying the source.
ESP32 projects using TFT or LCD displays instead of E-Paper are common alternatives. An LCD display refreshes faster and can show animations, but it draws continuous power whether or not the pixels change, which makes a months-long battery runtime impossible without significantly larger batteries or a constant power connection. The E-Paper constraint is also an advantage for outdoor-light readability; E-Paper screens are visible in bright light where backlit displays wash out.
The esp32-weather-epd repository has no GitHub releases. All firmware is built from the main branch using PlatformIO, which means users must track source changes manually to pick up fixes. This is a meaningful maintenance consideration for a device that will sit on a wall for months: a bug fix in the source requires reflashing the firmware, which involves disassembling the enclosure to reach the USB-C port unless an external charging port was wired during assembly. The README's suggestion to wire a USB extension cable for charging is therefore also useful for firmware updates.
Editorial conclusion
esp32-weather-epd is a good fit for makers who want a polished, long-running weather display without designing firmware from scratch. The hardware list is specific enough that assembling a compatible set of components requires careful part matching, particularly the adapter board and the E-Paper panel revision. Verify that the OpenWeatherMap API key is on a plan that supports the endpoint the firmware calls before building the enclosure, because an expired or rate-limited key will cause the display to show an API error at every refresh cycle.
Frequently asked questions
Does ESP32 have a built-in temperature sensor?
The ESP32 chip includes an internal temperature sensor, but it measures the chip's own operating temperature rather than ambient conditions. esp32-weather-epd uses an external BME280 sensor for indoor temperature and humidity readings, and fetches outdoor weather data from the OpenWeatherMap API.
Why is my ESP32 so hot?
The ESP32 generates heat during active WiFi and processing operations. In esp32-weather-epd, the device spends most of its time in deep sleep at approximately 14 microamps, activating for about 15 seconds every 30 minutes to fetch data and refresh the display. Continuous operation for debugging or during initial setup will cause more heat than normal deployment behavior.
What is the best humidity sensor for ESP32 weather projects?
esp32-weather-epd uses the BME280, which measures temperature, humidity, and pressure and operates at both 3.3V and 5V logic levels. The README specifies this sensor for the project and notes it is available from multiple vendors.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/lmarzen-esp32-weather-epd)