tfaour
fd9516f5d1
Build and push server image / build-and-push (push) Successful in 36s
Purely a server-side decision: GET /frame/config hands back a longer refresh_interval_s while quiet hours are in effect (exactly the seconds until they end), and clamps the normal interval so the device's next wake lands at the boundary instead of wandering into the window, when outside it but approaching. A device already mid-sleep when quiet hours begin can still land one wake inside the window -- unavoidable without touching the firmware, since it has no wall-clock awareness -- but from that wake on it sleeps straight through to the end. Window is "HH:MM"-"HH:MM", wrap-past-midnight aware (e.g. 22:00-07:00), in the server's local timezone -- added tzdata to the Dockerfile since python:3.12-slim doesn't include it and TZ would otherwise silently resolve to nothing and fall back to UTC. Also fixed the "overdue" device-status check to account for quiet hours: without this it would falsely flag a device sleeping through a long quiet window as unreachable.
240 lines
13 KiB
Markdown
240 lines
13 KiB
Markdown
# ESPresso Frame Server
|
||
|
||
Pulls photos from an [Immich](https://immich.app) 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. **Get an Immich API key**: in Immich, go to Account Settings -> API Keys
|
||
-> New API Key. Needs read access to albums/assets/faces, plus
|
||
`sharedLink.create` (for the manage overlay's "scan to download" QR,
|
||
which creates a temporary public share link) -- a plain read-only key
|
||
will 403 on that one specific feature while everything else works.
|
||
2. **Copy the compose file and fill in your Immich details**:
|
||
```
|
||
cp docker-compose.yml.example docker-compose.yml
|
||
```
|
||
Edit `docker-compose.yml` and set `IMMICH_URL`/`IMMICH_API_KEY` under
|
||
`environment:`. `docker-compose.yml` is gitignored (it'll hold your real
|
||
API key) -- `docker-compose.yml.example` is the one that's committed.
|
||
3. **Run the server**:
|
||
```
|
||
docker compose up -d
|
||
```
|
||
4. Open `http://<this-machine>:8420/` in a browser, click **Load Albums**,
|
||
pick one, and **Save**. (The Immich URL/API key fields will already be
|
||
populated from the environment; changing them in the UI has no effect
|
||
as long as the env vars are set -- they win on every load.)
|
||
5. On the ESP32's captive portal setup form, set the **Tools Server** field
|
||
to `<this-machine>:8420`. This server always speaks plain HTTP itself --
|
||
for HTTPS, put a TLS-terminating reverse proxy (e.g. nginx) in front of
|
||
it and enter the proxy's `https://` address instead (see
|
||
`firmware/README.md`'s HTTPS section for what the ESP32 side needs).
|
||
6. **Optional: set `MANAGEMENT_TOKEN`** in `docker-compose.yml` to gate
|
||
the *entire server* -- the web UI (`/`, `/api/*`) and every
|
||
device-facing `/frame/*` endpoint -- behind a shared secret (leave
|
||
unset to keep it all open, the previous default -- fine on a trusted
|
||
LAN). If set, paste the same value into the ESP32's captive portal
|
||
setup form's **Access Token** field: the device then sends it on
|
||
every request it makes, and the manage-menu/share QR codes embed it
|
||
automatically (`?token=...`) so scanning them just works. Visiting
|
||
the web UI without a valid token in the URL shows a plain token-entry
|
||
prompt instead of the config UI; `/health` stays open regardless
|
||
(pure liveness, nothing sensitive in it).
|
||
|
||
## Endpoints
|
||
|
||
- `GET /` -- config UI (album, order, refresh interval, face-aware crop
|
||
toggle, upcoming-photos count, now-displaying + drag-to-reorder
|
||
upcoming grid -- not Immich URL/API key, see Setup above)
|
||
- `GET /api/albums` -- lists Immich albums (used by the config UI)
|
||
- `POST /api/config` -- saves
|
||
album/order/orientation/refresh_interval_s/smart_crop_faces/queue_target_len/quiet_hours_*.
|
||
`orientation` (`landscape`, `portrait`, `landscape_flipped`,
|
||
`portrait_flipped`) matches how the frame is physically hung: photos
|
||
are composed/cropped for that shape (portrait crops at 480x800), then
|
||
rotated into the panel's native 800x480 byte layout server-side --
|
||
the device never knows. Note the device-side manage-menu overlay
|
||
(QRs, text, battery indicator, face labels) still renders in native
|
||
panel orientation, so on a portrait-hung frame it appears rotated
|
||
90° to the viewer -- QR codes scan fine at any rotation, but the text
|
||
reads sideways. A known limitation, not planned to change soon.
|
||
`quiet_hours_enabled`/`quiet_hours_start`/`quiet_hours_end`
|
||
(`"HH:MM"`, may wrap past midnight, e.g. `22:00`-`07:00`) don't touch
|
||
the device at all -- purely a server decision about what
|
||
`refresh_interval_s` to hand back from `GET /frame/config` below,
|
||
computed in `_effective_refresh_interval_s`. Uses the server's local
|
||
timezone (`TZ` in `docker-compose.yml.example` -- the image needs
|
||
`tzdata` for a named zone to actually resolve, already installed in
|
||
the provided `Dockerfile`). The device can still land one wake right
|
||
at the start of the window (nothing server-side can prevent that
|
||
without touching the firmware, since the device doesn't know wall-clock
|
||
time), but from that wake on it's told to sleep exactly until the
|
||
window ends. The "overdue" indicator in `/api/queue`'s `device` object
|
||
also accounts for this -- it won't falsely flag a device that's
|
||
legitimately sleeping through a long quiet-hours window
|
||
- `GET /frame/image` -- returns the current photo 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 to the next photo once
|
||
`refresh_interval_s` has elapsed since the current one was set, so
|
||
calling it repeatedly (e.g. the device rebooting unexpectedly) just
|
||
redisplays the same photo instead of skipping ahead.
|
||
- `POST /frame/advance` -- forces an immediate advance to the next photo,
|
||
ignoring `refresh_interval_s`, and resets the interval clock from now.
|
||
Same response shape as `/frame/image`. Used by the device's next-photo
|
||
button (see `firmware/README.md`). Every photo actually displayed this
|
||
way (or via the normal timer-based advance) is pushed onto a bounded
|
||
history (`app/photo_queue.py`, last 20) that `/frame/back` below can
|
||
return to.
|
||
- `POST /frame/back` -- returns to the previously-current photo (the
|
||
exact mirror of `/frame/advance`), and resets the interval clock from
|
||
now. A no-op (still 200, same photo) if there's no history yet.
|
||
Pressing advance afterwards returns to where you were before going
|
||
back -- it displaces the current photo onto the front of the upcoming
|
||
queue rather than discarding it. Same response shape as
|
||
`/frame/image`. Used by the device's back-photo button.
|
||
- `GET /frame/config` -- `{"refresh_interval_s": ..., "firmware_version": "1.2.3" | null}`,
|
||
polled by the frame each wake alongside its reachability check.
|
||
`firmware_version` is whatever's currently uploaded via
|
||
`POST /api/firmware` below (`null` if nothing's been uploaded) -- the
|
||
device compares it against its own running version
|
||
(`esp_app_get_description()->version`, sent as an `X-Frame-Version`
|
||
request header, stored as `device_firmware_version`) to decide whether
|
||
to OTA
|
||
- `GET /frame/photo-info` -- `{"asset_id": ..., "location_line1": ... |
|
||
null, "location_line2": ... | null, "taken_at": ... | null}` for the
|
||
current photo (same idempotent current-photo semantics as
|
||
`/frame/image`). `location_line1`/`location_line2` are `city` /
|
||
`state-or-country` if Immich reverse-geocoded the photo's GPS EXIF
|
||
(both `null` if not) -- for US/Canada, the region line is the
|
||
abbreviated state/province (`"CA"`, `"ON"`); elsewhere it's the full
|
||
country name. `taken_at` is `MM/DD/YY` from the photo's EXIF capture
|
||
date, else `null`. Used by the device's manage button to build its
|
||
overlay text
|
||
- `GET /frame/share/{asset_id}` -- creates a 30-minute public, view-only
|
||
Immich share link for `asset_id` and redirects (302) to it. Only works
|
||
for the photo currently showing or in the upcoming queue on this frame
|
||
-- not any arbitrary Immich asset. The link is created on first hit
|
||
(i.e. when someone actually scans the manage overlay's share QR), not
|
||
when the button's pressed, so the 30-minute window starts when it's
|
||
actually used
|
||
- `GET /frame/face-labels` -- `{"count": N, "name_0": ..., "x_0": ...,
|
||
"y_0": ..., ...}` (up to 4 slots) -- named people from Immich's face
|
||
recognition, positioned in final 800x480 frame pixel space. Only faces
|
||
Immich already has an identified name for are included (no face
|
||
detection/recognition happens in this project, see
|
||
`app/face_labels.py`); `count: 0` if none are named. Used by the
|
||
device manage button's escalated second menu level
|
||
- `POST /frame/battery` -- `{"percent": 0-100}`; the device's last
|
||
battery reading, stored with a timestamp plus two histories: a
|
||
per-discharge-cycle one (reset whenever a report jumps up enough to
|
||
look like a recharge) feeding the "on battery for"/estimate numbers,
|
||
and a permanent, never-reset log (capped at `BATTERY_LOG_MAX`, ~2
|
||
years at hourly reports) feeding the web UI's battery graph. Only sent
|
||
when the device is actually running on battery (see
|
||
`firmware/README.md`'s Battery section) -- a frame on mains power
|
||
never reports
|
||
- `GET /api/battery-log` -- `{"log": [[timestamp, percent], ...]}`, the
|
||
full permanent battery history above; used by the web UI's "Battery
|
||
history" chart
|
||
- `POST /api/firmware` -- multipart upload (`file`) of a built
|
||
`espresso_frame.bin`. Parses the embedded `esp_app_desc_t` (rejects
|
||
anything that isn't a valid image for this project) and stores it as
|
||
the available firmware; devices pick it up via `GET /frame/config`
|
||
above on their next wake
|
||
- `GET /frame/firmware` -- streams back whatever was last uploaded via
|
||
`POST /api/firmware`, for the device's OTA fetch. 404 if nothing's
|
||
been uploaded yet
|
||
- `GET /api/queue` -- `{"current": {...} | null, "upcoming": [...],
|
||
"device": {"last_seen": ts | null, "overdue": bool,
|
||
"firmware_version": "1.2.3" | null, "firmware_available": "1.2.4" | null,
|
||
"battery": {"percent": N, "as_of": ts} | null, "on_battery_since": ts | null,
|
||
"battery_estimate_s": N | null}}`, each queue entry an asset id +
|
||
thumbnail URL; used by the config UI's "Device" panel
|
||
- `POST /api/queue/reorder` -- reorders the upcoming queue; body is
|
||
`{"queue": [asset_id, ...]}`. Tolerant of drift from the queue having
|
||
changed server-side since the client's last fetch (e.g. a top-up/trim)
|
||
-- unrecognized IDs in the body are dropped, and any currently-queued
|
||
photo missing from the body is appended rather than lost, instead of
|
||
rejecting the whole request
|
||
- `POST /api/queue/promote` -- moves one photo to the front of the queue;
|
||
body is `{"asset_id": "..."}`. Used by "Show next" in the web UI --
|
||
unlike `/reorder`, doesn't depend on the client knowing the queue's
|
||
full current order, so it can't fail from staleness
|
||
- `POST /api/queue/remove` -- permanently excludes a photo from this
|
||
frame's rotation; body is `{"asset_id": "..."}`. Doesn't touch Immich
|
||
or the album -- the photo just stops being selected by this frame
|
||
again (`app/photo_queue.py`'s `excluded_asset_ids`/`remove_from_rotation()`).
|
||
Works on the current photo too, in which case it immediately advances
|
||
to a different one (without recording the removed photo in history --
|
||
going back to a photo you just removed wouldn't make sense). Used by
|
||
the "×" button in the web UI on both the current-photo thumbnail and
|
||
each upcoming card
|
||
- `GET /api/photo-thumbnail/{asset_id}` -- proxies an Immich thumbnail so
|
||
the browser never needs the Immich API key directly
|
||
- `GET /health` -- liveness check
|
||
|
||
## Notes
|
||
|
||
- Album/order/refresh-interval/current photo/upcoming queue/etc. are
|
||
stored in `./data/config.json` on the host via the compose volume
|
||
mount. Immich URL/API key are too if set via the web UI, but
|
||
`IMMICH_URL`/`IMMICH_API_KEY` env vars (see Setup above) always 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.
|
||
- Every endpoint except `/` and `/health` -- the web UI's `/api/*` and
|
||
every device-facing `/frame/*` -- requires `?token=` (or the
|
||
`mgmt_token` cookie the web UI sets after a valid one) once
|
||
`MANAGEMENT_TOKEN` is set (see Setup above); unset, everything stays
|
||
open like before, which is still fine on a trusted home LAN. `/frame/share`
|
||
additionally stays scoped to only ever create a link for a photo this
|
||
frame is actually showing or has queued, not any Immich asset ID
|
||
someone might guess -- a second layer a leaked token alone wouldn't
|
||
bypass.
|
||
- The 6-color palette RGB values in `app/image_pipeline.py` are
|
||
approximations, not measured values (Waveshare doesn't publish exact
|
||
color primaries for this panel) -- tune them once you can compare a
|
||
rendered test image against the real panel.
|
||
|
||
## 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.
|