117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
# 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).
|
|
|
|
|
|
|
|
## 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).
|