E-paper ESP32 Frame

• This project is currently a Work in Progress (WIP)!

This project leverages Immich as a service for organizing albums and photos. Photos intended for display are grouped into specific albums, and a FLASK server hosted on a NAS or cloud server handles image cropping and editing before sending them to the ESP32. Since the ESP32 remains in deep sleep most of the time, and all image processing is handled by the server, the EPD updates photos very quickly, typically within 15 seconds. This significantly reduces power consumption.

Features

• Captive portal: By long-pressing setup button on the ESP32 when boot up, the device enters setup mode, allowing the Wi-Fi setup page to store up to five SSIDs. This enhances mobility and makes it easier to switch between networks. Mostly modifieded from TRMNL WiFiCaptive[https://github.com/usetrmnl/firmware/tree/main/lib/wificaptive]
• Fully Automated Photo Management: Manage photos through Immich without additional manual processes; photos will automatically sync to the frame.
• Ultra-low Power Consumption: As all image processing and quantization are handled by the server, the device only consumes ~16µA during deep sleep, with photo updates completed within 30 seconds.
• Customizable Display: Configure photo orientation, basic color adjustments, album name, and more through the server webpage.
• Multi-language settings page: The settings page is available in English, Traditional Chinese, Simplified Chinese and Japanese, picked automatically from your browser's language and switchable from the header.
• Cython impelementation: Use Cython to significantly accelerate photo processing, achieving up to a 5x speed boost.
• HTTPS supported: ESP32 now can connect to secured server.
• Sleep time impelementation: ESP32 will enter deep sleep during the specified sleep period.
• One button: When the ESP32 is in deep sleep, a short press of the setting button will wake it up and restart the process, while a long press(~5s) of the setting button during boot will enter setting mode.

Table of Contents

• Components
• Installation
• License

Components

• FireBeetle 2 ESP32-C6
• 7.3-inch E Ink Spectra 6 (E6) Full Color E-Paper Display Module + HAT
• Picture frame: A standard picture frame that accommodates the e-paper frame.
• Li-Po battery with PH2.0 header
• Simple button for wake and setting

Installation

Clone the Repository

$ git clone https://github.com/jwchen119/epf.git

Manually Build Docker Image

$ git clone https://github.com/jwchen119/epf.git
$ docker build -t jwchen119/epf .

Download Precompiled Docker Image

If you prefer not to build the image yourself, you can download the precompiled image from DockerHub:

docker pull jwchen119/epf

Run with Docker Compose (recommended)

Create a .env file next to docker-compose.yml holding your Immich API key, then bring it up:

$ echo "IMMICH_API_KEY=<replace-your-immich-api-key>" > .env
$ docker compose up -d

./config and ./photos are bind-mounted, so settings saved from the web page and the shown-photo history survive docker compose pull and a container rebuild. TZ is set too, because the sleep window and wake-up schedule are evaluated against local time and the image would otherwise run in UTC. Both EPF_PORT (default 15001) and TZ (default Asia/Taipei) can be overridden in the same .env file.

Run the Container Manually

If you would rather not use compose, mount both directories yourself. Anything written outside them lives only in the container and is lost as soon as the container is recreated - which is what updating to a new image does:

$ docker run --name epf \
    -e IMMICH_API_KEY='<replace-your-immich-api-key>' \
    -e TZ=Asia/Taipei \
    -v "$(pwd)/config:/config" \
    -v "$(pwd)/photos:/photos" \
    -d -p <replace-port>:5000 jwchen119/epf

Configure config.yaml (no longer needed, configure the settings directly from webpage)

Details

Below is an example of a configured `config.yaml` file:

immich:
  # Album name, must match the album name created in Immich
  album: testAlbme
  # Photo rotation angle, accepts only (0, 90, 180, 270)
  rotation: 270
  # Immich server URL
  url: http://192.168.100.36:2283
  # Color(Saturation) enhancement level using PIL's ImageEnhance.Color (1.0 = original level)
  enhanced: 1.5
  # Contrast level using PIL's ImageEnhance.Contrast (1.0 = original level)
  contrast: 1.2

ESP32-C6

Connect the EPD, ESP32-C6, Li-Po battery, and setting button according to the correct wiring configuration. To run the code follow the following steps:

1. Install and set up Arduino IDE
2. Connect your ESP32-C6
3. Rename the Arduino folder from the repo to epd7in3e
4. Open the epd7in3e.ino file
5. Install following libraries from Arduino library manager: 5-1. Arduinojson 5-2. Async TCP 5-3. ESP Async Web Server
6. Click 'Upload'
7. Connect to the Wifi AP created by the ESP32, named ESP32_ePAPER
8. A captive portal shows up allowing to enter your WiFi details and details of the Docker container (e.g. http://192.168.100.10:15151)

You can re-enter the configuration page later by short-circuiting the setting button at least 5 second while rebooting.

License

This project is licensed under the MIT License.