Szuru-Eink Bot

This project fetches random images from a Szurubooru instance, processes them for e-ink displays, and uploads them to a e-ink screens running on the Waveshare E-Paper ESP32 Driver Board.

Features

• Fetches random images from a configurable Szurubooru instance.
• Resizes and dithered images for e-ink display compatibility.
• Supports monochrome and color dithering (for compatible displays).
• Uploads processed images to a Waveshare 7.5b V2 e-ink screen.
• Configurable via environment variables.
• Designed to run as a Docker container on a cron job.

Setup and Installation

Prerequisites

• Docker and Docker Compose installed on your system.
• A Waveshare 7.5b V2 e-ink screen connected to your network with its web interface accessible.

1. Clone the Repository

git clone <your-repository-url>
cd szuru-eink

2. Configure Environment Variables

Create a .env file in the root directory of the project (if it doesn't exist) and populate it with your Szurubooru API details and e-ink screen configuration. You can use the .env.sample as a reference for the required variables.

Note: For EPD_TYPE, refer to the epd/epd_config.py file for a full list of supported display types and their corresponding string labels. For color displays, ensure DITHERING_MODE is set to color.

3. Build and Run with Docker Compose

Navigate to the project's root directory and run the following command to build the Docker image and start the container:

docker-compose up --build -d

This command will:

• Build the Docker image based on the Dockerfile.
• Create and start a Docker container named szuru-eink-bot.
• Copy the environment variables from your .env file to docker-compose.yml for the container.
• Set up a cron job inside the container to run the szuru-eink.py script at a specified interval (default: every 15 minutes).
• Create a bind mount for logs in ./logs directory on your host machine.

4. Verify Logs

You can check the logs generated by the cron job in the ./logs/szuru-eink-cron.log file on your host machine.

tail -f logs/szuru-eink-cron.log

Project Structure

.dockerignore
.env
.gitignore
.tool-versions
Dockerfile
README.md
crontab
cron_job.sh
docker-compose.yml
epd/
├── epd_config.py
├── epd_uploader.py
└── image_processor.py
pyproject.toml
szuru-eink.py

Dependencies

• uv (for dependency management)
• Pillow (for image processing)
• python-dotenv (for loading environment variables in local testing)
• pyszuru (for interacting with Szurubooru API)
• requests (for HTTP requests)
• black (development dependency for code formatting)

Waveshare E-Ink Screen Compatibility

This project has been specifically tested and configured for the Waveshare 7.5b V2 e-ink screen. The image processing and upload logic are tailored to its specifications, including its 3-color (Black, White, Red) capabilities. While other Waveshare displays might share similar protocols, full compatibility is not guaranteed without further testing and potential adjustments to epd/epd_config.py and epd/epd_uploader.py.

Driver Board and Flashing

The e-ink screen used in this project is driven by the Waveshare E-Paper ESP32 Driver Board. The board was flashed with the sample Loader_esp32wf project provided by Waveshare, which exposes the web interface that this Python script interacts with.

3D Printed Casing

The 3D printed casing for the e-ink screen shown in the preview image was sourced from lmarzen/esp32-weather-epd.