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 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 E-Paper ESP32 Driver Board with the Loader_esp32wf project configured and flashed to the device, 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

Modify docker-compose.yml with the environment variables specified for your display.

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.
Configure the environment variables in 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).

4. Verify Logs

You can check the logs by doing docker-compose logs -f szuru-eink-bot.

Project Structure

.dockerignore
.gitignore
.tool-versions
Dockerfile
README.md
crontab
entrypoint.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)
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. I covered it in walnut because I like walnut, sourced from Amazon.