# 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 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 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

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:

```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`.
- 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.

```bash
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](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).