add readme with env sample

.env.sample

@@ -0,0 +1,6 @@
+SZURU_URL=YOUR_SZURU_URL
+SZURU_USER=YOUR_SZURU_USER
+SZURU_TOKEN=YOUR_SZURU_TOKEN
+EPD_TYPE=YOUR_EPD_TYPE # e.g., 7.5b V2, 5.65f
+EINK_IP=YOUR_EINK_IP
+DITHERING_MODE=YOUR_DITHERING_MODE # e.g., mono, color

README.md

@@ -0,0 +1,117 @@
+# 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).