GET /api/albums/{id} was assumed to return an "assets" array alongside
the album metadata (that's what the original plan/prior art expected),
but on Immich 3.0.3 AlbumResponseDto only has assetCount -- no assets
field at all. Confirmed against the OpenAPI spec served at
/api/spec.json and by testing directly against a real instance: the
assumption was simply wrong for this API version, not a permissions
issue (the album metadata call succeeds fine with a valid 200).
Assets for an album now come from POST /api/search/metadata with an
albumIds filter, which returns them under assets.items. Verified
end-to-end against the real Immich instance and album -- /frame/image
now returns a proper 200 with exactly 192,000 bytes, spread across all
six panel colors (not a degenerate all-white/black response).
Only fetches the first page of search results; fine for a photo frame
cycling through an album, but would need nextPage handling for anyone
pointing this at a very large album.
Two bugs found testing against a real (partially-configured) server:
- The reachability check hit HEAD / with -- our server only registers
GET on that route, so it always got a 405. Harmless for the check
itself (any completed HTTP response counts as "reachable"), but noisy
and semantically wrong. Points at GET /health instead, which exists
for exactly this.
- fetch_and_display() failing before any pixel data was sent (e.g. a
400/404 on /frame/image) was treated the same as a mid-stream failure,
which skips drawing a status screen to avoid compounding flashing on
top of an already-refreshed panel. But a pre-stream failure never
touches the panel at all, so skipping the status screen there just
left the old provisioning QR code on screen with no indication
anything had gone wrong. fetch_and_display() now reports whether
streaming ever started so the caller can tell the two cases apart.
- The status screen now always shows on the very first successful
connection after (re)provisioning, regardless of outcome, via a new
"connected_once" NVS flag that frame_config_save() resets on every
fresh provisioning event. Later wakes skip it on success (straight to
the photo) but still show it on any failure, matching the intent from
the original status-screen feature.
- pillow==11.1.0 has no prebuilt wheel for Python 3.14, so pip fell back
to building from source and failed without libjpeg dev headers
installed. Bumped to 12.3.0 (has wheels); re-ran the local test suite
against it with no other changes needed.
- The local-dev uvicorn command in the README was missing --host 0.0.0.0,
so it defaulted to 127.0.0.1 -- unreachable from the ESP32 on the LAN.
The Docker image already binds 0.0.0.0 correctly; only the doc'd local
command was wrong.
frame_client_run() now does what it was always meant to: probe the tools
server, GET /frame/image and stream the response straight into the panel
via epd_display_stream() (esp_http_client's manual open/fetch_headers/read
API pulls in exactly the shape epd_display_stream()'s read_fn expects, so
the ~192KB frame never sits in RAM at once), then epd_sleep() and
esp_deep_sleep_start() for an hour.
Skips the WiFi/server status checklist screen on the happy path now that
there's a real photo to show instead -- three full refreshes every single
hour (status-pending, status-final, photo) wasn't worth it once bring-up
was actually working. Still shows it (status FAILED) when the server
isn't reachable, since nothing's been drawn yet that cycle and it's the
cheapest useful diagnostic. A mid-fetch failure after the panel's already
started refreshing just logs and retries sooner, rather than compounding
with a second refresh.
New Kconfig knobs: FRAME_FETCH_TIMEOUT_MS, FRAME_SLEEP_INTERVAL_S
(default 3600s), FRAME_RETRY_INTERVAL_S (default 300s on failure).
Builds server/Dockerfile and pushes to this repo's Gitea Container
Registry (git.thumeit.com/tfaour/espresso-frame-server) on every push to
main that touches server/, tagged both latest and the commit SHA.
docker-compose.yml now sets both image: and build: -- deploy hosts can
docker compose pull to grab the CI-built image without needing this
repo's build context, while local dev can still docker compose build
against Dockerfile changes directly.
Implements the server side of the architecture decided on: the ESP32-C6
has no PSRAM and a tight RAM budget, so all the heavy lifting (JPEG
decode, resize, Floyd-Steinberg dithering, 6-color quantization, 4bpp
packing) happens here instead of on-device. The frame just does a single
GET and streams the response straight to SPI.
- GET /frame/image: looks up the current cursor's asset in the configured
Immich album, downloads its preview thumbnail, and returns it packed
into the panel's exact 800x480/4bpp/2px-per-byte format
(application/octet-stream, always exactly 192,000 bytes).
- GET / + POST /api/config + GET /api/albums: a small web UI for entering
the Immich URL/API key and picking an album, rather than cramming that
into the ESP32's captive portal form.
- Config (Immich creds, selected album, cursor) persists to a JSON file
via a docker-compose volume mount.
Verified locally with a venv (Docker isn't available in this environment):
unit-tested image_pipeline against a synthetic image (exact byte count,
valid panel color codes only), and ran a full end-to-end pass against a
mock Immich HTTP server exercising the real /frame/image path.
Pinned dependency versions in requirements.txt after hitting a real bug
with unpinned floors: the latest starlette (1.3.1) resolved by `pip
install fastapi` breaks Jinja2Templates outright.
Not yet wired to the ESP32 side (task 6) or authenticated -- /frame/image
is unauthenticated for now, fine on a trusted LAN but worth revisiting
once the firmware sends a shared device token.
After a successful home WiFi connect, frame_client_run() now redraws the
panel as a two-row checklist (WiFi row with a checkmark, server row) so
the connection sequence is visible on-device rather than only in serial
logs. Refreshes once with the server row pending, probes the tools server
with a plain HTTP HEAD (any response, even 404, confirms the socket-level
connection works -- there's no real server yet), then refreshes again with
the final result. Two refreshes rather than one to actually show staged
progress, at the cost of the extra refresh time inherent to this panel.
Also fixes a second hardware-verified bug in the same area: on a failed
STA connect falling back to provisioning, wifi_init_softap()'s
esp_wifi_init() call was aborting with ESP_ERR_INVALID_STATE, because
frame_wifi_connect_sta() only stopped the WiFi driver on failure rather
than fully deinitializing it (and destroying the STA netif) before
handing back control.
Adds a "2. CONFIGURATION" step alongside WiFi setup: a second QR code
linking straight to the captive portal page (http://<ap-ip>/), for anyone
who's joined the AP but wants a one-scan shortcut to the config form
instead of relying on the captive-portal popup. The AP netif is now
created (but not started) before the display renders, since the AP's IP
is fixed at netif creation and needed for this QR before the network is
actually up.
Pulls the pixel/text drawing primitives (previously private to
qr_onboarding.c) out into epd_draw.c/.h so the upcoming status screen can
reuse them instead of duplicating.
Two crashes found flashing to real hardware:
- epd_display_stream's 4KB SPI chunk buffer was a stack local, but the
default main task stack (3584 bytes) is smaller than that alone --
Guru Meditation stack protection fault. Made it static instead, and
bumped CONFIG_ESP_MAIN_TASK_STACK_SIZE to 8192 for headroom in the rest
of the boot call chain (provisioning -> QR render -> eventually the
HTTP fetch cycle all run in this one task).
- epd_wait_busy() polled with a 1ms vTaskDelay, which rounds down to 0
FreeRTOS ticks at the default 100Hz tick rate -- so it never actually
blocked, tight-spinning the CPU for the panel's real refresh time
(15-30+s for a full-color pass) and starving the idle task long enough
to trip the 5s task watchdog. Bumped to 20ms, safely >=1 tick regardless
of tick rate.
Also updates the EPD pin defaults to the board's actual wiring
(CLK=20 MOSI=19 CS=18 DC=9 RST=10 BUSY=11), confirmed working on hardware.
Vendors two small MIT/BSD-3-Clause libraries rather than hand-rolling
either: Nayuki's qrcodegen (QR matrix generation) and Waveshare's Font24
bitmap table from their e-Paper repo (same repo the epd7in3e driver came
from) for rendering readable text on the panel.
qr_onboarding_show() builds a standard WIFI:T:WPA;S:...;P:...;; payload,
rasterizes the QR module matrix plus the SSID and password as plaintext
underneath (for anyone provisioning from a device that can't scan a QR)
onto a malloc'd frame buffer, and pushes it to the panel via
epd_display_buffer(). The buffer is heap-allocated on demand rather than
statically reserved, since 192KB held permanently in BSS would eat into
the RAM budget the HTTP fetch path (task 6) is specifically trying to keep
free.
Wired into wifi_provisioning_start() before the softAP comes up, so the
join instructions are already on-screen by the time the network is
joinable.
The board's flash is 8MB, but neither flash size nor partition table were
pinned in sdkconfig.defaults, so a fresh clone would silently fall back to
IDF's default (2MB flash, ~1MB "single app" partition table) rather than
what this project was actually being built/tested against. Building against
that default left only 4% of the app partition free before the HTTP client
work (task 6) even lands. Adds a custom partitions.csv with a 2MB app
partition and pins CONFIG_ESPTOOLPY_FLASHSIZE_8MB so the committed config
reproduces a working build for anyone else who clones this.
Ports Waveshare's official EPD_7in3e.c register/refresh sequence (the
panel has no public datasheet, so their reference driver is the source of
truth) to an ESP-IDF component using spi_master + gpio instead of the
bcm2835/RPi hardware abstraction the reference targets.
Unlike the reference driver, which toggles CS around every single byte,
this holds CS low for each logical command/data phase and DMAs pixel data
in 4KB chunks -- sending ~192,000 individual one-byte SPI transactions
would make a full refresh impractically slow.
Exposes a streaming API (epd_display_stream, pulling chunks from a
caller-supplied read_fn) so the eventual HTTP fetch path can feed the panel
without holding a full ~192KB frame in RAM, plus an in-memory convenience
wrapper (epd_display_buffer) for cases like the upcoming QR code screen
where buffering the whole frame is fine.
Wired into wifi_provisioning_start() as an init + white-clear for now, to
prove the driver builds/links/runs at the right point in the boot sequence
ahead of the actual QR code content.
Two frames on the same network would otherwise both advertise the same
ESPRESSO SSID during provisioning. Appends the last 3 bytes of the WiFi MAC
(read via esp_read_mac(), available before the WiFi driver starts) so each
device's softAP is uniquely named.
Splits provisioning (softAP + captive portal + NVS-backed config) into
wifi_provisioning.c and home-network connection into frame_client.c.
/save_config now parses the form body and persists it to NVS; on boot the
device goes straight to STA mode if a config exists, retrying a few times
before falling back to provisioning if the home network is unreachable.
The provisioning AP is now always named ESPRESSO with a random per-device
password (generated once, persisted in NVS) instead of a fixed Kconfig
value, drawn from a charset that avoids visually ambiguous characters since
it'll be read off the e-ink panel and possibly typed by hand.
Moves the existing ESP-IDF captive_portal example into firmware/ to make
room for the new FastAPI server and project docs, ahead of building out the
full ESPresso Frame project (ESP32-C6 + Immich-backed e-ink photo frame).
tfaour