Important

This project was developed entirely with AI coding assistance (Claude Opus 4.6 via Cursor IDE) and has not undergone rigorous review. It is provided as-is and may require adjustments for other environments.

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.

_{PaperColor showing a dithered photo with location and date metadata overlays}

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-S3R8 (16MB flash, 8MB PSRAM), 4" 600x400 Spectra 6 e-ink display, 1250mAh battery, 2.4 GHz Wi-Fi

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.

Usage

The PaperColor has three user buttons along the top edge (left to right: Top, Up, Down) and a power button on the side.

Single press:

Button	Action
Top	Show a random photo
Up	Next photo
Down	Play / pause slideshow

Combos and holds:

Input	Action
Top double-press	Enter deep sleep
Top + Down hold (3s)	Enter deep sleep
Up hold (5s)	Factory reset (erases all settings, reboots)

LED feedback:

• White flash on any button press
• Red flash when entering deep sleep
• Green pulse while charging
• Orange pulse at low battery, red pulse at critical

Deep sleep: In deep sleep mode the device wakes on a timer, fetches and displays a photo, then sleeps again. The interval and batch size are configured via the web UI. Press the power button to wake manually.

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