ESP32 E-Paper Weather Display

This is a weather display powered by a wifi-enabled ESP32 microcontroller and a 7.5in E-Paper (aka E-ink) display. Current and forecasted weather data is obtained from the OpenWeatherMap API. A sensor provides the display with accurate indoor temperature and humidity.

The project draws ~14μA when sleeping and an estimated average of ~83mA during its ~15s wake period. The display can be configured to update as frequently as desired. When the refresh interval is set to 30 minutes, the device will run for >6 months on a single 5000mAh battery. The project displays accurate battery life percentage and can be recharged via a USB-C cable connected to a wall adapter or computer.

There are configuration options for everything from location, time/date formats, units, and language to air quality index scale and hourly outlook graph bounds.

The hourly outlook graph (bottom right) shows a line indicating temperature and shaded bars indicating probability of precipitation (or optionally volume of precipitation).

Here are two examples utilizing various configuration options:

Contents

• Setup Guide
  • Hardware
  • Wiring
  • Configuration, Compilation, and Upload
  • OpenWeatherMap API Key
• Error Messages and Troubleshooting
  • Low Battery
  • WiFi Connection
  • API Error
  • Time Server Error
• Licensing

Customizing and Keeping Up-to-Date with the Original Project

This project is a fork of lmarzen/esp32-weather-epd. This section explains how to customize your forked version and how to merge in updates from the original repository.

1. Fork the Repository:

• Visit the lmarzen/esp32-weather-epd repository.
• Click the "Fork" button in the top-right corner to create a copy of the repository under your GitHub account.

2. Clone Your Fork:

• Open a terminal or command prompt.

• Navigate to the directory where you want to store your project.

• Clone your forked repository using git:

  git clone https://github.com/<your-username>/esp32-weather-epd.git
  cd esp32-weather-epd

  (Replace <your-username> with your GitHub username.)

3. Add the Original Repository as an "Upstream" Remote:

• This step allows you to fetch updates from the original repository.

  git remote add upstream https://github.com/lmarzen/esp32-weather-epd.git

• Verify that the remotes are configured correctly:

  git remote -v

  You should see output similar to this:

  origin  https://github.com/<your-username>/esp32-weather-epd.git (fetch)
  origin  https://github.com/<your-username>/esp32-weather-epd.git (push)
  upstream        https://github.com/lmarzen/esp32-weather-epd.git (fetch)
  upstream        https://github.com/lmarzen/esp32-weather-epd.git (push)
  

4. Create a Branch for Your Modifications:

• Avoid making direct changes to the main branch. Create a new branch for your customizations.

  git checkout -b my-feature-branch

  (Replace my-feature-branch with a descriptive name for your branch, e.g., add-display-rotation, customize-weather-icons.)

5. Make Your Modifications:

• Edit the code in your my-feature-branch. Add your custom features, fix bugs, or change the behavior of the original project to fit your requirements.

6. Commit Your Changes:

• After making changes, stage them:

  git add .  # Or git add <specific_file> if you only want to stage certain files

• Commit your changes with a descriptive message:

  git commit -m "Add display rotation functionality"

7. Push Your Branch to Your Fork:

• Push your branch to your forked repository on GitHub:

  git push origin my-feature-branch

8. Keeping Up-to-Date with the Original Repository (Upstream):

• Periodically, you'll want to check for updates from the original lmarzen/esp32-weather-epd repository.

  • Fetch the latest changes from upstream:

    git fetch upstream

  • Merge or Rebase the upstream changes into your branch:

    Choose one of the following methods:

    • Merge (Simpler, Preserves History):

      git checkout my-feature-branch  # Make sure you're on your branch
      git merge upstream/main

    • Rebase (Cleaner History, Use with Caution on Shared Branches):

      git checkout my-feature-branch
      git rebase upstream/main

      Rebasing rewrites your branch's history by reapplying your commits on top of the latest upstream/main. Use this with caution if you have already pushed your branch to your remote repository and others are collaborating on it.

  • Resolve any conflicts: If there are conflicts between your changes and the upstream changes, Git will mark them in the affected files. You'll need to manually edit those files to resolve the conflicts, then git add the resolved files and git commit (if merging) or git rebase --continue (if rebasing).

  • Push the updated branch to your fork:

    git push origin my-feature-branch

Best Practices:

• Descriptive Commit Messages: Write clear and descriptive commit messages to explain the purpose of each change.
• Regularly Update: Fetch and merge/rebase from upstream frequently to minimize the risk of large, difficult-to-resolve conflicts.
• Testing: Thoroughly test your changes after merging/rebasing to ensure they work as expected and haven't introduced any regressions.

Example Scenario:

Let's say you want to add the ability to rotate the display by 90 degrees.

1. Fork and Clone the repository as described above.
2. Add Upstream as described above.
3. Create a branch: git checkout -b add-display-rotation
4. Modify the code: (Implement the display rotation logic)
5. Commit your changes: git add . then git commit -m "Add 90-degree display rotation option"
6. Push your branch: git push origin add-display-rotation

Later, if the original esp32-weather-epd project receives an update:

1. Fetch upstream: git fetch upstream
2. Merge/Rebase: git checkout add-display-rotation then git rebase upstream/main or git merge upstream/main
3. Resolve conflicts (if any): If the upstream changes conflict with your rotation code, you'll need to fix them.
4. Test: Make sure the rotation still works correctly after the merge/rebase.
5. Push: git push origin add-display-rotation

This workflow enables you to customize and enhance the esp32-weather-epd project while maintaining the ability to integrate improvements and bug fixes from the original repository.

Setup Guide

Hardware

7.5inch (800×480) E-Paper Display

• Advantages of E-Paper

  • Ultra Low Power Consumption - E-Paper (aka E-Ink) displays are ideal for low-power applications that do not require frequent display refreshes. E-Paper displays only draw power when refreshing the display and do not have a backlight. Images will remain on the screen even when power is removed.

• Limitations of E-Paper:

  • Colors - E-Paper has traditionally been limited to just black and white, but in recent years 3-color E-Paper screens have started showing up.

  • Refresh Times and Ghosting - E-Paper displays are highly susceptible to ghosting effects if refreshed too quickly. To avoid this, E-Paper displays often take a few seconds to refresh(4s for the unit used in this project) and will alternate between black and white a few times, which can be distracting.

• Panel support:

  Waveshare and Good Display make equivalent panels. Either variant will work.

  Panel	Resolution	Colors	Notes
  Waveshare 7.5in e-paper (v2)	800x480px	Black/White	Available here. (recommended)
  Good Display 7.5in e-paper (GDEY075T7)	800x480px	Black/White	Available here. (recommended)
  Waveshare 7.5in e-Paper (B)	800x480px	Red/Black/White	Available here.
  Good Display 7.5in e-paper (GDEY075Z08)	800x480px	Red/Black/White	Available here.
  Waveshare 7.3in ACeP e-Paper (F)	800x480px	7-Color	Available here.
  Good Display 7.3in e-paper (GDEY073D46)	800x480px	7-Color	Available here.
  Waveshare 7.5in e-paper (v1)	640x384px	Black/White	Limited support. Some information not displayed, see image.
  Good Display 7.5in e-paper (GDEW075T8)	640x384px	Black/White	Limited support. Some information not displayed, see image.

  This software has limited support for accent colors. E-paper panels with additional colors tend to have longer refresh times, which will reduce battery life.

DESPI-C02 Adapter Board

• No level converters, which makes it better for low-power use with 3.3V processors compared to the Waveshare HAT.

• The Waveshare HATs (rev 2.2/2.3) are not recommended. Their compatibility with this project is not regularly tested.

• https://www.e-paper-display.com/products_detail/productId=403.html

• https://www.aliexpress.us/item/3256804446769469.html

FireBeetle 2 ESP32-E Microcontroller

• Why the ESP32?

  • Onboard WiFi.

  • 520kB of RAM and 4MB of FLASH, enough to store lots of icons and fonts.

  • Low power consumption.

  • Small size, many small development boards available.

• Why the FireBeetle 2 ESP32-E

  • Drobot's FireBeetle ESP32 models are optimized for low-power consumption (https://diyi0t.com/reduce-the-esp32-power-consumption/). The Drobot's FireBeetle 2 ESP32-E variant offers USB-C, but older versions of the board with Micro-USB would work fine too.

  • Firebeetle ESP32 models include onboard charging circuitry for a 3.7v lithium-ion(LiPo) battery.

  • FireBeetle ESP32 models include onboard circuitry to monitor battery voltage of a battery connected to its JST-PH2.0 connector.

• https://www.dfrobot.com/product-2195.html

BME280 - Pressure, Temperature, and Humidity Sensor

• Provides accurate indoor temperature and humidity.

• Much faster than the DHT22, which requires a 2-second wait before reading temperature and humidity samples.

3.7V Lipo Battery w/ 2 Pin JST Connector

• Size is up to you. I used a 5000mah battery so that the device can operate on a single charge for >6 months.

• The battery can be charged by plugging the FireBeetle ESP32 into the wall via the USB-C connector while the battery is plugged into the ESP32's JST connector.

  Warning The polarity of JST-PH2.0 connectors is not standardized! You may need to swap the order of the wires in the connector.

Stand/Frame

• You'll want a nice way to show off your project. Here are a few popular choices.
• DIY Wooden
  • I made a small stand by hollowing out a piece of wood from the bottom. On the back, I used a short USB extension cable so that I can charge the battery without needing to remove the components from the stand. I also wired a small reset button to refresh the display manually. Additionally, I 3d printed a cover for the bottom, which is held on by magnets. The E-paper screen is very thin, so I used a thin piece of acrylic to support it.
  • Measurements:
    • depth = 63mm
      height = 49mm
      width = 170.2mm (= width of the screen)
      screen angle = 80deg
      screen is 15mm from the front
• 3D Printable

  • Here is a list of community designs.

    Contributor	Link
    Kingfisher	Printables
    Francois Allard	Printables
    3D Nate	Printables
    Sven F.	Printables
    Layers Studio	Printables
    PJ Veltri	Printables
    TheMeanCanEHdian	Printables
    MPHarms	Thingiverse
    Plaste-Metz	Printables

  • If you want to share your own 3D printable designs, your contributions are highly encouraged and welcome!

• Picture Frame

Wiring

Pin connections are defined in config.cpp.

If you are using the FireBeetle 2 ESP32-E, you can use the connections I used or change them how you would like.

I have included 2 wiring diagrams. One for the Waveshare HAT rev2.2 and another using the recommended DESPI-C02.

NOTE: Waveshare now ships revision 2.3 of their e-paper HAT (no longer rev 2.2 ). Rev 2.3 has an additional PWR pin (not depicted in the wiring diagrams below); connect this pin to 3.3V.

IMPORTANT: The Waveshare E-Paper Driver HAT has two physical switches that MUST be set correctly for the display to work.

• Display Config: Set switch to position B.

• Interface Config: Set switch to position 0.

IMPORTANT: The DESPI-C02 adapter has one physical switch that MUST be set correctly for the display to work.

• RESE: Set switch to position 0.47.

Cut the low power pad for even longer battery life.

• From https://wiki.dfrobot.com/FireBeetle_Board_ESP32_E_SKU_DFR0654

  Low Power Pad: This pad is specially designed for low power consumption. It is connected by default. You can cut off the thin wire in the middle with a knife to disconnect it. After disconnection, the static power consumption can be reduced by 500 μA. The power consumption can be reduced to 13 μA after controlling the maincontroller enter the sleep mode through the program. Note: when the pad is disconnected, you can only drive RGB LED light via the USB Power supply.

Configuration, Compilation, and Upload

PlatformIO for VSCode is used for managing dependencies, code compilation, and uploading to ESP32.

1. Clone this repository or download and extract the .zip.

2. Install VSCode.

3. Follow these instructions to install the PlatformIO extension for VSCode: https://platformio.org/install/ide?install=vscode

4. Open the project in VSCode.

   a. File > Open Folder...

   b. Navigate to this project and select the folder called "platformio".

5. Configure Options.

   • Most configuration options are located in config.cpp, with a few in config.h. Locale/language options can also be found in include/locales/locale_*.inc.

   • Important settings to configure in config.cpp:

     • WiFi credentials (ssid, password).

     • Open Weather Map API key (it's free, see next section for important notes about obtaining an API key).

     • Latitude and longitude.

     • Time and date formats.

     • Sleep duration.

     • Pin connections for E-Paper (SPI), BME280 (I2C), and battery voltage (ADC).

   • Important settings to configure in config.h:

     • Units (Metric or Imperial).

   • Comments explain each option in detail.

6. Build and Upload Code.

   a. Connect ESP32 to your computer via USB.

   b. Click the upload arrow along the bottom of the VSCode window. (Should say "PlatformIO: Upload" if you hover over it.)

   • PlatformIO will automatically download the required third-party libraries, compile, and upload the code. :)

   • You will only see this if you have the PlatformIO extension installed.

   • If using a FireBeetle 2 ESP32-E and you receive the error Wrong boot mode detected (0x13)! The chip needs to be in download mode. unplug the power from the board, connect GPIO0 (labeled 0/D5) to GND, and power it back up to put the board in download mode.

   • If you are getting other errors during the upload process, you may need to install drivers to allow you to upload code to the ESP32.

OpenWeatherMap API Key

Sign up here to get an API key; it's free. https://openweathermap.org/api

This project will make calls to 2 different APIs ("One Call" and "Air Pollution").

• The One Call API 3.0 is only included in the "One Call by Call" subscription. This separate subscription includes 1,000 calls/day for free and allows you to pay only for the number of API calls made to this product.

Here's how to subscribe and avoid any credit card changes:

• Go to https://home.openweathermap.org/subscriptions/billing_info/onecall_30/base?key=base&service=onecall_30
• Follow the instructions to complete the subscription.
• Go to https://home.openweathermap.org/subscriptions and set the "Calls per day (no more than)" to 1,000. This ensures you will never overrun the free calls.

Error Messages and Troubleshooting

Low Battery

This error screen appears once the battery voltage has fallen below LOW_BATTERY_VOLTAGE (default = 3.20v). The display will not refresh again until it detects battery voltage above LOW_BATTERY_VOLTAGE. When battery voltage is between LOW_BATTERY_VOLTAGE and VERY_LOW_BATTERY_VOLTAGE (default = 3.10v) the esp32 will deep-sleep for periods of LOW_BATTERY_SLEEP_INTERVAL (default = 30min) before checking battery voltage again. If the battery voltage falls between LOW_BATTERY_SLEEP_INTERVAL and CRIT_LOW_BATTERY_VOLTAGE (default = 3.00v), then the display will deep-sleep for periods VERY_LOW_BATTERY_SLEEP_INTERVAL (default = 120min). If battery voltage falls below CRIT_LOW_BATTERY_VOLTAGE, then the esp32 will enter hibernate mode and will require a manual push of the reset (RST) button to begin updating again.

WiFi Connection

This error screen appears when the ESP32 fails to connect to WiFi. If the message reads "WiFi Connection Failed" this might indicate an incorrect password. If the message reads "SSID Not Available" this might indicate that you mistyped the SSID or that the esp32 is out of the range of the access point. The esp32 will retry once every SLEEP_DURATION (default = 30min).

API Error

This error screen appears if an error (client or server) occurs when making an API request to OpenWeatherMap. The second line will give the error code followed by a descriptor phrase. Positive error codes correspond to HTTP response status codes, while error codes <= 0 indicate a client(esp32) error. The esp32 will retry once every SLEEP_DURATION (default = 30min).

In the example shown to the left, "401: Unauthorized" may be the result of an incorrect API key or that you are attempting to use the One Call v3 API without the proper account setup.

Time Server Error

This error screen appears when the esp32 fails to fetch the time from NTP_SERVER_1/NTP_SERVER_2. This error sometimes occurs immediately after uploading to the esp32; in this case, just hit the reset button or wait for SLEEP_DURATION (default = 30min) and the esp32 to automatically retry. If the error persists, try selecting closer/lower latency time servers or increasing NTP_TIMEOUT.

Licensing

esp32-weather-epd is licensed under the GNU General Public License v3.0 with tools, fonts, and icons whose licenses are as follows:

Name	License	Description
Adafruit-GFX-Library: fontconvert	BSD License	CLI tool for preprocessing fonts to be used with the Adafruit_GFX Arduino library.
pollutant-concentration-to-aqi	GNU Lesser General Public License v2.1	C library that converts pollutant concentrations to Air Quality Index(AQI).
GNU FreeFont	GNU General Public License v3.0	Font Family
Lato	SIL OFL v1.1	Font Family
Montserrat	SIL OFL v1.1	Font Family
Open Sans	SIL OFL v1.1	Font Family
Poppins	SIL OFL v1.1	Font Family
Quicksand	SIL OFL v1.1	Font Family
Raleway	SIL OFL v1.1	Font Family
Roboto	Apache License v2.0	Font Family
Roboto Mono	Apache License v2.0	Font Family
Roboto Slab	Apache License v2.0	Font Family
Ubuntu font	Ubuntu Font Licence v1.0	Font Family
Weather Themed Icons	SIL OFL v1.1	(wi-**.svg) Weather icon family by Lukas Bischoff/Erik Flowers.
Google Icons	Apache License v2.0	(battery**.svg, visibility_icon.svg) Battery and visibility icons from Google Icons.
Biological Hazard Symbol	CC0 v1.0	(biological_hazard_symbol.svg) Biohazard icon.
House Icon	MIT License	(house.svg) House icon.
Indoor Temerature/Humidity Icons	SIL OFL v1.1	(house_**.svg) Indoor temerature/humidity icons.
Ionizing Radiation Symbol	CC0 v1.0	(ionizing_radiation_symbol.svg) Ionizing radiation icons.
Phosphor Icons	MIT License	(wifi**.svg, warning_icon.svg, error_icon.svg) WiFi, Warning, and Error icons from Phosphor Icons.
Wind Direction Icon	CC BY v3.0	(meteorological_wind_direction_**deg.svg) Meteorological wind direction icon from Online Web Fonts.