https://github.com/palemoky/paper-pi
A personalized, asynchronous dashboard for Waveshare E-Ink displays, built with Python and Docker.
https://github.com/palemoky/paper-pi
eink epaper raspberry-pi waveshare
Last synced: 2 months ago
JSON representation
A personalized, asynchronous dashboard for Waveshare E-Ink displays, built with Python and Docker.
- Host: GitHub
- URL: https://github.com/palemoky/paper-pi
- Owner: palemoky
- License: gpl-3.0
- Created: 2025-11-21T12:38:19.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T07:59:44.000Z (3 months ago)
- Last Synced: 2026-04-08T09:31:33.753Z (3 months ago)
- Topics: eink, epaper, raspberry-pi, waveshare
- Language: Python
- Homepage:
- Size: 22.2 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Powered by Pi, rendered in Pixels.
# Paper Pi
[](https://github.com/palemoky/paper-pi/actions)
[](https://hub.docker.com/r/palemoky/paper-pi)
[](https://github.com/palemoky/paper-pi)
[](https://www.python.org/)
[](https://github.com/palemoky/paper-pi)
A modern, modular, and highly customizable dashboard for Waveshare E-Ink displays. Built with Python 3.14+ using async/await patterns and a clean, testable architecture.
## 🚀 Quick Start with Docker
The easiest way to run is using Docker - it handles all dependencies and driver setup automatically.
## Screenshots
### 📊 Dashboard
| Todo | HackerNews |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|  |  |
### 🥷 Other Modes
| Quote | Poetry | Wallpaper | Year-End Summary |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|  |  |  |  |
### 🎉 Special Days
| Happy Birthday | Anniversary | Valentine's Day |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|  |  |  |
| Happy New Year | Spring Festival | Mid-Autumn Festival | Christmas |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|  |  |  |  |
### Pull and Run
```bash
# Pull the latest image
docker pull palemoky/paper-pi:latest
# Or use GitHub Container Registry
docker pull ghcr.io/palemoky/paper-pi:latest
# Run with docker-compose (recommended)
git clone https://github.com/palemoky/paper-pi.git
cd paper-pi
cp .env.example .env
# Edit .env with your API keys
# For dashboard/quote/wallpaper modes (default)
docker-compose up -d
# For poetry mode (includes poetry-api service)
docker-compose --profile poetry up -d
```
> **Note**: The `poetry-api` service is optional and only needed when using `DISPLAY_MODE=poetry`. For other modes (dashboard, quote, wallpaper), you can run without the poetry profile to save resources.
### Supported Platforms
- `linux/arm64` - Raspberry Pi 3/4/5 (64-bit)
## ✨ Features
### 📊 Dashboard Widgets
- **Custom To-Do Lists** - Three customizable lists (Goals/Must/Optional) with strikethrough for completed items
- **HackerNews** - Auto-rotating top stories with pagination and configurable display time ([Live Mirror](https://gist.github.com/palemoky/b04f3dcfb8431784cddc648d1af6dd4c))
- **Real-time Weather** - OpenWeatherMap integration with icon support
- **GitHub Contributions** - Daily/Weekly/Monthly/Yearly stats with grid layout
- **Bitcoin Price** - Live BTC price with 24h change percentage
- **VPS Data Usage** - Monitor your server's data consumption
- **Weekly Progress** - Visual progress ring for the current week
### 🎨 Display Modes
- **Dashboard** - Main information display with time-based TODO/HN switching
- **Quote** - Inspirational quotes
- **Poetry** - Classical Chinese poetry
- **Holiday Greetings** - Auto-triggered on special days
- **Wallpaper** - Custom images
### 🎉 Smart Features
- **Year-End Summary** - Automatic GitHub contribution summary on Dec 31st
- **Holiday Detection** - Auto-displays greetings for:
- Birthdays & Anniversaries (configurable)
- Lunar New Year (Spring Festival)
- Mid-Autumn Festival
- New Year's Day & Christmas
- **Time-based Switching** - Configurable time slots for TODO lists vs HackerNews
- **Quiet Hours** - Configurable sleep period (e.g., 1 AM - 6 AM)
- **Grayscale Support** - 4-level grayscale for enhanced visual quality (white/light gray/dark gray/black)
- **Audio Notifications** - [Xiaomi speaker](https://github.com/palemoky/xiaomi-speaker) [integration](https://github.com/palemoky/xiaomi-speaker-action) for alerts and announcements
### 🏗️ Modern Architecture
- **Async/Await** - Built with `asyncio` and `httpx` for concurrent operations
- **Modular Design** - 23+ focused modules following Single Responsibility Principle
- **Type Safety** - Full type hints with mypy validation
- **Plugin System** - Extensible display mode system
- **Event Bus** - Decoupled component communication
- **Smart Caching** - TTL-based caching with LRU eviction
- **Unified Retry** - Automatic retry with exponential backoff using `tenacity`
- **Task Management** - Async task lifecycle management
- **Config Hot Reload** - Runtime configuration updates with `watchdog`
- **Graceful Shutdown** - Proper SIGTERM/SIGINT handling
### 🧪 Quality & Testing
- **Unit Tests** - 90+ tests with 66% overall coverage
- **Core Modules** - 77%+ coverage on critical components
- **CI/CD** - Automated testing, type checking, and Docker builds via GitHub Actions
- **Type Checking** - Full mypy validation with strict mode
- **Code Quality** - Ruff linting and formatting
- **Pre-commit Hooks** - Automated code quality checks before commits
- **Mock System** - CLI tool for generating test images without hardware
## 🏛️ System Architecture
The E-Ink Dashboard follows a modular, event-driven architecture with clear separation of concerns:
```mermaid
flowchart LR
%% --- Style Definition ---
classDef control fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
classDef data fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;
classDef render fill:#fff3e0,stroke:#e65100,stroke-width:2px;
classDef hw fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;
classDef subBox fill:#ffffff,stroke:#90a4ae,stroke-width:1px,stroke-dasharray: 5 5;
%% --- 1. Control Layer ---
subgraph ControlLayer ["🎮 Core & Control"]
direction TB
Main("Main Orchestrator")
Config("Config & Hot Reload")
DisplayCtrl{{"Display Controller"}}
TaskMgr("Task Manager")
end
%% --- 2. Data Layer ---
subgraph DataLayer ["📡 Data Acquisition"]
direction TB
Fetcher("Data Fetcher")
subgraph Providers ["Providers"]
External["External APIs
(Weather, GitHub, BTC, HN)"]
Local["Local Info
(Quotes, Poetry, TODO)"]
end
subgraph Storage ["State Management"]
Cache[("Cache (TTL/LRU)")]
State[("Persistence DB")]
end
end
%% --- 3. Render Layer ---
subgraph RenderLayer ["🎨 Rendering Engine"]
direction TB
ImgBuilder("Image Builder")
subgraph Strategies ["Layout Strategies"]
DashLayout["Dashboard Layout"]
ContextLayouts["Context Layouts
(Holiday, Quote, Poetry)"]
end
Renderer["Primitive Renderers
(Text, Icons, Shapes)"]
end
%% --- 4. Hardware Layer ---
subgraph HWLayer ["🖥️ Hardware Output"]
direction TB
DriverFac("Driver Factory")
EPD["E-Paper Driver"]
Mock["Mock (PNG)"]
end
%% --- Connection Logic ---
%% Control Flow
Main --> Config & TaskMgr
Main --> DisplayCtrl
Config -.-> Main
%% Data Flow
Main --"Trigger"--> Fetcher
Fetcher --> External & Local
External & Local -.-> Storage
%% Render Flow
DisplayCtrl --"Select Mode"--> ImgBuilder
ImgBuilder --"Get Data"--> Storage
ImgBuilder --> DashLayout & ContextLayouts
DashLayout & ContextLayouts --> Renderer
%% Output Flow
Renderer --> DriverFac
DriverFac --> EPD & Mock
%% --- Application Style ---
class Main,Config,DisplayCtrl,TaskMgr control
class Fetcher,External,Local,Cache,State data
class ImgBuilder,DashLayout,ContextLayouts,Renderer render
class DriverFac,EPD,Mock hw
class Providers,Storage,Strategies subBox
```
## 🖥️ Hardware Support
- **Primary**: Waveshare 7.5inch E-Paper HAT (V2)
- **Other Models**: Configurable via `EPD_MODEL` env var (supports most models in the [official repo](https://github.com/waveshareteam/e-Paper))
- **Platform**: Raspberry Pi (Zero/3/4/5) or any Linux board with SPI/GPIO
## 🙏 Acknowledgments
- [Antigravity](https://antigravity.google/) for the pair programming
- [Waveshare](https://www.waveshare.com/) for E-Ink display drivers
- [Chinese Poetry](https://github.com/chinese-poetry/chinese-poetry), [LxgwWenKai](https://github.com/lxgw/LxgwWenKai), [Hanyi](https://hanyi.com.cn/) for poetry
- [Flaticon](https://www.flaticon.com/), [Weather Icons](https://github.com/erikflowers/weather-icons) for icons
- [CoinGecko](https://www.coingecko.com/) for BTC price
- [OpenWeatherMap](https://openweathermap.org/) for weather
- [Figma](https://www.figma.com/) for UI design
- All the open-source libraries that make this project possible