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

Hardware

• M5Stack PaperColor (ESP32-S3, 600x400 Spectra 6 e-ink, 1600mAh battery)

Requirements

• PlatformIO (CLI or IDE plugin)
• An Immich server with an API key

Getting Started

1. Clone the repository:

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

2. Build and flash:

   pio run -t upload
   

3. On first boot the device creates a PaperColor-Setup WiFi access point. Connect to it and open 192.168.4.1 in your browser.

4. Enter your WiFi credentials, Immich server URL, and API key. The device reboots and begins displaying photos.

Configuration

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

Tools

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

• log-viewer.html -- chart and table view of a single wake log
• log-compare.html -- side-by-side comparison of multiple wake logs

Open them directly in your browser; no server required.

License

MIT