Feed images to Waveshare two-color ePaper display attached to ESP32 with deep sleep mechanism

As ePaper displays are getting cheaper more and more, I started to investigate the possibilities for using such a device at places without constant power supply.

ePaper display


  • use Waveshare ePaper display with black/white/red pixels
  • powered by battery
  • long periods of time (maybe months) without charging the battery
  • at least daily upload of new content
  • network configuration of ESP32 NOT hard-coded (preferred by something like Arduino library WifiManager)
  • optional MQTT interface

Unfortunately, there were tons of projects on GitHub or home automation forums, but none of them fulfilled my requirements completely.

A good start for me was reading the blog post of "André" which is based on the work of "Yattien":

So far, we have Yattien's working ESP32 firmware which is a modification of the original "Price tag" implementation of Waveshare, that is capable of a managed network configuration and the MQTT interface.

Nevertheless, I would like to send new images by using some lightweight solution and without setting up a complete FHEM environment. Up to now, it seems nobody has done something like that, so I had to implement it on my own.

The primary idea was to capture the communication of Waveshare's "price tag" web interface, which led to a simple PHP script:


How does it work?

The ESP's buffer is limited. Sending bitmaps over wifi and doing the calculations on the microprocessor does not make much sense.

Therefore, the image calculations are done on the device that will execute the PHP script.

We provide an image in the ePaper's native resolution, apply a dithering algorithm, create two arrays (one for black pixels, one for red pixels) and finally send them in chunks to the EPS's web interface using the PHP curl-functions.

As there are some inconveniences regarding conversions between byte and char data types, the PHP script will add the value of the character "a" to each byte value which contains the value of four pixels. The communication between the script and the ESP's firmware will now use characters for the pixel payload and the ESP will subtract the value and assign the pixel color to the ePaper's memory afterwards.

Including MQTT

The final process is as follows:

  1. The ESP will check the configured topic upon wake up, if a refresh for the current image is needed, e.g. "stat/display/needUpdate". If the payload is "true", step 2 will follow, otherwise the ESP will start to deep sleep.
  2. The ESP will set topic "cmd/display/upload" to "true"
  3. The PHP script has to be executed as soon as step 2 is recognized, e.g. by checking the MQTT payload for the given topic "cmd/display/upload".
  4. The ESP will refresh the ePaper display and show the new image.
  5. The ESP will go to deep sleep for the configured amount of time.
  6. Everything will repeat from step 1.

We use cookies on our website. Some of them are essential for the operation of the site, while others help us to improve this site and the user experience (tracking cookies). You can decide for yourself whether you want to allow cookies or not. Please note that if you reject them, you may not be able to use all the functionalities of the site.