A modern C++23 library for controlling Waveshare e-paper displays on Raspberry Pi with transparent sleep/wake management and clean architecture.
#include <epaper/device.hpp>
#include <epaper/display.hpp>
#include <epaper/drivers/epd27.hpp>
#include <epaper/font.hpp>
using namespace epaper;
int main() {
Device device;
device.init().value();
auto display = create_display<EPD27>(device, DisplayMode::BlackWhite,
Orientation::Landscape90).value();
display->clear(Color::White);
display->draw_string(20, 70, "Hello, libepaper!",
Font::font24(), Color::Black, Color::White);
display->refresh();
return 0;
}👉 See examples/ for complete applications including a real-time crypto dashboard!
- Modern C++23:
std::expected,std::span, concepts, and ranges - Transparent Sleep/Wake: Auto-sleep prevents burn-in, auto-wake on refresh—no manual management
- Clean Architecture: Modular design with RAII and composition over inheritance
- Full Drawing API: Points, lines, rectangles, circles, text, bitmaps with PNG/JPEG support
- Automatic Color Conversion: RGB images automatically converted to grayscale with intelligent quantization
- Multiple Display Modes: Black/white (1-bit) and 4-level grayscale (2-bit)
- Display Orientation: Rotate 0°, 90°, 180°, 270° with automatic coordinate transformation
- Extensible Drivers: Abstract driver interface for easy addition of new displays
- Type Safety: Strong typing with
std::expectederror handling - Zero-Cost Abstractions: Modern C++ with no runtime overhead
| Document | Description |
|---|---|
| Examples & Tutorials | Get started quickly with working examples |
| API Reference | Complete API guide with usage patterns |
| Architecture Guide | Deep dive into design, decisions, and diagrams |
| Driver Development | Write drivers for new displays |
Run the automated setup script:
./bin/setupOr manually install dependencies:
sudo apt install cmake g++-14 libgpiod-dev libcurl4-openssl-dev nlohmann-json3-dev pkg-config# Enable SPI interface
sudo raspi-config
# Interface Options → SPI → Enable
# Add user to gpio and spi groups (for GPIO/SPI access without sudo)
sudo usermod -a -G gpio,spi $USER
# Log out and back in for group changes to take effect| E-Paper Pin | Raspberry Pi GPIO |
|---|---|
| RST | GPIO 17 |
| DC | GPIO 25 |
| CS | GPIO 8 (CE0) |
| BUSY | GPIO 24 |
| MOSI | GPIO 10 (MOSI) |
| SCLK | GPIO 11 (SCLK) |
| GND | GND |
| VCC | 3.3V |
./bin/buildOr manually:
cmake -S . -B build -DCMAKE_CXX_COMPILER=g++-14
cmake --build build -j$(nproc)# Run crypto dashboard (live prices with charts)
./build/examples/crypto_dashboard/crypto_dashboard
# Run tests
./build/tests/test_auto_sleepNote: No sudo required! The library uses user-space GPIO access via libgpiod. Make sure you're in the gpio and spi groups (see step 2).
# Run all tests
cd build/tests
./run_all_tests.sh
# Run specific test
./test_auto_sleepSee tests/README.md for details.
We welcome contributions! This project uses Conventional Commits for clear history.
<type>(<scope>): <subject>
<body>
<footer>
Types:
feat: New featurefix: Bug fixdocs: Documentation changesstyle: Code formattingrefactor: Code refactoringperf: Performance improvementstest: Test additions/updateschore: Maintenance tasks
Scopes: device, driver, display, docs, examples, tests
feat(driver): add EPD42 display driver support
Implements the Driver interface for Waveshare 4.2" displays.
Supports both black/white and 4-level grayscale modes.
fix(display): correct auto-wake behavior in refresh()
The previous implementation didn't check is_asleep_ before refresh.
Now transparently wakes display if needed.
docs(readme): restructure documentation for clarity
- Fork and create a feature branch
- Follow project coding standards (run
./bin/format) - Add/update tests as needed
- Use conventional commit messages
- Update documentation
- Submit PR with clear description
Currently Implemented:
- Waveshare 2.7" e-Paper Display (176×264 pixels)
Easy to Extend: The abstract driver interface makes it straightforward to add support for other displays. See docs/DRIVER.md for a guide to writing new drivers.
- C++23 capable compiler (GCC 14+ or Clang 18+)
- CMake 3.25+
- libgpiod library (user-space GPIO access)
- Raspberry Pi with SPI enabled
- User in
gpioandspigroups (no sudo required)
libepaper/
├── include/epaper/ # Public API headers
│ ├── device.hpp # Hardware abstraction
│ ├── display.hpp # High-level display API
│ ├── drivers/ # Driver interface & implementations
│ └── font.hpp # Font rendering
├── src/ # Implementation files
├── examples/ # Example applications
│ ├── bmp_debug_example/ # BMP export for debugging
│ └── crypto_dashboard/ # Real-time crypto price dashboard
├── tests/ # Test suite
├── docs/ # Comprehensive documentation
└── bin/ # Build and setup scripts
- Waveshare for the e-Paper hardware and original library
- libgpiod developers for modern Linux GPIO access
- stb_image library authors for image loading
MIT License - see LICENSE file for details.
Copyright (c) 2025 Johanns Gregorian
Getting Started? → Examples API Questions? → API Reference Architecture Deep Dive? → Architecture Guide Writing a Driver? → Driver Development