mcu-waveshare

Hard fork of epd-waveshare. This fork implements breaking changes to the API and focuses on memory-constrained microcontrollers by eliminating the need for full in-memory framebuffers. It also adds first-class support for async operations via embedded-hal-async.

Work in progress. Current changes are untested. This notice will be updated as the project matures.

This library contains a no_std driver for E-Paper (E-Ink) display modules from Waveshare (and compatible Dalian Good Display panels).

It uses the embedded-graphics-core library for graphics support.

A 2021-edition compatible version (Rust 1.75+) is needed.

Async SPI Support

Enable the async feature for Embassy/RTIC async SPI via embedded-hal-async:

[dependencies]
mcu-waveshare = { version = "0.6", features = ["async"] }

All 28 display drivers support both sync (default) and async modes.

Other similar libraries with support for much more displays are u8g2 and GxEPD for arduino.

Examples

There are multiple examples in the examples folder. Use cargo run --example example_name to try them.

use mcu_waveshare::{epd4in2::*, prelude::*, graphics::draw_fn};
use embedded_graphics::{prelude::*, mono_font::ascii::FONT_6X10, text::*};

// Setup the epd
let mut epd4in2 =
    Epd4in2::new(&mut spi, busy, dc, rst, &mut delay, None).expect("eink initalize error");

// Allocate a small band buffer (only 10 rows instead of the full display)
let mut buf = [0u8; WIDTH as usize / 8 * 10];

// Draw and display a frame using streaming rendering
epd4in2.update_frame(&mut spi, &mut delay, &draw_fn::<Color, _>(|display| {
    let style = MonoTextStyleBuilder::new()
        .font(&FONT_6X10)
        .text_color(Color::White)
        .background_color(Color::Black)
        .build();
    let text_style = TextStyleBuilder::new().baseline(Baseline::Top).build();
    let _ = Text::with_text_style("It's working-WoB!", Point::new(175, 250), style, text_style)
        .draw(display);
}), &mut buf).expect("display error");
epd4in2.display_frame(&mut spi, &mut delay).expect("display error");

// Going to sleep
epd4in2.sleep(&mut spi, &mut delay)

The draw_fn closure is called once per band as the display streams data to the e-paper. Only the band buffer needs to fit in RAM, not the full framebuffer.

Check the complete example here.

(Supported) Devices

Device (with Link)	Colors	Flexible Display	Partial Refresh	Supported	Tested
7.5 Inch B/W/R V2/V3 (B)	Black, White, Red	✕	✕	✔	✔
7.5 Inch B/W HD (A)	Black, White	✕	✕	✔	✔
7.5 Inch B/W V2 (A) [1]	Black, White	✕	✕	✔	✔
7.5 Inch B/W (A)	Black, White	✕	✕	✔	✔
7.3 Inch HAT (F)	Black, White, Red, Green, Blue, Yellow, Orange	✕	✕	✔	✔
5.83 Inch B/W/R (b)	Black, White, Red	✕	Not officially	✔	✔
5.65 Inch 7 Color (F)	Black, White, Red, Green, Blue, Yellow, Orange	✕	✕	✔	✔
4.2 Inch B/W (A)	Black, White	✕	Not officially [2]	✔	✔
2.13 Inch B/W (A) V2	Black, White	✕	✔	✔	✔
2.13 Inch B/W/R (B/C) V2	Black, White, Red	✕	✕	✔	✔
2.9 Inch B/W/R (B/C)	Black, White, Red	✕	✕	✔	✔
2.9 Inch B/W (A)	Black, White	✕	✔	✔	✔
2.9 Inch B/W V2 (A)	Black, White	✕	✔	✔	✔
2.7 Inch 3 Color (B)	Black, White, Red	✕	✔	✔	✔
2.7 Inch B/W V2	Black, White	✕	(✔)	✔	✔
2.66 Inch 3 Color (B)	Black, White, Red	✕	✕	✔	✔
1.54 Inch B/W/Y (C) (Discontinued)	Black, White, Yellow	✕	✕	✔	✔
1.54 Inch B/W/R (B)	Black, White, Red	✕	✕	✔	✔
1.54 Inch B/W (A)	Black, White	✕	✔	✔	✔

[1]: 7.5 Inch B/W V2 (A)

Since November 2019 Waveshare sells their updated version of these displays. They should have a "V2" marking sticker on the backside of the panel.

Use epd7in5_v2 instead of epd7in5, because the protocol changed.

[2]: 4.2 Inch E-Ink Black/White - Partial Refresh

Out of the Box the original driver from Waveshare only supports full updates.

That means: Be careful with the quick refresh updates:
It's possible with this driver but might lead to ghosting / burn-in effects therefore it's hidden behind a feature.

Interface

Interface	Description
VCC	3.3V
GND	GND
DIN	SPI MOSI
CLK	SPI SCK
CS	SPI chip select (Low active)
DC	Data/Command control pin (High for data, and low for command)
RST	External reset pin (Low for reset)
BUSY	Busy state output pin (Low for busy)

Display Configs

There are two types of Display Configurations used in Waveshare EPDs, which also needs to be set on the "new" E-Paper Driver HAT. They are also called A and B, but you shouldn't get confused and mix it with the Type A,B,C and D of the various Displays, which just describe different types (colored variants) or new versions. In the Display Config the separation is most likely due to included fast partial refresh of the displays. In a Tabular form:

Type A	Type B
1.54in (A)	1.54in (B)
2.13in (A)	1.54in (C)
2.13in (D)	2.13in (B)
2.9in (A)	2.13in (C)
	2.7in (A)
	2.7in (B)
	2.9in (B)
	2.9in (C)
	4.2in (A)
	4.2in (B)
	4.2in (C)
	7.5in (A)
	7.5in (B)
	7.5in (C)