Waveshare e-Paper no display - help please

I have a Waveshare 4.2inch v2 display (Labels on rear: 024RW-Z98 and 2024032101) and the Waveshare ESP32 driver board but cannot get anything at all to display when using ESPHome.

I’m pretty sure it is not hardware related as I’ve substitued the screen and driver board (individually and together) and tried all three 4.2 inch drivers in the yaml. I have also tried connecting the screen directly to the driver board - and via the extension, and the switch in both A and B positions.

I am probably missing something obvious so really would appreciate any help you could provide.

The yaml:

esphome:
  name: "display-epaper01"
  friendly_name: Display-epaper01

esp32:
  board: esp32dev
  framework:
    type: arduino

logger:

api:
ota:
  - platform: esphome

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

captive_portal:

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

font:
  - file: '/config/Fonts/Comic Sans MS.ttf'
    id: font1
    size: 20

spi:
  clk_pin: GPIO13
  mosi_pin: GPIO14

display:
  - platform: waveshare_epaper
    id: waveshare
    cs_pin:
      number: GPIO15
      ignore_strapping_warning: True        
    dc_pin: GPIO27
    busy_pin: 
      number: GPIO25
    reset_pin: GPIO26
    reset_duration: 2ms
    model: 4.20in-bV2-bwr
#    model: 4.20in-bV2
#    model: 4.20in
    update_interval: 60s
    lambda: |-
      it.printf(25, 25, id(font1), color_black, "Hello World:");

What happens if you leave the color_black out of your print statement?

Thanks for your response, @zoogara ! I have tried that and variations of colour statements such as color_red, id(color_black), and Color::BLACK

At no time have I had any indication of any text or anything else on the screen - it is almost as if the screen is disconnected or powered off (or I have two faulty screens or two faulty driver boards - but I think that unlikely!)

For the my waveshare 7.5 inch BWR I use COLOR_ON or no color parameter. Since the last does not work I assume that is not it. Unless, some drivers at some point had colors inverted. For white I use all components set to 0, even the white component.

I have a 7.5 inch, which has busy pin inverted. That differs per device and should not be set the wrong way as in the long term that might cause problems. But it does not hurt to try to change it, the effect is only after prolonged use.

In case there’s something about the font I’d put in filled rectangles in various colors.

How is the display connected? With the 7.5 I got a board to go between that I did not need. I put the band cable in directly. Are you sure it is in the right way and clamped tight using the lever? Is your power supply adequate? Do you see any kind of refresh cycle when powering on?

What does the log say when running?

Not sure if it should matter, but did you include the device in HA? You did enable the api.

Thanks for your response, @Edwin_D

I have tried inverting the busy pin - it made no difference, unfortunately.

I have the desplay connected by the ribbon cable directly into the driver board with the metallic side up (it arrived with the extension cable installed that way up) - I did try it the other way, too

There is no refresh cycle - or any other indication of life on the display - it is as if it is not powered at all.

I hadn’t thought about font issues so tried the shapes as you suggested and, again, no display at all.

The logs don’t show any display-related entries (except the one about taking a long time, that I gather is not unusual)

Yes, I did include the device in HA and the power supply is a 2A one that should be adequate.

You mention a COLOR_ON or no color parameter - I have not seen this documented; how is it used? Where is it entered?

Thanks again!

That all sounds pretty normal, except for no refresh cycle. Without that nothing will show.

The log saying display takes long is happening for me too, and indicates it does try to call the display function.

The COLOR_ON is defined by ESPHome I think for displays that use a single bit instead of color values as pixels. Even the 3 color display actually uses two display buffers in bits, one for black and one for red.

Are you sure the board is what you configured, a three color waveshare display? The two color is different. I cannot find the type numbers you mention online.

Waveshare doesn’t have any demo code for it? Arduino code?

This is what I ordered and it looks like that - but I haven’t seen it working yet to confirm the colours available! 400x300, 4.2inch E-Ink raw display, three-color, SPI interface, without PCB | WFT0420CZ15

I have update defined - I presume this is what you mean by refresh? I have dropped it in stages all the way to 1S and there is no display. I’ve also used component.update: but, again, no display.

I shall have to do that - I only really know ESPHome development environment so was trying to avoid the learning curve of their code as it is very different - but it looks like I’ll need to.

There’s likely not so much of l-curve to upload a demo code to see if it’s alive. If yes, you know you need to work on esphome, if not, you probably have hw issue.

I have this exact display and it appears ESPHome fully supports it…and, it appears the OP got it to build. But, when I go to try and build my project I get the following error:

Unknown value ‘4.20in-bv2-bwr’

It recognizes all the other versions, but for some reason it doesn’t seem to recognize the bwr version. I have the latest ESPHome version installed on the latest Home Assistant version (everything is up to date). So I’m not sure why it is not recognizing this particular model when according to ESPHome documents, this model is supported.

If anyone has a clue to what I’m missing here, please let me know. Thanks…

Try capital V: 4.20in-bV2-bwr. That’s what’s in the docs, maybe it makes a difference.

Otherwise share your yaml.

Sorry…that’s what the compiler error showed. My actual yaml is

substitutions:
  .....
  display_model:  4.20in-bV2-bwr
  display_width:  400
  display_height: 300
  display_rotation: 270

The model was a copy paste from the displayed value on the ESPHome WaveShare ePaper component page…just to make sure I absolutely knew it was the exact same text (thinking maybe I just goofed somewhere). So good catch, but unfortunately not applicable.

I should probably also mention that my code works perfectly fine (and has been for over a month) with the following:

substitutions:
  .....
  display_model:  2.90in3c
  display_width:  296
  display_height: 128
  display_rotation: 270

Of course that IS with a WeAct Studio 2.9" 3-Color display. My goal was to go to the WeAct Studio 4.2" 3-Color display so I didn’t need to rotate between 3 different views and instead place all 3 views on the same screen simultaneously (and then reduce the update time by a third). So code wise I know the rest of it works.

What I failed to mention here is that this is a WeAct Studio display and not a WaveShare display. Why I failed to mention that (and why I thought it was the same) was because the 2.9" WeAct Studio display is supported under the WaveShare ePaper component (although the ‘2.90in3c’ model isn’t shown on that page) and I made the bad assumption that therefore the 4.2" would be the same.

So even if I do get the 4.20in-bV2-bwr to get recognized by the compiler, I’m not sure it’ll make a difference here unfortunately. I say this because I also have a 4.2" WeAct Studio BW display and the ‘4.20in-bV2’ model is recognized and compiles as well as ‘4.20in’ (for some reason ‘gdey042t81’ is another 4.2" model listed though that also causes an unknown variable compile error). Anyway, switching to the BW screen showed that the WaveShare model is NOT compatible with the WeAct Studio model (unless I just have a bad BW display) and therefore support for what I have needs to actually be implemented (like a 4.20in3c model).

And yes…just yesterday I submitted to the ESPHome GitHub project this request since I think it was just last year that the 2.9" WeAct Studio was requested and eventually implemented. At the same time I mentioned in that request that the ‘4.20in-bV2-bwr’ model was getting an unknown variable error in the build (even though that probably wasn’t the best place to add that info to).

Until Espressif (or whoever does ESPHome development) does an actual implementation for WeAct Studio 4.2" displays, I’d still like to at least try the ‘4.20in-bV2-bwr’ model just to make sure it doesn’t work (and of course figure out why in my case the compiler doesn’t recognize this particular model where apparently for others it does).

OMG…I feel really stupid.

In order to get the 2.9" WeAct Studio screen working I had to use

external_components:
  - source: github://pr#6226
    components: [waveshare_epaper]

Simply commenting that out gets the compiler to recognize the ‘4.20in-bV2-bwr’ model.

I REALLY should’ve had that code up top near the model definitions and instead I had it buried down by the display section at which point I obviously forgot it was there…

I only discovered that because pr#6209 is a possible temporary fix for the 4.2" WeAct Studio display (I think BW only) and when I put that external_component section in, the compiler complained that I had already had one of those and well…it quickly became obvious what was happening.

1 Like

And for anyone who runs across this…using the following works for the 4.2" BW (only) WeAct Studio ePaper display (now that I worked out what I was doing wrong):

substitions:
  display_model: 4.20in-v2
  display_width:  400
  display_height: 300
  display_rotation: 0

external_components:
  - source: github://pr#6209
    components: [ waveshare_epaper ]

I am still trying to find somewhere the ability to do the BWR (3-Color) model now. My display used red in various ways (like a red sun vs. just plain black). Still, I’m happy I’ve gotten as far as I have (and sorry this is posted in the ‘Waveshare e-Paper’ post…although it’s very likely other WeAct Studio users will run across this as I had, hence why I thought it good to at least post the solution I eventually came across for the BW display).

This is my current setup on ESPHome 2025.7.4 that works with a Waveshare 4.2 inch e-Paper Module Rev 2.1 and V2 sticker on the PCB

...

esp32:
  board: wemos_d1_mini32
  framework:
    type: arduino

spi:
  clk_pin: GPIO19
  mosi_pin: GPIO23

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

font:
  - file:
      type: gfonts
      family: "IBM Plex Sans Condensed"
      weight: 700
    id: ibm_20
    size: 24

display:
  - platform: waveshare_epaper
    id: waveshare
    model: 4.20in-bv2-bwr
    update_interval: 360s #Update every 6 minutes
    cs_pin:
      number: GPIO18
    dc_pin: GPIO16
    busy_pin: 
      number: GPIO21
#      inverted: true
    reset_pin: GPIO17
    lambda: |-
      it.fill(color_white);
      it.printf(5, 5, id(ibm_20), color_black, "Hello World!");
      it.printf(5, 45, id(ibm_20), color_red, "Hello World!");