{"id":34830013,"url":"https://github.com/palemoky/paper-pi","last_synced_at":"2026-04-23T02:04:41.519Z","repository":{"id":325492963,"uuid":"1101266836","full_name":"palemoky/paper-pi","owner":"palemoky","description":"A personalized, asynchronous dashboard for Waveshare E-Ink displays, built with Python and Docker.","archived":false,"fork":false,"pushed_at":"2026-04-08T07:59:44.000Z","size":23230,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T09:31:33.753Z","etag":null,"topics":["eink","epaper","raspberry-pi","waveshare"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/palemoky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T12:38:19.000Z","updated_at":"2026-04-08T07:47:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/palemoky/paper-pi","commit_stats":null,"previous_names":["palemoky/eink-dashboard","palemoky/eink-panel"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/palemoky/paper-pi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palemoky%2Fpaper-pi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palemoky%2Fpaper-pi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palemoky%2Fpaper-pi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palemoky%2Fpaper-pi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/palemoky","download_url":"https://codeload.github.com/palemoky/paper-pi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palemoky%2Fpaper-pi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32162614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"online","status_checked_at":"2026-04-23T02:00:06.710Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eink","epaper","raspberry-pi","waveshare"],"created_at":"2025-12-25T15:47:22.316Z","updated_at":"2026-04-23T02:04:41.491Z","avatar_url":"https://github.com/palemoky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/logo.png\" alt=\"Logo\" height=\"100px\" /\u003e\n\nPowered by Pi, rendered in Pixels.\n\n# Paper Pi\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/palemoky/paper-pi/release.yml)](https://github.com/palemoky/paper-pi/actions)\n[![Docker Image Size](https://img.shields.io/docker/image-size/palemoky/paper-pi/latest)](https://hub.docker.com/r/palemoky/paper-pi)\n[![Test Coverage](https://img.shields.io/badge/coverage-66%25-green)](https://github.com/palemoky/paper-pi)\n[![Python](https://img.shields.io/badge/python-3.14-blue?logo=python\u0026logoColor=white)](https://www.python.org/)\n[![GitHub](https://img.shields.io/github/license/palemoky/paper-pi)](https://github.com/palemoky/paper-pi)\n\nA 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.\n\n\u003c/div\u003e\n\n## 🚀 Quick Start with Docker\n\nThe easiest way to run is using Docker - it handles all dependencies and driver setup automatically.\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/demo.webp\" alt=\"Device Demo\" width=\"70%\" /\u003e\n\u003c/div\u003e\n\n## Screenshots\n\n### 📊 Dashboard\n\n| Todo                                                                                                  | HackerNews                                                                                                        |\n| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ![Todo](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/dashboard-todo.png) | ![HackerNews](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/dashboard-hackernews.png) |\n\n### 🥷 Other Modes\n\n| Quote                                                                                         | Poetry                                                                                          | Wallpaper                                                                                             | Year-End Summary                                                                                                    |\n| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |\n| ![Quote](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/quote.png) | ![Poetry](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/poetry.png) | ![Wallpaper](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/wallpaper.png) | ![Year-End Summary](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/year_end_summary.png) |\n\n### 🎉 Special Days\n\n| Happy Birthday                                                                                      | Anniversary                                                                                               | Valentine's Day                                                                                                  |\n| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |\n| ![Birthday](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/birthday.png) | ![Anniversary](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/anniversary.png) | ![Valentine's Day](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/valentines_day.png) |\n\n| Happy New Year                                                                                            | Spring Festival                                                                                                   | Mid-Autumn Festival                                                                                                       | Christmas                                                                                             |\n| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| ![Happy New Year](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/new_year.png) | ![Spring Festival](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/spring_festival.png) | ![Mid-Autumn Festival](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/mid_autumn_festival.png) | ![Christmas](https://raw.githubusercontent.com/palemoky/paper-pi/main/docs/screenshots/christmas.png) |\n\n### Pull and Run\n\n```bash\n# Pull the latest image\ndocker pull palemoky/paper-pi:latest\n\n# Or use GitHub Container Registry\ndocker pull ghcr.io/palemoky/paper-pi:latest\n\n# Run with docker-compose (recommended)\ngit clone https://github.com/palemoky/paper-pi.git\ncd paper-pi\ncp .env.example .env\n# Edit .env with your API keys\n\n# For dashboard/quote/wallpaper modes (default)\ndocker-compose up -d\n\n# For poetry mode (includes poetry-api service)\ndocker-compose --profile poetry up -d\n```\n\n\u003e **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.\n\n### Supported Platforms\n\n- `linux/arm64` - Raspberry Pi 3/4/5 (64-bit)\n\n## ✨ Features\n\n### 📊 Dashboard Widgets\n\n- **Custom To-Do Lists** - Three customizable lists (Goals/Must/Optional) with strikethrough for completed items\n- **HackerNews** - Auto-rotating top stories with pagination and configurable display time ([Live Mirror](https://gist.github.com/palemoky/b04f3dcfb8431784cddc648d1af6dd4c))\n- **Real-time Weather** - OpenWeatherMap integration with icon support\n- **GitHub Contributions** - Daily/Weekly/Monthly/Yearly stats with grid layout\n- **Bitcoin Price** - Live BTC price with 24h change percentage\n- **VPS Data Usage** - Monitor your server's data consumption\n- **Weekly Progress** - Visual progress ring for the current week\n\n### 🎨 Display Modes\n\n- **Dashboard** - Main information display with time-based TODO/HN switching\n- **Quote** - Inspirational quotes\n- **Poetry** - Classical Chinese poetry\n- **Holiday Greetings** - Auto-triggered on special days\n- **Wallpaper** - Custom images\n\n### 🎉 Smart Features\n\n- **Year-End Summary** - Automatic GitHub contribution summary on Dec 31st\n- **Holiday Detection** - Auto-displays greetings for:\n  - Birthdays \u0026 Anniversaries (configurable)\n  - Lunar New Year (Spring Festival)\n  - Mid-Autumn Festival\n  - New Year's Day \u0026 Christmas\n- **Time-based Switching** - Configurable time slots for TODO lists vs HackerNews\n- **Quiet Hours** - Configurable sleep period (e.g., 1 AM - 6 AM)\n- **Grayscale Support** - 4-level grayscale for enhanced visual quality (white/light gray/dark gray/black)\n- **Audio Notifications** - [Xiaomi speaker](https://github.com/palemoky/xiaomi-speaker) [integration](https://github.com/palemoky/xiaomi-speaker-action) for alerts and announcements\n\n### 🏗️ Modern Architecture\n\n- **Async/Await** - Built with `asyncio` and `httpx` for concurrent operations\n- **Modular Design** - 23+ focused modules following Single Responsibility Principle\n- **Type Safety** - Full type hints with mypy validation\n- **Plugin System** - Extensible display mode system\n- **Event Bus** - Decoupled component communication\n- **Smart Caching** - TTL-based caching with LRU eviction\n- **Unified Retry** - Automatic retry with exponential backoff using `tenacity`\n- **Task Management** - Async task lifecycle management\n- **Config Hot Reload** - Runtime configuration updates with `watchdog`\n- **Graceful Shutdown** - Proper SIGTERM/SIGINT handling\n\n### 🧪 Quality \u0026 Testing\n\n- **Unit Tests** - 90+ tests with 66% overall coverage\n- **Core Modules** - 77%+ coverage on critical components\n- **CI/CD** - Automated testing, type checking, and Docker builds via GitHub Actions\n- **Type Checking** - Full mypy validation with strict mode\n- **Code Quality** - Ruff linting and formatting\n- **Pre-commit Hooks** - Automated code quality checks before commits\n- **Mock System** - CLI tool for generating test images without hardware\n\n## 🏛️ System Architecture\n\nThe E-Ink Dashboard follows a modular, event-driven architecture with clear separation of concerns:\n\n```mermaid\nflowchart LR\n    %% --- Style Definition ---\n    classDef control fill:#e1f5fe,stroke:#01579b,stroke-width:2px;\n    classDef data fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;\n    classDef render fill:#fff3e0,stroke:#e65100,stroke-width:2px;\n    classDef hw fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px;\n    classDef subBox fill:#ffffff,stroke:#90a4ae,stroke-width:1px,stroke-dasharray: 5 5;\n\n    %% --- 1. Control Layer ---\n    subgraph ControlLayer [\"🎮 Core \u0026 Control\"]\n        direction TB\n        Main(\"Main Orchestrator\")\n        Config(\"Config \u0026 Hot Reload\")\n        DisplayCtrl{{\"Display Controller\"}}\n        TaskMgr(\"Task Manager\")\n    end\n\n    %% --- 2. Data Layer ---\n    subgraph DataLayer [\"📡 Data Acquisition\"]\n        direction TB\n        Fetcher(\"Data Fetcher\")\n\n        subgraph Providers [\"Providers\"]\n            External[\"External APIs\u003cbr/\u003e(Weather, GitHub, BTC, HN)\"]\n            Local[\"Local Info\u003cbr/\u003e(Quotes, Poetry, TODO)\"]\n        end\n\n        subgraph Storage [\"State Management\"]\n            Cache[(\"Cache (TTL/LRU)\")]\n            State[(\"Persistence DB\")]\n        end\n    end\n\n    %% --- 3. Render Layer ---\n    subgraph RenderLayer [\"🎨 Rendering Engine\"]\n        direction TB\n        ImgBuilder(\"Image Builder\")\n\n        subgraph Strategies [\"Layout Strategies\"]\n            DashLayout[\"Dashboard Layout\"]\n            ContextLayouts[\"Context Layouts\u003cbr/\u003e(Holiday, Quote, Poetry)\"]\n        end\n\n        Renderer[\"Primitive Renderers\u003cbr/\u003e(Text, Icons, Shapes)\"]\n    end\n\n    %% --- 4. Hardware Layer ---\n    subgraph HWLayer [\"🖥️ Hardware Output\"]\n        direction TB\n        DriverFac(\"Driver Factory\")\n        EPD[\"E-Paper Driver\"]\n        Mock[\"Mock (PNG)\"]\n    end\n\n    %% --- Connection Logic ---\n    %% Control Flow\n    Main --\u003e Config \u0026 TaskMgr\n    Main --\u003e DisplayCtrl\n    Config -.-\u003e Main\n\n    %% Data Flow\n    Main --\"Trigger\"--\u003e Fetcher\n    Fetcher --\u003e External \u0026 Local\n    External \u0026 Local -.-\u003e Storage\n\n    %% Render Flow\n    DisplayCtrl --\"Select Mode\"--\u003e ImgBuilder\n    ImgBuilder --\"Get Data\"--\u003e Storage\n    ImgBuilder --\u003e DashLayout \u0026 ContextLayouts\n    DashLayout \u0026 ContextLayouts --\u003e Renderer\n\n    %% Output Flow\n    Renderer --\u003e DriverFac\n    DriverFac --\u003e EPD \u0026 Mock\n\n    %% --- Application Style ---\n    class Main,Config,DisplayCtrl,TaskMgr control\n    class Fetcher,External,Local,Cache,State data\n    class ImgBuilder,DashLayout,ContextLayouts,Renderer render\n    class DriverFac,EPD,Mock hw\n    class Providers,Storage,Strategies subBox\n```\n\n## 🖥️ Hardware Support\n\n- **Primary**: Waveshare 7.5inch E-Paper HAT (V2)\n- **Other Models**: Configurable via `EPD_MODEL` env var (supports most models in the [official repo](https://github.com/waveshareteam/e-Paper))\n- **Platform**: Raspberry Pi (Zero/3/4/5) or any Linux board with SPI/GPIO\n\n## 🙏 Acknowledgments\n\n- [Antigravity](https://antigravity.google/) for the pair programming\n- [Waveshare](https://www.waveshare.com/) for E-Ink display drivers\n- [Chinese Poetry](https://github.com/chinese-poetry/chinese-poetry), [LxgwWenKai](https://github.com/lxgw/LxgwWenKai), [Hanyi](https://hanyi.com.cn/) for poetry\n- [Flaticon](https://www.flaticon.com/), [Weather Icons](https://github.com/erikflowers/weather-icons) for icons\n- [CoinGecko](https://www.coingecko.com/) for BTC price\n- [OpenWeatherMap](https://openweathermap.org/) for weather\n- [Figma](https://www.figma.com/) for UI design\n\n- All the open-source libraries that make this project possible\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalemoky%2Fpaper-pi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpalemoky%2Fpaper-pi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalemoky%2Fpaper-pi/lists"}