Files

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-31 13:39:27 -04:00

Immich Frame

An ESP32 firmware for the M5Stack PaperColor e-ink display that turns it into a digital photo frame powered by your Immich server.

Features

Photo cycling modes -- random, chronological, reverse-chronological, favorites-weighted, and recency-weighted
Deep sleep with batch caching -- fetches multiple photo IDs per wake cycle to minimize network calls and extend battery life
6-color e-ink rendering -- Floyd-Steinberg dithering calibrated to the Spectra 6 palette with blue noise smoothing
Portrait pairing -- automatically pairs two portrait photos side-by-side
Metadata overlays -- date, time, location, people, album, and camera info as caption bars or corner badges
Web UI -- configure all settings, manage albums, trigger actions, and download wake logs from your browser
Wake logging -- persistent CSV log of each photo cycle that survives reboots and deep sleep

Clone the repository:

git clone https://code.cottongin.xyz/cottongin/immich-frame.git
cd immich-frame

Build and flash:
```
pio run -t upload
```
On first boot the device creates a PaperColor-Setup WiFi access point. Connect to it and open 192.168.4.1 in your browser.
Enter your WiFi credentials, Immich server URL, and API key. The device reboots and begins displaying photos.

Once connected to your network, access the web UI at http://papercolor.local to manage:

Slideshow -- interval (2m to custom), cycling mode, image quality, deep sleep batch size
Display -- metadata overlay content and position, translucent badge backgrounds
Albums -- filter photos by specific Immich albums
Device -- sync time, download/clear wake logs, deep sleep, reboot, factory reset

The tools/ directory contains standalone HTML utilities for analyzing wake log CSV files:

Open them directly in your browser; no server required.