{"id":25436628,"url":"https://github.com/mscrnt/epaper-frame","last_synced_at":"2026-05-18T02:03:09.108Z","repository":{"id":277784488,"uuid":"933482844","full_name":"mscrnt/epaper-frame","owner":"mscrnt","description":"ePaper Frame is a Raspberry Pi-based image display system for Waveshare ePaper displays. It supports Google Drive integration, Tkinter/Flask-based emulation, and an optional auto-shutdown feature for power efficiency.","archived":false,"fork":false,"pushed_at":"2025-03-02T04:47:51.000Z","size":1014,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-02T05:25:56.472Z","etag":null,"topics":["emulation","epaper","epaper-displays","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mscrnt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-02-16T04:05:11.000Z","updated_at":"2025-03-02T04:47:54.000Z","dependencies_parsed_at":"2025-02-16T17:25:34.692Z","dependency_job_id":null,"html_url":"https://github.com/mscrnt/epaper-frame","commit_stats":null,"previous_names":["mscrnt/epepar-frame","mscrnt/epaper-frame"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscrnt%2Fepaper-frame","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscrnt%2Fepaper-frame/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscrnt%2Fepaper-frame/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscrnt%2Fepaper-frame/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mscrnt","download_url":"https://codeload.github.com/mscrnt/epaper-frame/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264766,"owners_count":22041794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["emulation","epaper","epaper-displays","raspberry-pi","waveshare"],"created_at":"2025-02-17T08:21:10.361Z","updated_at":"2026-05-18T02:03:09.101Z","avatar_url":"https://github.com/mscrnt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## **📄 README.md - ePaper Frame for Raspberry Pi**\nThis project enables a **Raspberry Pi** to display images on an **ePaper display**. It supports **Google Drive image retrieval**, a **simulated ePaper display**, and **power management** using a **PiSugar battery**.\n\nThe system can **wake on a schedule**, display an image, and **shut down** after execution. Users can also **control it via MQTT commands** from Home Assistant.\n\n---\n\n## **🛠 Features**\n✔ **Supports Waveshare ePaper displays**  \n✔ **Simulated ePaper display (EPD Emulator)**  \n✔ **Retrieves images from local storage or Google Drive**  \n✔ **Automated wake-up using PiSugar battery**  \n✔ **Reports battery status via MQTT**  \n✔ **Accepts MQTT commands for display updates**  \n✔ **Over-the-Air (OTA) updates via Git**  \n\n---\n\n## **📂 Project Structure**\n```\nepepar-frame/\n│── epd_emulator/              # EPD Emulator for Tkinter or Flask\n│── waveshare_epd/             # Drivers for real Waveshare ePaper displays\n│── images/                    # Local folder for images\n│── config.py                  # Loads settings from .env \u0026 CLI arguments\n│── display.py                 # Main script for processing \u0026 displaying images\n│── image_source.py            # Fetches images from local or Google Drive\n│── update.sh                  # Fetches latest updates from GitHub\n│── update_wake_time.sh        # Updates PiSugar wake time\n│── run_update_and_display.sh  # Runs updates \u0026 display.py\n│── mqtt_update.py             # Sends battery status \u0026 last image to MQTT\n│── mqtt_command_listener.py   # Listens for MQTT commands (shutdown, update display)\n│── upload_to_drive.py         # Uploads logs to Google Drive\n│── .env                       # Environment variables for configuration\n│── .secrets                   # Secure storage for sensitive values (Google Drive)\n│── README.md                  # This documentation\n```\n\n---\n\n## **🚀 Installation on Raspberry Pi**\n### **1️⃣ Clone the Repository**\n```bash\ngit clone https://github.com/mscrnt/epepar-frame.git\ncd epepar-frame\n```\n\u003e **🔹 Important:** Replace `mscrnt` with **your own GitHub repo** if you forked the project.\n\n---\n\n### **2️⃣ Install Dependencies**\n```bash\nsudo apt update\nsudo apt install -y python3 python3-venv python3-pip git jq\n```\nCreate a **Python virtual environment**:\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On Windows use: venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n---\n\n### **3️⃣ Configure `.env` File**\nCreate a `.env` file in the project root:\n```\nIMAGE_SOURCE=drive  # Options: local, drive\nGOOGLE_SERVICE_ACCOUNT=credentials.json\nLOCAL_IMAGE_DIR=./mnt/images  # Local image directory\nDISPLAY=epd5in65f  # Default display 5.65 inch 7 color display (600, 448)\nUSE_SIMULATOR=true  # Set to \"true\" to use the emulator\nUSE_TKINTER=false   # Set to \"false\" to use Flask for the simulator\nSHUTDOWN_AFTER_RUN=true  # Set to \"true\" to shutdown after displaying the image\nMQTT_BROKER=homeassistant.local\nMQTT_PORT=1883\nMQTT_TOPIC_PREFIX=epaper_frame\n```\n\n\u003e **🛠 Need to prevent shutdown?** Set `SHUTDOWN_AFTER_RUN=false` in `.env`.\n\n---\n\n### **3️⃣ Configure `.secrets` File**\nCreate a `.secrets` file in the project root:\n```\nGOOGLE_DRIVE_FOLDER_ID=your_drive_folder_id (if using Google Drive)\nGOOGLE_DRIVE_LOG_FOLDER_ID=your_log_folder_id (if using Google Drive)\nMQTT_USERNAME=your_mqtt_username (if using MQTT)\nMQTT_PASSWORD=your_mqtt_password (if using MQTT)\n```\n\n---\n### **4️⃣ Configure Google Drive (Optional)**\nIf using Google Drive:\n1. **Enable Google Drive API**: [Google Cloud Console](https://console.cloud.google.com/).\n2. **Download `credentials.json`** and place it in the project root.\n3. **Share the folder** with the service account email found in `credentials.json`.\n4. **Set the folder ID** in `.secrets` file.\n\n---\n\n## **🔋 PiSugar Battery Setup**\nThis setup **requires PiSugar** with the **PiSugar server running**.\n\nTo check if the PiSugar server is running:\n```bash\nsudo systemctl status pisugar-server\n```\n\nSet the PiSugar **wake-up time** every **8 hours**:\n```bash\n/path/to/epaper-frame/update_wake_time.sh\n```\n\n---\n\n## **🖥️ Running the Display Script**\n### **📌 Manually Run**\n```bash\npython display.py\n```\nThis will:\n- Fetch an image (from local storage or Google Drive)\n- Process it for the **ePaper display** or **simulator**\n- Display the image\n- Shutdown the Pi if `SHUTDOWN_AFTER_RUN=true`\n\n---\n\n## **📡 MQTT Integration**\n### **📤 Sends These MQTT Updates**\n| **Topic**                 | **Payload Example**                            | **Description** |\n|---------------------------|--------------------------------|----------------|\n| `epaper_frame/last_image` | `{\"image\": \"Last_image_displayed.jpg\"}` | Last displayed image |\n| `epaper_frame/battery_status` | `{\"charge\": \"77.52%\", \"voltage\": \"3.80V\", \"current\": \"-1.05A\", \"charging\": \"false\", \"power_plugged\": \"true\"}` | Battery status |\n\n### **📥 Accepts These MQTT Commands**\n| **Topic**                   | **Payload**           | **Action** |\n|-----------------------------|----------------------|------------|\n| `epaper_frame/command`       | `shutdown`          | Shuts down the Pi |\n| `epaper_frame/command`       | `display`           | Runs `display.py` |\n| `epaper_frame/command`       | `set_image: my_image.jpg` | Displays a specific image |\n\n---\n### **📌 Automate MQTT Services**\nTo run **MQTT updates \u0026 command listener** automatically:\n\n\n---\n#### **Create `mqtt_command_listener.service`**\n```bash\nsudo nano /etc/systemd/system/mqtt_command_listener.service\n```\n```\n[Unit]\nDescription=E-Paper MQTT Command Listener\nAfter=network.target\n\n[Service]\nExecStart=/usr/bin/python3 /path/to/mqtt_command_listener.py\nRestart=always\nUser=kenneth\n\n[Install]\nWantedBy=multi-user.target\n```\n\u003e **🔹 Important:** Replace `/path/to/` with the **actual path** to your `mqtt_command_listener.py` file.\n\nOr copy the mqtt_command_listener.service file from the project root to `/etc/systemd/system/`.\n\n```bash\nsudo cp mqtt_command_listener.service /etc/systemd/system/\n```\nEnable \u0026 start:\n```bash\nsudo systemctl enable mqtt_command_listener.service\nsudo systemctl start mqtt_command_listener.service\n```\n\n---\n\n### **📌 `run_update_and_display.sh` (Update and run display.py)**\nThis script runs the update, **fetches new images**, and **updates the display**.\n\n```bash\n./run_update_and_display.sh\n```\n\n---\n## **🔄 Automating Execution**\n### **📌 Wake on Event \u0026 Update via `cron`**\nTo set the Raspberry Pi to **wake on schedule**, update, and **display an image**, add to `cron`:\n\n```bash\ncrontab -e\n```\nAdd:\n```\n@reboot /bin/bash /path/to/run_update_and_display.sh\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmscrnt%2Fepaper-frame","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmscrnt%2Fepaper-frame","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmscrnt%2Fepaper-frame/lists"}