E-Paper Dashboards with Waveshare and ESPHome

About Waveshare E-Paper Displays

Waveshare is a company specializing in the design and manufacturing of electronic components, including development boards, displays, and sensors, for use in areas such as IoT, robotics, and education. If you’ve ever encountered beautiful, large e-paper (e-ink) displays used with ESPHome and Home Assistant, chances are they were made by Waveshare.

Unlike LED or LCD panels, e-paper displays typically feature only several colors or come only in black and white. This is because their underlying technology, primarily electrophoretic displays (EPDs), relies on the physical movement of charged pigment particles to form an image.

In simpler words, it’s like tiny specks of colored dust are physically moved around to create what you see, rather than lights turning on or off. This physical movement is much harder to do with many different colors quickly and vibrantly.

In this article, I am sharing my experience with Waveshare e-Paper displays and ESPHome. My goal is to clear up the confusion of which models work with ESPHome, what features and colors are supported and perhaps give you some ideas for use cases.

Waveshare and ESPHome Compatibility

Waveshare produces a very wide range of e-paper displays, which can quickly become overwhelming when considering Home Assistant and ESPHome compatibility. This is further complicated by variations of the same panels, making the process of figuring things out even more difficult.

To remedy this to an extent, I’ve dug deep into the niche forums and discussion groups to identify which models are officially supported, partially supported, and unsupported. Additionally, because Waveshare offers a very convenient ESP32 e-Paper driver board, I’ve noted which panels are directly compatible with it without needing extra drivers or breakout boards.

Model (ePaper)	Device Size Display Size (mm)	Colors Resolution1	Refresh Rate	Partial Refresh	Driver Board Compatibility2	ESPHome Model3	Price (USD)
1.54″ ePaper 12561	37.32×31.80×1.05 27.60×27.60	BW 200×200	2sec	0.3sec	ESP32 ESP8266	1.54in 1.54inv24	Amazon US Amazon DE AliExpress
1.54″ ePaper (B) 13275	31.8×37.32×1.05 27.60×27.60	BWR 200×200	14sec	X	ESP32 ESP8266	1.54inv2-b	Amazon US Amazon DE AliExpress
2.70″ ePaper 13378	70.42×45.8×0.98 57.29×38.20	BW 264×176	6sec	0.3sec	ESP32 ESP8266	2.70inv2	Amazon US Amazon DE AliExpress
2.70″ ePaper (B) 13185	70.42×45.8×0.98 57.29×38.20	BWR 264×176	15sec	X	ESP32 ESP8266	2.70in-b 2.70in-bv25	N/A
2.90″ ePaper 12563	79.00×36.70×1.05 66.89×29.05	BW 296×128	3sec	0.6sec	ESP32 ESP8266	2.90in 2.90in-dke 2.90inv26 2.90inv2-r27	Amazon US Amazon DE AliExpress
2.90″ ePaper (B) 13276	79.00×36.70×1.20 66.90×29.06	BWR 296×128	14sec	1.8sec	ESP32 ESP8266	2.90in-b8 2.90in-bV39	Amazon US Amazon DE AliExpress
4.20″ ePaper 13186	91.00×77.00×1.18 84.80×63.60	BW 400×300	5sec	1.5sec	ESP32 ESP8266	4.20in	Amazon US Amazon DE AliExpress
4.20″ ePaper (B) 13379	91.00×77.00×1.05 84.80×63.60	BWR 400×300	15sec	X	ESP32 ESP8266	4.20in-bV210 4.20in-bV2-bwr11	Amazon US Amazon DE AliExpress
5.83″ ePaper 14410	125.40×99.50×1.18 119.23×88.32	BW 640×480	5sec	X	ESP32 ESP8266	5.83in 5.83inv212	Amazon US Amazon DE AliExpress
7.30″ ePaper (F) 23434	170.20×111.20×0.91 160.00×96.00	BWRYBGO 800×480	35sec	X	X X	7.30in-f13	Amazon US Amazon DE AliExpress
7.50″ ePaper 13187	170.20×111.20×0.98 163.20×97.92	BW 800×480	4sec	0.4sec	ESP32 X	7.50in 7.50inV214 7.50inV2alt15 7.50inV2p16	Amazon US Amazon DE AliExpress
7.50″ ePaper (B) 13380	170.20×111.20×1.18 163.20×97.92	BWR 800×480	26sec	1.5sec	ESP32 X	7.50in-bV217 7.50in-bV318 7.50in-bV3-bwr19 7.50in-bc20	Amazon US Amazon DE AliExpress
13.3″ ePaper (K) 25725	286.32×212.26×1.20 275.52×195.16	BW 960×680	5sec	0.7sec	ESP32 ESP8266	13.3in-k21	Amazon US Amazon DE AliExpress

When choosing an e-ink display, your first decision is the desired color capability. More colors typically mean slower refresh times. While some screens offer partial refresh to mitigate this, it’s a feature that doesn’t always perform reliably and adds to the full refresh time of the screen.

The next decision you’ll make is the display size. For small e-paper displays acting as single-device status boards in your smart home, a 1.5-3″ screen will suffice. However, if you plan to showcase full dashboards with multiple data sensors, you should consider screens ranging from 4-13.3″.

Finally, you’ll need to account for the price of Waveshare e-paper displays. As e-paper screens are quite costly, expenses can quickly add up, especially if you’re deploying several large units with their associated driver boards. Naturally, this is very individual thing and beyond the scope of this guide.

Waveshare ESP32 and ESP8266 Driver Boards

All Waveshare e-paper screens, with the exception of the 7.3″ 7-color model, are compatible with the official Waveshare ESP32 Driver Board. While some models also work with the ESP8266 version, I highly recommend getting the ESP32 version, as it’s similar in price, yet has superior performance.

Using these driver boards makes installation virtually plug-and-play: just connect the display’s flat cable to the board, and it’s ready for flashing. Whichever display you choose to use with the official driver boards, it will always have the following PIN configuration:

The next thing you need to figure out is setting the proper resistor configuration of the board. Both models have a small switch that you need to flick to the correct position according to your e-paper screen model. On both boards, this can be either A or B, which correspond to the following Waveshare e-Paper displays:

Getting started with Waveshare and ESPHome

To get started with Waveshare and ESPHome, you simply need to plug the flat cable of the e-paper display to the ESP driver board. In my example, I am using the Waveshare ESP32 E-Paper Driver Board and a Waveshare 7.50″ ePaper (B) Tri-color display. Further, I am using the default ESPHome Display Component for this model, as I found LVGL causes more issues than it solves and development is not there yet.

The ESP32 Board is initialized just like any other ESP board in ESPHome, with the basic configuration remaining the same. The core functionality involves defining the waveshare_epaper component and spi connection, before anything can be rendered on screen. For example:

esphome:
  name: waveshare
  friendly_name: waveshare
.....
spi:
  clk_pin: GPIO13
  mosi_pin: GPIO14
display:
  - platform: waveshare_epaper
    id: waveshare
    model: 7.50in-bV3-bwr #Version 3 of the 7.50" (B) e-Paper Display, supports B/W/R rendering.
    cs_pin:
      number: GPIO15
      ignore_strapping_warning: True
    dc_pin: GPIO27
    busy_pin: 
      number: GPIO25
      inverted: true
    reset_pin: GPIO26
    lambda: |-
.....

On this board, GPIO15 is a strapping pin. These pins are read by the chip during a power-on reset to configure its initial operation, such as enabling bootstrap (flashing) mode or setting the operating voltage. By adding ignore_strapping_warning: true, I am telling ESPHome to ignore the warning.

Further, the Busy PIN on the Waveshare 7.30in-f, Waveshare 7.50inV2 and V3 models must be inverted to prevent permanent display damage. Do not forget to set this parameter, otherwise you might experience issues and cause screen damage!

Defining Colors

The next step is to define colors in the ESPHome configuration. These need to have a unique ID, which will be called upon in the lambda function to render components on the screen. You can define them in HEX or RGB, check out the ESPHome display colors documentation. For my particular tri-color display:

color:
  - id: color_black
    red: 100%
    green: 100%
    blue: 100%
    white: 100%
  - id: color_red
    red: 100%
    green: 0%
    blue: 0%
    white: 0%

You will notice the background color, which is white, is not defined. This is because there is no need to define and use it, the screen fills everything with white when there is no color set in the lambda.

Adding Fonts

The next step is to add some fonts which ESPHome can use to render text and sensor data on the display. ESPHome has a very capable and versatile Font Renderer Component, which allows multiple fonts to be used from a variety of sources. You can even upload and host them locally. For example:

font:
  - file:
      type: gfonts
      family: Source Code Pro
      weight: 700
    id: font_roboto
    size: 26
  - file: "gfonts://Roboto"
    id: roboto_20
    size: 20

Adding Icons

If you are looking to create a rich dashboard with material design icons, the simplest way is to add and define each icon manually as an image. You need to define the type, which can be either binary, grayscale, rgb or rgb565 and set an icon size. The downside of this approach is that you cannot change the color and size in the lambda, which means you would need to add the same icon several times if you intend to use it in a different color or dimension. For example:

image:
  - file: mdi:alert-outline
    type: binary
    id: alert
    resize: 80x80
.....

# TO RENDER
display:
  - platform: waveshare_epaper
    id: waveshare
.....
    lambda: |-
      it.image(400, 200, id(alert));

Alternatively, you can load the material design icons font file manually and map the icons you need in the lambda. Weatherman by Madelena is a great example of this implementation, it looks something like this:

font:
  - file: "fonts/materialdesignicons-webfont.ttf" #Hosted locally, adjust the path if needed
    id: material_icons
    size: 60 # Adjust size as needed
    glyphs: &mdi-weather-glyphs
          - "\U000F0599" # mdi-weather-sunny #Define as many icons as needed
.....
display:
  - platform: waveshare_epaper
    id: waveshare
.....
    lambda: |-
      // Map weather states to MDI characters.
      std::map<std::string, std::string> weather_icon_map
        {
          {"sunny", "\U000F0599"}, #Map as many icons as needed
        };
      it.print(5, 300, id(material_icons), id(color_black), weather_icon_map["sunny"].c_str());

Adding Images

The last use case you might want to consider is rendering actual images on your Waveshare display. While images are not really suitable for e-paper screens, they can be rendered if needed. You can upload your own image and render it on the display. For example:

image:
  - file: "fonts/smarthomescene-logo-black.jpg"
    type: binary
    id: logo
    resize: 250x250
    invert_alpha: true
.....
display:
  - platform: waveshare_epaper
    id: waveshare
.....
    lambda: |-
      it.image(100, 500, id(logo));

Now, when you send a full-color or even grayscale image to such a display, it has to significantly simplify the image data, essentially guessing whether each tiny dot should be black, white, or red. This causes the image to be displayed in all black, not displayed at all or distorted significantly.

There are ways to get around this, but in the end it will only be displayed in the 3 colors the e-paper display is actually capable of rendering. Therefore, the most effective solution is to prepare your image beforehand to match the display’s capabilities precisely. This involves opening your image and converting it to a pure black and white (1-bit) image. Ensure there are absolutely no shades of gray, no anti-aliasing, and that the background is a solid white, not transparent. The colors of the image can be inverted by setting invert_alpha: true. This is especially useful for manipulating images on e-paper displays.

Configuring Refresh Rate

E-Paper (E-Ink) displays typically have a slow refresh rate. As explained earlier, this is because their underlying technology relies on the physical movement of charged pigment particles to form an image or render text. Because of this, it’s good practice to lower the full refresh rate of the display as much as possible to suit your use case. Alternatively, if your Waveshare display supports it, you can implement the partial refresh feature.

You can control how your display updates using several options. E-paper displays have two main modes: a quicker partial update that only changes the pixels that have actually changed, and a full update mode that first clears the entire screen before redrawing the whole image. The partial update is much faster and provides a smoother experience, but a full update is necessary every so often to clear away any lingering “ghosting” or artifacts that might build up over time.

Some specific Waveshare models, like the 1.54in, 1.54inv2, 2.13in, 2.13inv2, 2.90in, 2.90inv2, 7.50inV2p, and gdew029t5, allow you to set full_update_every to perform a full refresh only after a certain number of partial updates, defaulting to every 30 updates on these models, while others always do a full update.

The reset_duration option controls how long the display takes to perform its reset operation, which defaults to 200 milliseconds. However, setting this value to a shorter 2 milliseconds can help resolve common issues with newer e-Paper Driver modules, such as the Waveshare 7.50″ ePaper (B) Tri-color display. Finally, the update_interval determines how often the screen automatically redraws its contents, with a default of 1 second. If you prefer to have complete manual control over when the screen updates, you can set this to never and trigger updates only through a component.update command, which is useful for static displays or to conserve power. For example:

display:
  - platform: waveshare_epaper
    id: waveshare
    model: 7.50in-bV3-bwr
    reset_duration: 2ms
    update_interval: 300s #Update every 5 minutes
.....

Adjusting Rotation

You can easily orient your display to fit your physical setup using the rotation option. This setting will rotate everything you draw within the lambda section by your chosen degree, allowing for flexible display orientations such as 0° (the default), 90°, 180°, or 270°. This means you don’t have to adjust your drawing coordinates for different physical screen positions; you just set the rotation once, and ESPHome handles the rest. For example:

display:
  - platform: waveshare_epaper
    id: waveshare
    model: 7.50in-bV3-bwr
    rotation: 90 #Vertical display
.....

Rendering Content

With the ESPHome building blocks in place, you can start rendering contents on your Waveshare E-Paper Display. The ESPHome Display Rendering Engine is quite powerful, but complex. It can be a challenge to render exactly what you are trying to achieve. I found that in time, you get the hang of it and it becomes a matter of trial and error.

Displaying Home Assistant Sensor Data

Just like any other ESP32 project, Home Assistant sensor data can be pushed via ESPHome and showcased to a connected display. For my particular Waveshare Tri-color model, here’s a simple example:

sensor:
### Living Room ###
  - platform: homeassistant
    id: living_room_temperature
    entity_id: sensor.air_quality_living_room_temperature
    accuracy_decimals: 1
    unit_of_measurement: "°C"
  - platform: homeassistant
    id: living_room_humidity
    entity_id: sensor.air_quality_living_room_humidity
    accuracy_decimals: 1
    unit_of_measurement: "%"
......
display:
  - platform: waveshare_epaper
    id: waveshare
    model: 7.50in-bV3-bwr
......
    lambda: |-
      it.printf(5, 5, id(font_1), color_black, "Living Room:");
      it.printf(240, 5, id(font_1), color_red, "%.1f°C • %.1f%%", id(living_room_temperature).state, id(living_room_humidity).state);

Any Home Assistant Sensor can be pushed through ESPHome and displayed on these screens. It’s also good practice to set the refresh rate to never and think of a clever way for refreshing on demand. For example, say you want to update the screen only when motion or presence is detected in the vicinity. This practice ensures the display refreshes with current data only when you approach, staying dormant otherwise:

sensor:
### Living Room ###
  - platform: homeassistant
    id: living_room_temperature
    entity_id: sensor.air_quality_living_room_temperature
    accuracy_decimals: 1
    unit_of_measurement: "°C"
  - platform: homeassistant
    id: living_room_motion
    entity_id: binary_sensor.living_room_motion_sensor
    on_value:
      - then:
          component.update: waveshare
......
display:
  - platform: waveshare_epaper
    id: waveshare
    model: 7.50in-bV3-bwr
    rotation: 90
    reset_duration: 2ms
    update_interval: never
    lambda: |-
      it.printf(5, 5, id(font_1), color_black, "Living Room:");
      it.printf(240, 5, id(font_1), color_red, "%.1f°C • %.1f%%", id(living_room_temperature).state;

Weatherman by Madelena

Weatherman is a very popular project made by Madelena which uses ESP32 boards and Waveshare e-paper screens for displaying all kinds of data. It’s easy to implement and looks great once wall-mounted with a nice frame or a 3D printed enclosure. Weatherman uses the Waveshare 7.5″ two-color display instead of three and this simple photo frame to mount it on a wall.

Madelena’s code is very detailed and complete, implementing a weather dashboard via Home Assistant sensors. You will need to create some template sensors to pull weather data, or you can create your own and simply adopt the lambda used in Weatherman.

Final Thoughts

Working with e-ink or e-paper displays is trickier compared to LCD or AMOLED panels. If you are interested in a process comparison, I highly suggest your check out this DIY Info Display with LILYGO T-Display-S3 in ESPHome.

On the other hand, true e-paper displays, such as those from Waveshare, produce a clear paper-like image viewable from all angles. There are no distortions, glares or glow when the room gets dark. They are beautiful to look at and are a great fit for wall-mounted status dashboards.

With ESPHome as the powerhouse driving such a display and the simplicity of a plug-and-play ESP32 board, the process becomes only a matter of writing the code. Hopefully, my examples gave you an idea of where and how to start. In this guide, this is what I used:

Waveshare 7.5″ e-Paper Display (B)

Red, Black, White

800×480

Fast: 16s, Full: 26s

ESPHome

Amazon USAmazon DE

Waveshare ESP32 Driver Board

Bluetooth 4.2, Wi-Fi 2.4GHz

3-wire SPI, 4-wire SPI

29.46×48.25mm

ESPHome

Amazon USAmazon DE