Your photo albums on an e-paper frame

Everlock now serves battery-powered e-paper picture frames. Point an esp32-photoframe at an album and it wakes up, fetches one picture, and goes back to sleep — no cloud account, no companion server, no sync agent. The photo library you already host is the picture source.

One URL per album

The image backend serves GET /album/{id}/photoframe. Every fetch returns a random photo from that album, and the frame's If-None-Match handshake keeps the same picture from showing twice in a row — without the server keeping any per-device state. Albums with a single photo answer 304 Not Modified, so the panel skips its refresh entirely and saves the battery for pictures that actually changed.

Rendered for the panel, not for a browser

E-paper is not a screen: a Spectra 6 panel shows six measured pigment colors, a grayscale panel sixteen levels. The frame normally downloads a JPEG and spends seconds of awake-CPU time decoding and dithering it. Everlock does that work server-side instead and answers in the panel's native format — pre-dithered 4-bit pixels, gzip-wrapped — so recent firmware just decompresses and blits. The renderer honors the device's own calibration: panel size and orientation, the measured color palette, and the processing settings (tone curve, saturation, dither algorithm) the frame reports with every request. Older firmware and browsers get a panel-sized JPEG from the same URL, which doubles as the debug view. Rendered frames are cached in the versioned store next to the previews, so each photo is dithered once per configuration, not once per fetch.

A key that can only see one album

The frame authenticates with an Everlock API key minted by sharing the album. The key is scoped to exactly that album — its access grant is http/image/<instance>:<album-id>, the same container:member convention mail uses for domain:mailbox — and it works both as an Authorization: Bearer header (the frame's native mechanism) and as the ?key= parameter of a share link. It expires with the share, shows up in /users apikey list, is revocable there at any moment, and disappears together with the album. A device taped to the wall holds a credential worth exactly one album, nothing more.

Setting it up

Share the album, mint the key, and enter two values in the frame's setup page:

image url:    https://photos.example.org/album/<album-id>/photoframe
access token: evapi_…

That's the whole integration.