waveshare-epaper — Rust driver for Waveshare e-Paper HATs

Rust driver support for the Waveshare 5.83" e-Paper HAT V2, built around the current Waveshare demo flow and embedded-hal 1.0 traits.

Features

• SPI/GPIO driver for the 5.83" V2 display
• Optional async driver API via embedded-hal-async
• Standard, fast, partial, and 4-gray initialization flows
• Full-frame, partial-frame, clear, and sleep operations
• Higher-level MonoImage abstraction for packed full-frame rendering
• Pure framebuffer packing helper for 1-bit images
• Criterion benchmark for bitmap packing
• Optional rppal integration for Raspberry Pi Linux targets

Support Matrix

Displays / HATs

• Waveshare 5.83" e-Paper HAT V2: supported
• Other Waveshare e-Paper panels/HATs: not yet implemented in this crate

Host Boards / Platforms

• Raspberry Pi (Linux) via rppal: supported (example included)
• Generic embedded targets with embedded-hal 1.0 SPI/GPIO/delay implementations: supported
• Desktop simulation/testing with fake HAL backends: supported for protocol validation

Driver API Levels

• Synchronous driver (Epaper583V2): supported
• Asynchronous driver (Epaper583V2Async, feature async): supported
• High-level full-frame mono abstraction (MonoImage): supported

Update Modes

• Normal init + full refresh: supported
• Fast init: supported
• Partial init + partial window updates: supported
• 4-gray init + 4-gray frame path: supported

Public API

The crate exports a small surface area:

• Epaper583V2 for SPI/GPIO control of the display
• InitMode for choosing the Waveshare initialization flow
• pack_mono_bitmap and packed_mono_len for preparing 1-bit frames
• MonoImage for higher-level full-frame mono workflows
• DriverError and FramePackingError for fallible operations
• ThreadDelay as a simple std-backed delay implementation for examples and tests

Hardware notes

This crate follows the Waveshare 5.83" V2 manual and demo code.

• Resolution: 648 × 480
• Interface: SPI mode 0
• Control pins: DC, RST, BUSY, and PWR
• The Waveshare demo drives PWR high during initialization and low on sleep

Compatibility note:

• Command timings and register sequences are tuned for 5.83" V2 behavior and may not be correct for other controller variants.

Usage

use rppal::gpio::Gpio;
use rppal::spi::{Bus, Mode, SlaveSelect, Spi};
use waveshare_epaper::{Epaper583V2, ThreadDelay, MONO_FRAME_BYTES};

let spi = Spi::new(Bus::Spi0, SlaveSelect::Ss0, 2_000_000, Mode::Mode0)?;
let gpio = Gpio::new()?;

let busy = gpio.get(24)?.into_input();
let dc = gpio.get(25)?.into_output();
let rst = gpio.get(17)?.into_output();
let pwr = gpio.get(18)?.into_output();

let mut display = Epaper583V2::new(spi, busy, dc, rst, pwr, ThreadDelay);
display.initialize()?;

let frame = [0xFFu8; MONO_FRAME_BYTES];
display.display_frame(&frame)?;
display.sleep()?;

For higher-level frame preparation from a byte-per-pixel bitmap:

use waveshare_epaper::{MonoImage, Epaper583V2};

# fn show<SPI, BUSY, DC, RST, PWR, DELAY>(
#     display: &mut Epaper583V2<SPI, BUSY, DC, RST, PWR, DELAY>,
#     source: &[u8],
# ) -> Result<(), waveshare_epaper::DriverError<(), ()>>
# where
#     SPI: embedded_hal::spi::SpiBus<u8, Error = ()>,
#     BUSY: embedded_hal::digital::InputPin<Error = ()>,
#     DC: embedded_hal::digital::OutputPin<Error = ()>,
#     RST: embedded_hal::digital::OutputPin<Error = ()>,
#     PWR: embedded_hal::digital::OutputPin<Error = ()>,
#     DELAY: embedded_hal::delay::DelayNs,
# {
let image = MonoImage::from_bitmap(source)?;
display.display_image(&image)?;
# Ok(())
# }

Enable the Raspberry Pi example with:

cargo run --example rppal_full_refresh --features rppal

Enable async support with:

cargo test --features async

Development

cargo test
cargo bench

The test suite covers the framebuffer packing helpers, initialization command sequences, partial-update validation, and sleep behavior.

Documentation Book

This repository includes an mdBook source under docs/.

Build it with:

mdbook build

Serve it locally with live reload:

mdbook serve

You can also generate crate API docs with:

cargo doc --no-deps --open

Repository Docs and AI Guidance

The repository includes additional markdown-first structure commonly used in modern projects:

• .github/copilot-instructions.md: repository-wide Copilot guidance
• .github/instructions/*.instructions.md: path-specific AI instructions
• AGENTS.md: agent-oriented repository guidance
• docs/adr/: architecture decision records and templates
• docs/runbooks/: developer runbooks
• docs/operations/: operational/release process docs
• CONTRIBUTING.md: contributor workflow and expectations
• CHANGELOG.md: Keep a Changelog style release notes