# 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](https://www.waveshare.com/wiki/E-Paper_ESP32_Driver_Board).

![Picture of e-ink
screen](https://gitea.bubbletea.dev/shibao/szuru-eink-bot/raw/branch/master/eink-screen.jpg)

## 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](https://www.waveshare.com/wiki/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

```bash
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:

```bash
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](https://www.waveshare.com/wiki/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](https://github.com/lmarzen/esp32-weather-epd). I
covered it in walnut because I like walnut, sourced from
[Amazon](https://www.amazon.com/dp/B08SVQBVJN).