espresso_frame/server

ESPresso Frame Server

Pulls photos from an Immich album, resizes/dithers/quantizes them to the E Ink Spectra 6 panel's exact 6-color format, and serves the frame a ready-to-display image once an hour. All the image processing happens here so the ESP32 never has to decode a JPEG or run a dithering algorithm itself -- it just streams the response straight to the panel.

Setup

1. Copy the compose file and run the server:

   cp docker-compose.yml.example docker-compose.yml
   docker compose up -d
   

2. First-run setup: open http://<this-machine>:8420/ -- you'll be walked through creating the admin account. Every user has their own login; the admin can enroll more from the Admin page (family members can also self-enroll through the frame-claim flow, below).
3. Connect your Immich library (per user, in Settings): your Immich URL and an API key. The key needs read access to albums/assets/faces, plus sharedLink.create (for the on-frame "scan to download" QR, which creates a temporary public share link) -- a plain read-only key will 403 on that one feature while everything else works. Frames you own pull from your library. (IMMICH_URL/IMMICH_API_KEY env vars in docker-compose.yml still work as an operator-level fallback and seed the first admin's settings when migrating an older deployment.)
4. Provision a frame: power it on, join its ESPRESSO_XXXXXX WiFi (instructions show on the panel), fill in your WiFi details and this server's address (Tools Server, e.g. <this-machine>:8420). After saving, your browser is redirected to this server's claim page and the frame links to your account -- creating an account on the spot if you don't have one (a valid frame is the invitation). The server speaks plain HTTP itself -- for HTTPS, put a TLS-terminating reverse proxy in front and enter the proxy's https:// address instead (see firmware/README.md's HTTPS section).
5. Each frame gets its own device token automatically -- the server issues it on the frame's first check-in, so there's nothing to configure. The captive portal's Access Token field only matters when pointing new firmware at an old (pre-multi-frame) server. MANAGEMENT_TOKEN in docker-compose.yml is likewise now only the migration credential: a frame flashed with pre-multi-frame firmware authenticates with it until it's updated and bound (the Admin page shows the migration state per frame and a "Close legacy window" button for when it's done).
6. Optional: auto-update firmware from Gitea releases. If you're pushing this repo to a Gitea instance, .gitea/workflows/firmware-release-build.yml builds both supported boards and publishes them as release assets (firmware-xiao.bin/firmware-devkit.bin) whenever firmware/version.txt changes on main. In a frame's Configuration tab, set the Gitea repo URL; if the repo is private, also set GITEA_FIRMWARE_TOKEN (a read-only PAT) in docker-compose.yml. Which board's build to fetch is learned from the frame itself (its X-Frame-Board header) -- nothing to pick by hand. The server then periodically checks for a newer release and either shows an "Update frame" button or, with Automatically apply updates checked, stages it itself -- either way the frame only actually updates on its own next wake.

Users, frames, and control

• Users log in with a session cookie; passwords are scrypt-hashed; mutating requests are CSRF-protected. Sign-up paths: first-run setup (admin #1), admin enrollment (Admin page), or the claim flow (a valid unclaimed frame's device_id gates self-service signup).
• Frames identify themselves by ?id= (MAC-derived) on every request and authenticate with a per-frame device token the server issues at first check-in. Unknown frames self-register as unclaimed; claiming (via /claim?device_id=...) sets the owner -- whose Immich library the frame renders from -- and links the account. Admins can link additional users to any frame; every linked user sees it in their sidebar.
• Control is a soft lock per frame: everyone linked can view; changing settings/queue requires holding control, and "Take control" always succeeds (the 409 error names the current holder). The physical buttons on the frame ignore all of this.
• The on-frame manage QR opens a limited no-login page (/m/<token>): view current + upcoming, "show next", advance, back -- nothing else. The share QR stays public (it creates a 30-minute Immich share link for exactly the photo shown).
• Email (optional). An admin sets an SMTP server once (/admin -- server, port, username/password, from address, STARTTLS on/off; a "send test email to myself" button, delivered to the admin's own email); each user sets their own email in Settings. Once both are in place: "Forgot password?" on the login page emails a one-hour reset link (a generic "check your email" response either way, so the endpoint can't be used to enumerate accounts), and a frame's Configuration tab can set a battery-alert threshold -- an email to the frame's owner the first time a report drops to or below it, not again until a recharge is detected and it crosses again. No SMTP configured, or no email on the relevant account, and both features silently no-op rather than erroring.

Endpoints

Pages: / (routing hub), /setup, /login, /claim, /settings, /admin, /frames/{id} (Photos), /frames/{id}/config, /frames/{id}/stats, /m/{manage_token}.

Device protocol (/frame/* -- paths frozen; auth = ?id= + ?token=)

• GET /frame/image -- the frame's current image, pre-processed into the panel's raw 800x480, 4-bit-per-pixel, 2-pixels-per-byte format (application/octet-stream, exactly 192,000 bytes). Side-effect-free by default: it only actually advances once refresh_interval_s has elapsed since the current photo was set, so an unexpected reboot just redisplays the same photo. An unclaimed or not-yet-configured frame gets a rendered instruction placeholder (with a claim QR) instead of an error, so a fresh device never error-loops.
• POST /frame/advance / POST /frame/back -- the next/back photo buttons: force an immediate move (mirror images of each other; back pops a bounded 20-entry history and pushes the displaced photo onto the front of the queue). Same response shape as /frame/image.
• GET /frame/config -- {"refresh_interval_s": ..., "firmware_version": ... | null, "device_token": ...?}, polled each wake. Captures the X-Frame-Version/X-Frame-Board headers (running firmware + board variant). device_token appears only during the one-time identity handshake -- until the device authenticates with its issued token once -- and the flat firmware parser's 512-byte buffer bounds how big this response may grow.
• GET /frame/photo-info -- location/date overlay text for the manage menu (city + abbreviated US/CAN region or country, MM/DD/YY).
• GET /frame/share/{asset_id} -- creates a 30-minute public Immich share link and 302s to it; scoped to the photo currently showing or queued on this frame only.
• GET /frame/face-labels -- up to 4 named faces with 800x480 positions, flattened (name_0/x_0/y_0, ...) for the device's flat-scalar parser.
• POST /frame/battery -- {"percent": 0-100}; per-discharge-cycle history (feeds the runtime estimate) plus a permanent per-frame battery log (the Stats chart). Only sent on battery power. Also where the battery-alert threshold (below) is checked and, at most once per discharge cycle, emailed to the owner.
• GET /frame/firmware -- streams the frame's staged OTA image.

Web API (/api/frames/{id}/... -- session auth; view for reads, control for writes)

• GET .../queue -- current + upcoming (each entry id + thumbnail URL), the control state ({"controller": name, "you": bool}), and the device telemetry block (last_seen, overdue -- quiet-hours aware -- firmware versions, battery + runtime estimate).
• POST .../queue/reorder|promote|remove -- reorder is drift-tolerant (stale ids dropped, missing ids appended); promote is "Show next"; remove permanently excludes from this frame's rotation (never touches Immich) and advances if it was current.
• GET .../albums -- the owner's Immich albums.
• POST .../config -- partial update: only provided fields change (name, album_id -- resets queue/history on change --, order, refresh_interval_s, display_mode (crop_fill/crop_faces/ stretch_fill/letterbox, see image_pipeline.DISPLAY_MODES), queue_target_len, orientation (composed logically then rotated server-side; the on-device manage overlay still renders native, a known limitation), quiet_hours_* + timezone (a pure server-side decision shaping what refresh_interval_s gets handed to the device), firmware_update_repo_url, firmware_auto_update, battery_alert_threshold_pct -- percent, or -1/blank to disable --, palette -- exactly 6 #rrggbb values in black/white/yellow/red/ blue/green order --, palette_reset -- true clears back to the default palette --, color_boost/contrast_boost -- PIL ImageEnhance factors, 0-2, 1 = unchanged --, dither_strength -- 0-1, blends toward a flat/undithered quantization before running Floyd-Steinberg, so 0 = no dithering texture and 1 = full strength).
• GET .../preview/original, GET .../preview/rendered -- the before/after comparison on the Configuration tab: the current photo's Immich preview untouched (JPEG), and that same photo run through this frame's actual saved rendering pipeline (PNG, upright logical orientation, not packed device bytes) -- reflects saved settings, not unsaved slider positions.
• POST .../take-control -- always succeeds for a linked user.
• GET .../stats, GET .../battery-log, GET .../thumbnail/{asset_id}.
• POST .../firmware (manual .bin upload, esp_app_desc_t-validated), GET .../firmware/check (throttled 15 min; ?force=true bypasses), POST .../firmware/apply-latest.

Manage-QR API (/api/m/{manage_token}/... -- token in path, no login)

• GET queue, POST promote, POST advance, POST back, GET thumbnail/{asset_id} (scoped to this frame's current/queued photos). Nothing else.

• GET /health -- liveness check, always open.

Notes

• All state (settings, current photo, upcoming queue, battery history, stats) lives in a SQLite database at ./data/espresso.db on the host via the compose volume mount (DATABASE_URL env var to override -- any SQLAlchemy URL works, so a future move to Postgres is a config change). A pre-database deployment's ./data/config.json is imported automatically on first boot (it becomes frame #1) and left untouched afterwards as the rollback path. IMMICH_URL/IMMICH_API_KEY env vars (see Setup above) still take precedence when present.
• The upcoming queue is a bounded lookahead, not the whole album -- "Upcoming photos to show" in the config UI (queue_target_len, 5-50, default 20) controls its size and takes effect immediately (the queue is topped up or trimmed the next time the page loads, not lazily over future advances). It's topped up automatically as photos are consumed, in sequential or shuffle order per the Order setting. Dragging photos in the web UI (or using "Show next") only rearranges what's already in that lookahead; it doesn't add or remove photos from the album.
• Auth in one breath: browsers use sessions (+CSRF), devices use per-frame tokens (?id= + ?token=), the manage QR uses its own limited token, and MANAGEMENT_TOKEN survives only as the migration credential for pre-multi-frame firmware. /frame/share stays scoped to photos this frame is actually showing or has queued, not any Immich asset ID someone might guess -- a second layer a leaked device token alone wouldn't bypass.
• Calendar frame mode (app/calendar_feed.py) expands recurring events (RRULE/EXDATE/DST) via recurring-ical-events, which is LGPL-3.0-or-later -- the only non-permissively-licensed dependency here. It's used as an ordinary pip install runtime import, never vendored or modified, so this project's own code stays under its own license; LGPL's copyleft terms apply to that library itself, not to code that merely links against it dynamically.
• CalDAV account support (app/caldav_client.py, alongside the plain ICS subscription) wraps the caldav PyPI package. caldav itself is dual-licensed GPL-3.0-or-later/Apache-2.0, but it hard-depends on icalendar-searcher, which is AGPL-3.0-or-later -- the strongest copyleft in this project's dependency tree, and the one whose network-use clause is written specifically for server applications like this one (not just "don't vendor/modify it," which was enough reasoning for the LGPL dependency above). Taking this on was an explicit, informed call by the project owner, not a default -- anyone redistributing this project (vs. just self-hosting it) should re-evaluate that tradeoff for their own situation before doing so.
• Calendar event titles can contain emoji, which ImageFont.load_default() (used for every other bit of text this project renders) has no glyphs for -- PIL/FreeType substitute a visible ".notdef" tofu box rather than skipping the codepoint. app/calendar_render.py draws emoji runs with a vendored font instead (Google's Noto Emoji, OFL-1.1 -- license text at app/fonts/OFL.txt), the one deliberate exception to this project's usual "no new font/icon assets" default elsewhere in calendar_render.py -- there's no way to hand-draw arbitrary emoji with primitives the way the weather icons are. Full color (app/fonts/NotoColorEmoji.ttf, embedded CBDT bitmap glyphs) is tried first and confirmed to hold up fine through the panel's own Floyd-Steinberg dithering; a deployment whose Pillow/FreeType wasn't built with embedded color bitmap support falls back to a monochrome outline font (app/fonts/NotoEmoji.ttf) instead of crashing or rendering nothing. Color glyphs are only stored at one embedded bitmap size (109px), so they're rasterized once at that size and scaled down to the target row height rather than drawn directly like normal vector text.
• The 6-color palette RGB values in app/image_pipeline.py (DEFAULT_PALETTE_RGB) are approximations, not measured values (Waveshare doesn't publish exact color primaries for this panel). Each frame's Configuration tab has an Advanced configuration section (collapsed by default) with a color picker per ink color -- tune them once you can compare a rendered photo against the real panel, and "Reset to defaults" to go back. Different panel units can vary enough to be worth calibrating per frame.

Deploying a pre-built image

Every push to main that touches server/ triggers a Gitea Actions workflow (.gitea/workflows/server-docker-build.yml) that builds this image and pushes it to this repo's Gitea Container Registry at git.thumeit.com/tfaour/espresso-frame-server. docker-compose.yml (copied from docker-compose.yml.example, see Setup above) already points at that image, so a deploy host doesn't need this repo's build context at all -- just the compose file:

docker compose pull
docker compose up -d

docker compose build (or up --build) still works too, for local iteration against your own Dockerfile changes.

Local development (without Docker)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
CONFIG_PATH=./data/config.json uvicorn app.main:app --reload --host 0.0.0.0 --port 8420

--host 0.0.0.0 matters here: without it, uvicorn defaults to 127.0.0.1 (localhost-only), which the ESP32 can't reach over the LAN. The Docker image already binds 0.0.0.0 by default.