The card being dragged never moved -- it just faded in place while a
static outline highlighted whatever was underneath the finger. Now the
card tracks the pointer 1:1 (translate + a slight scale-up "lift"),
gets a stronger shadow while airborne, and leaves its grid slot looking
like an empty gap until dropped (transform doesn't remove it from
layout flow, so the reserved space stays put -- no reflow needed until
drop). pointer-events:none while dragging so elementFromPoint's
drop-target hit-test sees through to the card underneath instead of
hitting the translated one.
Also: a short vibration tick when the touch hold-to-arm fires and
another on a successful drop (Chrome/Android only, iOS Safari has no
Vibration API -- harmless no-op there), and trimmed the arm delay from
350ms to 250ms now that there's actual feedback confirming the hold
registered.
The right column had grown to 5 stacked cards (Now displaying, Device,
Battery history, Firmware update, Stats) against the left's single
Settings form, running noticeably longer. Moved the collapsed Stats
card into a new left-column stack under Settings -- it's already
de-emphasized by design, so pairing it with the other
occasionally-checked column reads naturally, and it's small enough
(collapsed by default) to roughly balance the two columns' heights
without overcorrecting the other way.
Quiet hours only clamped what refresh_interval_s the *device* is told
to sleep for -- the separate elapsed-time check in
photo_queue.get_current() (used by /frame/image, /frame/photo-info,
/frame/face-labels, and /api/queue) had no quiet-hours awareness at
all, since it runs independent of the device. An open web UI tab
polling /api/queue overnight, or just loading the page during a quiet
window, would silently advance which photo is "current" on raw elapsed
time alone -- nothing reaches the panel until the device wakes after
quiet hours end, but the pointer moving mid-window still isn't what
"don't do anything overnight" implies.
get_current() now takes an in_quiet_hours flag that suppresses only the
elapsed-time trigger; an unset/invalid current photo is still picked
regardless (showing nothing is worse than showing something even at
3am). New _in_quiet_hours() helper in main.py, passed at all four call
sites.
New FrameStats (first_seen, device_wakes, photos_displayed,
photos_removed, battery_reports, recharge_cycles, ota_updates_applied,
config_saves), persisted alongside everything else in config.json.
Incremented at the existing route/photo_queue.py call sites that already
own each event -- no new instrumentation plumbing, no behavior depends
on these, purely informational. GET /api/stats serves them; the web UI
renders them into a native <details> "Stats" card (collapsed by default,
no JS needed for the expand/collapse), fetched once on page load like
the battery-history chart.
Verified: TestClient run through /frame/config (wakes + first_seen +
OTA-applied detection), /frame/battery (reports + recharge detection),
/api/config (saves); direct photo_queue.py unit checks for
advance/back/remove covering the "did the current photo actually
change" distinction (removing a queued-but-not-current photo bumps
photos_removed but not photos_displayed).
A press-and-drag gesture over a card's badge/button text also triggered
the browser's native selection highlight, distracting and occasionally
fighting the pointer-based drag tracking closely enough to break it.
Replaces the ad-hoc inline styling with a shared base template driven by
CSS custom properties (light/dark palettes), a card-based two-column
layout, and a persistent dark-mode toggle. Also moves quiet-hours'
timezone from the container's TZ env var into a proper web UI setting
(zoneinfo-backed), so it no longer needs a docker-compose.yml edit and
restart to change.
After a successful home-WiFi connection, caches BSSID/channel and
IP/netmask/gateway/DNS in NVS. The next wake's first connect attempt
uses the cached BSSID/channel (skips the all-channel scan) and applies
the cached IP directly once the link comes up (skips DHCP) -- a couple
fewer seconds of radio-on time per wake, free every wake since nothing
about the network actually needs renegotiating most of the time.
Falls back to a normal scan+DHCP attempt, and clears the cache, if: the
fast attempt itself fails, or it "succeeds" at the WiFi layer but the
full fetch cycle then fails anyway (a stale cached IP/DNS/gateway that
associates but can't actually reach the server). Also cleared on
(re)provisioning and factory reset, since a new network shouldn't try
to reuse the old one's cache.
The static-IP path needed care to get right without touching untested
territory: esp_netif_set_ip_info() only posts IP_EVENT_STA_GOT_IP (what
the existing connect-wait logic blocks on) once the netif is already
up, which the internal netif-glue's own WIFI_EVENT_STA_CONNECTED
handler guarantees by running first (registered earlier, in
esp_netif_create_default_wifi_sta()) -- confirmed against ESP-IDF's own
static_ip example and esp_netif_handlers.c source rather than assumed.
Falling back after a failed fast attempt also needed an explicit
esp_netif_dhcpc_start() first: esp_netif_dhcpc_stop() leaves the netif's
DHCP status STOPPED rather than resetting to INIT, and left alone the
glue would silently re-post the stale cached IP on the next connect
instead of actually running DHCP (esp_netif_action_connected).
Version bumped to 1.1.0 (real feature, not just a fix); build-verified
clean on both board configs (devkit 8MB, XIAO 4MB), no new warnings.
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.
battery_history stays cycle-scoped (reset on recharge, feeds the "on
battery for"/estimate numbers), but nothing kept a permanent record --
added battery_log, appended on every report and never reset, capped at
~2 years of hourly reports as a sanity bound rather than a real limit.
New GET /api/battery-log serves it; the web UI draws it as a plain
canvas line chart (no chart library) under a new "Battery history"
section, loaded once on page load.
Also caught up server/README.md, which never documented the OTA
firmware endpoints or the /api/queue response's current "device" shape
from the earlier status-panel work.
Two independent timers: a 1s tick re-renders "Last seen"/"On battery
for" from the already-fetched device data (so they count up smoothly --
1s ago, 5s ago, 1m ago...) without hitting the server that often, and a
10s poll re-fetches /api/queue to pick up real changes (new photo
displayed, queue edited elsewhere, a battery/firmware report) -- both
reuse the existing render functions, no new endpoints needed. The poll
skips itself while a drag-reorder is in progress so it can't yank the
grid out from under an in-flight drag.
It's a ratio divider -- what matters is the two resistors matching each
other, not hitting 200k exactly. Also note sdkconfig.xiao now enables
FRAME_BATTERY_ADC_GPIO by default, which the doc's "off by default"
line no longer reflected.
FRAME_BATTERY_ADC_GPIO was still at its off-by-default -1 in
sdkconfig.xiao despite the XIAO being the one board this was designed
for -- the status panel showed no battery line because the device never
sent a report at all. Sets it to GPIO0, matching the settled
shared-with-back-button design.
- version.txt + esp_app_desc_t version reporting (X-Frame-Version header);
new ota_update.c checks the server's advertised version against the
running one and streams+applies an update via esp_https_ota, gated by
bootloader rollback (marks the image valid only after a full successful
cycle, so a bad update can't brick a wall-mounted frame).
- Dual-OTA partition tables: partitions.csv (8MB dev board, 2MB slots) and
new partitions_xiao.csv (4MB XIAO, 1.875MB slots -- the dev board's
table doesn't fit the XIAO's flash). New build_for_board.sh gives each
board its own build dir + generated sdkconfig via SDKCONFIG_DEFAULTS
layering, so switching boards never clobbers the other's config.
- fetch_photo_info()/fetch_face_labels() were using the short
reachability-check timeout even though the manage-menu path can be the
first (cold, TLS-handshake-paying) request of a wake cycle -- switched
to the longer fetch timeout to stop spurious ESP_ERR_HTTP_CONNECT
failures.
- XIAO: the RF switch that selects onboard vs. external antenna
(GPIO3/14) isn't initialized by plain ESP-IDF the way Seeed's Arduino
package does it, leaving WiFi unable to reliably reach the antenna at
all -- new board_antenna.c powers the switch and selects the onboard
antenna, gated behind FRAME_XIAO_ANTENNA_INIT (on by default in
sdkconfig.xiao). Also remaps the EPD DC/RST/BUSY pins, since the dev
board's defaults (GPIO9/10/11) aren't physically exposed on the XIAO.
/api/queue now returns a "device" object: last_seen/overdue, running and
available firmware versions, battery percent + on-battery duration +
linear-fit remaining-time estimate (recharge cycles reset the history so
estimates never span a charge). New POST /api/firmware (token-gated
upload, validates the embedded esp_app_desc_t) and GET /frame/firmware
(token-gated download) let a build be pushed to the device without
touching it physically. GET /frame/config now accepts an X-Frame-Version
header and returns the available firmware version, piggybacking the
device's update check on a request it already makes every wake.
Battery (firmware + server, disabled by default): new battery.c reads
a 2x200k voltage divider via ADC oneshot with curve-fitting calibration
(the ESP32-C6's scheme), maps through a piecewise LiPo discharge curve,
and restores the pin to button duty after each read -- the settled
XIAO ESP32-C6 design shares the back button's GPIO0/A0, time-shared per
wake. Skipped entirely when on mains (a 2x100k VBUS divider into a
spare digital pin -- the 5V pin is dead on battery power, so presence =
mains, where the charging voltage would read misleadingly full) or when
the reading is implausible. The manage overlay gains a battery region
(static outline glyph + "NN%", below the manage QR, all menu levels),
and the device POSTs to the new /frame/battery endpoint after a
successful fetch; the server stores percent + as-of timestamp, exposed
via /api/queue and shown in the web UI. FRAME_BATTERY_ADC_GPIO /
FRAME_VBUS_SENSE_GPIO default to -1 (fully inert on the dev board);
compile-verified both disabled and enabled, hardware bring-up deferred
until the ordered XIAO + batteries arrive.
Orientation (server-side only): new config setting + web UI dropdown
(landscape / portrait / landscape_flipped / portrait_flipped). Photos
are composed/cropped at the logical hanging shape (portrait crops at
480x800, so face-aware crops match how the frame actually hangs), then
rotated losslessly into the panel's native 800x480 byte layout after
dithering -- the device never knows. Face-label anchors are transformed
through the same rotation (logical_to_native()) so they stay attached
to faces on rotated frames. Known documented limitation: the on-device
manage overlay still renders in native orientation, so it appears
sideways on a portrait-hung frame (QRs scan at any rotation; text reads
sideways).
Remove from rotation: a new bounded exclude list
(FrameConfig.excluded_asset_ids) that photo_queue._top_up() never
selects from. POST /api/queue/remove scrubs an asset out of
queue/history too so it can't resurface via "Show next" or the back
button, and if it was the current photo, advances away from it
immediately -- without recording it in history, since going back to a
photo you just explicitly removed doesn't make sense. Doesn't touch
Immich or the album itself, just this frame's own selection. Wired into
the web UI as a small "x" button on both the current-photo thumbnail
and every upcoming card.
Mobile scroll fix: touching a card to scroll the page was being
captured as a drag attempt every time (touch-action: none on every
.photo-card, needed for the existing drag-reorder gesture to work at
all), making it too easy to accidentally reorder instead of scroll.
Reworked touch dragging to require a brief hold (350ms, roughly
stationary) before it arms -- touch-action stays "pan-y" (native
scroll allowed) the whole time up to that point, so a normal
touch-and-swipe scrolls the page like anywhere else, and only switches
to "none" once a hold is confirmed as deliberate. Mouse dragging is
unchanged (no hold delay -- no scroll-vs-drag ambiguity with a mouse).
Also made the "Show next" and new remove buttons always visible instead
of hover/focus-revealed, since that was invisible-but-still-tappable on
touch (no hover state) -- a real hazard for a destructive action.
Root-caused the earlier "No matching trusted root certificate found"
failure properly this time by reading ESP-IDF's actual bundle-matching
code (esp_crt_bundle.c): it looks up a trusted root by the ISSUER name
of whatever certificate it can't otherwise validate, not by matching
the presented certificate itself. The live server's chain ends in a
GTS Root R4 certificate cross-signed by the old GlobalSign Root CA R1
(common Cloudflare/Google Trust Services practice, for compatibility
with older/embedded clients) -- and ESP-IDF's current bundle snapshot
has dropped that old GlobalSign root entirely, so the lookup came up
empty. This was a general gap, not something specific to this one
deployment's cert.
Fix: keep the standard public CA bundle (esp_crt_bundle_attach) as the
trust mechanism -- so any normal reverse-proxy cert (Let's Encrypt,
etc.) works out of the box -- and add the one missing root on top via
ESP-IDF's CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE mechanism
(sdkconfig.defaults), which appends a project-supplied cert file to the
bundle at build time. Fetched GlobalSign's official Root CA R1 cert and
cryptographically verified (openssl verify) it actually validates the
live server's certificate before embedding it -- see
firmware/main/certs/additional_root_ca.pem (replaces the old
tools_server_ca.pem, which pinned one exact certificate directly and
would've broken for anyone else's reverse proxy). Confirmed working
against the real deployment on hardware.
Found by a thorough code review:
- server/app/config.py's load()/save() each locked only their own file
I/O, not the full read-modify-write cycle each route does around
them. Since uvicorn dispatches sync routes to a thread pool, two
concurrent requests (e.g. the device's own poll landing alongside a
web UI edit) could each load() the same on-disk state and the
second's save() silently clobber the first's changes. Added
config.locked() (backed by an RLock, since load()/save() also take
the lock internally) and wrapped every mutating route's
load/mutate/save span in it -- kept outside the lock wherever a route
also does slow Immich network I/O, re-loading fresh state right
before the actual mutation instead. Verified with a new concurrency
stress test (many concurrent /api/queue/promote and /api/config
calls) alongside the existing scratch suite.
- firmware/main/root.html's SSID/password/toolsserver/access-token
inputs had no maxlength, so pasting something longer than the
matching NVS buffer (wifi_provisioning.h's FRAME_CFG_*_MAX_LEN) was
silently truncated with no indication why the device later can't
connect or gets 401s.
- frame_client.c's share_url buffer (256 bytes) could be too small in
the worst case -- toolsserver (128) + "/frame/share/" + asset_id (47)
+ "?token=" + access_token (64) can reach ~266 bytes, silently
dropping the token off a request that would then just 401 with no
obvious cause. Widened to 320.
firmware/README.md's HTTP vs HTTPS section still described the
public-CA-bundle trust approach that was tried and abandoned in favor
of pinning one specific certificate -- rewritten to match what's
actually there. docs/architecture.md was missing the back-photo button
entirely (sequence diagram and boot-flow bullets only covered next) and
still said the system talks "over plain HTTP" despite HTTPS support.
docker-compose.yml.example's MANAGEMENT_TOKEN comment understated its
scope (said "the web UI", omitting that every /frame/* endpoint is
gated too).
The native HTML5 Drag-and-Drop API (draggable/dragstart/dragover/drop)
is mouse-only by spec and never fires on phones/tablets, so reordering
was unusable on mobile. Replaced it with the Pointer Events API
(pointerdown/pointermove/pointerup), which unifies mouse, touch, and
pen into one code path, plus touch-action: none on the cards so
touching one to drag it doesn't get hijacked by the browser's default
scroll gesture. Same visual behavior as before (dim the dragged card,
outline the drop target).
Back button (new GPIO0, POST /frame/back): the server now tracks a
bounded history of previously-current photos (photo_queue.py), pushed
to on every advance (auto or forced) and popped by back_forced() --
symmetric with advance, so pressing next afterwards returns to right
where you were. frame_client.c's force_advance bool becomes a 3-way
fetch_action_t (NORMAL/ADVANCE/BACK) threaded through the whole fetch
path.
Also folds the separate reset and manage buttons onto one pin
(combo_button.c, replacing reset_button.c/manage_button.c entirely),
disambiguated by hold duration: quick press shows the management menu
(unchanged), ~3s hold-then-release soft-resets (esp_restart(), config
kept -- new), ~15s hold factory-resets (today's old reset behavior,
extended from 10s for clearer tier separation). Driven by a production
board (Seeed XIAO ESP32-C6) exposing only 3 of the ESP32-C6's 8
deep-sleep-wakeup-capable GPIOs -- next/back keep their own dedicated
pins where instant response matters most, everything else shares the
third pin via timing instead of needing its own. Same three-pin layout
now works on both the dev board and the production board.
Fixed a fast-tap bug in combo_button_check() before shipping: it only
did a live gpio_get_level() read to decide whether the button was
pressed at all, so a press fast enough to already be released by the
time boot reached that check was missed entirely (treated as "never
pressed" rather than "quick press"). Added the same latched
esp_sleep_get_gpio_wakeup_status() check the other buttons already use
for exactly this reason.
The Tools Server hostname turned out to be Cloudflare-proxied, not a
direct connection to nginx -- so the ESP32 (and any browser) sees
Cloudflare's own edge certificate (issued by Google Trust Services),
never the Origin CA cert, which only ever sits on the Cloudflare-to-
origin leg. Confirmed on hardware: ESP_ERR_HTTP_CONNECT.
Tried switching to ESP-IDF's built-in public CA bundle instead
(esp_crt_bundle_attach) as the more general fix, but that also failed
on hardware ("No matching trusted root certificate found") -- the
bundle's copy of the relevant Google root has the same name and public
key as the live one but a different serial/signature (a reissue), and
the bundle does an exact byte-level match, not a semantic one.
Simplest reliable fix: embed the exact certificate the proxy actually
presents (extracted live via openssl s_client, see
firmware/main/certs/tools_server_ca.pem) and trust that directly via
cert_pem, sidestepping bundle-matching semantics entirely. Documented
in firmware/README.md how to re-extract if the proxy's CA ever changes.
The management token only gated / and /api/* -- every device-facing
/frame/* endpoint (including /frame/image, which serves the actual
photo bytes) stayed open regardless. That was fine while the server
was assumed LAN-only, but defeats the point now that HTTPS exists
specifically to let this sit behind a public hostname.
build_url() (frame_client.c) is the one chokepoint all firmware-side
URL construction already went through, so it now appends ?token= to
every request it builds -- device fetches and QR-embedded links alike
-- instead of that being bolted on per-callsite. Server-side, the
former require_management_token dependency (renamed require_access_token)
is applied to /frame/config, /frame/image, /frame/advance,
/frame/photo-info, /frame/face-labels, and /frame/share/{asset_id} too.
/health stays open -- pure liveness, nothing sensitive to protect.
ESP32 side can now reach the tools server over HTTPS: the Tools Server
field accepts an https:// address for a TLS-terminating reverse proxy
in front of the server (which still only ever speaks plain HTTP
itself), trusting Cloudflare's Origin CA root (embedded at build time)
since that's the common way to get a real cert on a private origin.
Every URL the device builds -- image fetch, config check, manage-menu
data, the QR codes' own links -- goes through one build_url() helper
that picks the scheme from what's configured.
Also adds an optional MANAGEMENT_TOKEN (docker-compose.yml) that gates
the web UI (/, /api/*) behind a shared secret -- unset by default, so
existing trusted-LAN deployments are unaffected. The same token is
entered once during the ESP32's captive-portal setup and gets baked
into the manage-menu's QR code (?token=...), so scanning it just works;
visiting the page without a valid token shows a plain entry prompt
instead of the config UI, and a valid query-param hit sets a cookie so
the page's own fetch()/<img> calls stay authorized for the rest of the
visit. Device-facing /frame/* endpoints are unaffected -- a separate,
already-documented trust boundary.
ESP-IDF locks ("holds") every pin armed as a GPIO deep-sleep wakeup
source across the sleep transition, and never releases it automatically
on wake -- confirmed against sleep_modes.c's
esp_sleep_gpio_wakeup_prepare_on_hp_periph_powerdown(), which calls
gpio_hold_en() with no corresponding gpio_hold_dis() anywhere in
ESP-IDF's own wake path. Left held, live gpio_get_level() reads stay
frozen at whatever level the pin had when sleep began (almost always
"not pressed"), which is indistinguishable from a real "not pressed"
reading and silently broke any live poll for a *new* press later in the
same awake session.
This never surfaced before the manage menu's escalation feature, since
every other button check either used the latched wakeup-status register
(unaffected by hold) or only polled once, early in boot, before any
sleep/wake cycle in that session. wait_for_button_press() is the first
code in this project to repeatedly poll a button live *after* having
just woken via that same pin -- exactly the case hold breaks. Fixed by
calling gpio_hold_dis() before gpio_config() in all three buttons' init
functions, not just manage's -- reset and next-photo have the same
latent issue in their own live-read fallback paths, just not yet
exercised the same way.
A plain read-only key (per the original setup instructions) 403s on
POST /api/shared-links -- confirmed against the live instance's
permission enum in /api/spec.json.
Two rounds of follow-up work on the manage-button overlay:
1. Location formatting: US/Canada now show abbreviated state/province
("CA", "ON") instead of the full name, other countries show the full
country name, and each is its own line (was one line, now wraps to
two) so longer international place names have more room without
threatening to overlap the top-right QR box. The bottom-left share QR
also gets a "SCAN TO DOWNLOAD" caption.
2. Escalating menu: pressing the manage button again while its overlay
is already up adds a second level -- each Immich-identified person's
name labeled next to their face in the photo (using Immich's own
face recognition/People data, no detection/recognition added to this
project). A third press exits immediately instead of waiting out the
30s auto-revert timer. No new Immich API needed -- GET /api/faces
already embeds a nullable person.name per face; new
server/app/face_labels.py maps a named face's box into the final
800x480 frame's pixel space (reusing crop-box math extracted from
image_pipeline.py's face-aware cropping). Capped at 4 named faces,
sized to a real firmware RAM budget: each label is its own malloc'd
overlay region on the device, alongside the 4 fixed corner regions
already in use. New GET /frame/face-labels returns a flattened
fixed-slot JSON shape (not a real array) so firmware's existing
flat-scalar parser can read it without needing an actual array
parser. No persistent state needed for the escalation itself -- it's
all local control flow within one continuous awake session
(frame_client.c's run_management_menu()).
Two changes, bundled since they landed in the same session and touch
overlapping files:
1. Fix: "Show next" sent the browser's full queue snapshot to
POST /api/queue/reorder, which hard-rejected if the server's queue
had shifted since the last fetch (e.g. right after a queue-length
trim). New POST /api/queue/promote moves one photo to the front
authoritatively, with no dependency on client staleness. /reorder
itself is now tolerant too -- unrecognized IDs are dropped and
missing ones appended, instead of rejecting the whole request.
2. Feature: the manage button's overlay now also shows the photo's
location (top-left, only if Immich reverse-geocoded it from GPS
EXIF), the date it was taken (bottom-right), and a QR code (bottom-
left) linking to a 30-minute public Immich share link -- created
lazily when someone actually scans it, not when the button's
pressed. New server endpoints GET /frame/photo-info and
GET /frame/share/{asset_id} (scoped to the frame's current/queued
photos, not any arbitrary Immich asset). Firmware-side, the overlay
mechanism generalizes from one spliced region to up to four
(manage_qr_overlay.c), each its own small buffer, still never
holding the full frame in RAM.
Adds "Upcoming photos to show" to the config UI (queue_target_len, 5-50,
default 20, replacing the hardcoded QUEUE_TARGET_LEN constant). Lowering
it trims the queue immediately on next page load rather than waiting for
enough advances to consume the excess naturally; raising it tops back up
the same way, via a new photo_queue.sync_queue_length() called from
GET /api/queue.
Replaces the up/down-button vertical list with a responsive photo grid
(native HTML5 drag-and-drop between cards, reusing the existing
POST /api/queue/reorder endpoint -- no new server route needed). Each
card also gets a "Show next" button that jumps it straight to the front
of the queue.
Also bumps the queue lookahead from 10 to 24 photos (QUEUE_TARGET_LEN in
photo_queue.py) now that the grid has room to show more at once.
Pressing the manage button (GPIO1) overlays a small QR code -- "SCAN TO
MANAGE" -- in the top-right corner of whatever photo is currently on
screen, linking to the server's config page, then reverts to the plain
photo after 30 seconds.
The overlay is spliced into the existing streaming fetch as chunks pass
through (frame_client.c's http_read_fn), rather than buffering the full
192,000-byte frame in RAM: only the small overlay rectangle itself
(~30KB) is ever held in memory, generated via new stride-parameterized
drawing helpers (epd_draw_*_ex in epd_draw.c) that let the existing
QR/text drawing code target an arbitrarily-sized buffer instead of a
full-frame one. epd7in3e.c is untouched -- it has no idea an overlay
exists.
The QR onboarding and "CONNECTING..." status screens write to the panel
through a separate path that never touched the last-displayed-photo CRC
added in the previous commit. That left it stale relative to what's
actually on screen after either one draws -- most visibly after a
factory reset: reprovisioning and reconnecting could fetch a photo whose
CRC happened to match the one from before the reset, skip the refresh,
and leave the QR code frozen on screen indefinitely. Both screens now
invalidate the tracked CRC right after drawing, so the next photo fetch
is always guaranteed to actually refresh.
The panel driver now splits writing a frame into its SPI buffer
(epd_write_frame(), which also computes a CRC32 as it streams) from
actually triggering the physical refresh (epd_turn_on_display()).
frame_client.c compares the new CRC against the last one that was
actually refreshed (persisted in NVS) and skips the refresh entirely
when they match -- e.g. a reboot redisplaying the same photo before the
server's refresh interval elapsed no longer causes a visible flash for
no visual change.
Also reorders the per-wake fetch cycle: the image fetch (15s timeout)
now goes before the config check (3s timeout), instead of after. The
config check's tighter timeout was intermittently tripping on
connection-setup latency that's common on the first request after
waking from a long deep sleep (e.g. stale ARP); putting the more
tolerant request first absorbs that latency, and the config check then
rides the connection it already warmed up.
Factory-reset (GPIO3, hold 10s): clears stored WiFi/server config and
restarts into provisioning -- the deliberate, USB-free replacement for
the earlier reverted RST-based auto-reprovisioning idea.
Next-photo (GPIO2, tap): wakes the device and forces the server to
advance immediately via a new POST /frame/advance, instead of waiting
for the refresh interval. Both buttons arm themselves as deep-sleep GPIO
wakeup sources so a press is noticed promptly even while asleep.
Also makes GET /frame/image side-effect-free: it now only advances once
refresh_interval_s has elapsed since the current photo was set (tracked
server-side), so a device reboot for any reason just redisplays the
current photo instead of silently skipping ahead. The server maintains a
small reorderable upcoming-photos queue, viewable and rearrangeable from
the web UI.
- LICENSE: MIT, with attribution notes for the vendored qrcode/epaper_fonts/
dns_server code and the epd7in3e driver's transcription of Waveshare's
register sequence.
- Top-level README.md: project overview, hardware list, quick-start
pointing at firmware/ and server/, repo layout, license, Claude Code
attribution.
- firmware/README.md: full rewrite (was still the stock ESP-IDF captive
portal example's README) -- build/flash instructions, Kconfig reference
table, first-boot walkthrough, and how to reset to provisioning mode via
NVS erase (the only way in right now; a proper reconfigure trigger is a
future addition).
- docs/hardware.md: wiring table + parts list + strapping-pin/SPI-speed notes.
- docs/architecture.md: sequence diagram and walkthrough of the full
provision -> connect -> fetch -> display -> sleep cycle, plus the
reasoning behind doing image processing server-side and reusing Immich's
face detection instead of bundling a detector.
- server/README.md: fixed stale endpoint docs (missing GET /frame/config,
POST /api/config still describing removed immich_url/api_key fields).
Found on hardware: the Tools Server field was pointed at Immich's own
port instead of the frame server's, so /frame/image was actually hitting
Immich and getting back a small error response (~10KB) instead of a
192,000-byte frame. epd_display_stream() logged a size-mismatch warning
but called epd_turn_on_display() anyway, physically refreshing the panel
with a buffer that was ~95% whatever was left over from before -- visible
as "garbage" on screen, overwriting a previously-good image.
epd_display_stream() now returns ESP_ERR_INVALID_SIZE instead of
refreshing when the stream doesn't supply exactly EPD_FRAME_BYTES. Since
this check happens before epd_turn_on_display() is ever called, the
pixel data that *did* arrive only ever reached the panel's internal RAM
over SPI, not the physically visible display, so aborting here leaves the
screen exactly as it was.
This also means fetch_and_display() failing now always implies the panel
was never touched -- simplified frame_client_run() accordingly (dropped
the now-always-true/false out-param that used to distinguish "failed
before vs. during streaming", and always shows the FAILED status screen
on any fetch/display error, since it's now guaranteed safe to do so).
Now that they're set via docker-compose.yml's environment (previous
commit), leaving editable fields for them on the page was misleading --
anything typed there would be silently overwritten by the env vars on the
next load() anyway. Replaced with a read-only info banner showing the
configured Immich URL (never the API key value, even though it's already
env-sourced rather than user input) or a warning if IMMICH_URL/
IMMICH_API_KEY aren't set. POST /api/config no longer accepts or touches
those two fields at all.
Verified: page renders with no immich_url/immich_api_key input fields or
API key value in either case (env vars set or unset); config save/albums/
frame-image still work end-to-end via a mock Immich server.
RST/power-on trigger: checks esp_reset_reason() at the very top of boot.
ESP32-C6 can't electrically distinguish the RST/EN button from a genuine
power-on (both report ESP_RST_POWERON -- confirmed against ESP-IDF's own
docs, ESP_RST_EXT is explicitly "not applicable"), so POWERON is treated
as "user wants to reconfigure" and routes straight to provisioning. Safe
because the device's only normal restart path is ESP_RST_DEEPSLEEP (its
own scheduled wake), and crash-type resets (brownout/watchdog/panic)
report their own distinct reasons, not POWERON -- so a flaky power supply
or transient crash won't get bounced into provisioning, only an actual
power cycle or RST press will (which plausibly means the frame is being
moved/redeployed anyway).
Auto-fallback: a new NVS-persisted consecutive-failure counter
(frame_config_record_server_failure/reset_server_failures) tracks wakes
where the tools server was unreachable. After
CONFIG_FRAME_REPROVISION_AFTER_FAILURES in a row (default 12, ~1hr at the
retry interval), the device clears its stored WiFi config and
esp_restart()s rather than calling wifi_provisioning_start() directly --
doing that inline would mean initializing the display driver a second
time in the same session (frame_client_run already did once), the same
class of double-init bug hit earlier with WiFi. The next boot's
frame_config_load() naturally reports "not provisioned" and routes
through the existing, already-tested provisioning path with a single
fresh epd_init(). Solves the "I moved the server to a new address" case
without needing USB access.
Both frame_config_save() (fresh provisioning) and any successful server
contact reset the failure counter.
docker-compose.yml is tracked in a repo meant for publishing, so it can't
hold a real API key. Renamed it to docker-compose.yml.example (placeholder
values, safe to commit) and gitignored the real docker-compose.yml --
deploying is now "cp the example, fill in real values, docker compose up",
no .env file needed.
config.load() now reads IMMICH_URL/IMMICH_API_KEY from the environment
and applies them on top of whatever's in config.json, so setting them in
the compose file's environment: block takes effect without ever touching
the web UI. Env vars always win over the UI-saved values when both are
present -- verified they survive a save() with different UI-entered
values still in place.
The automatic GITHUB_TOKEN doesn't reliably authenticate against Gitea's
Container Registry -- confirmed as a known, still-open limitation across
several Gitea versions (multiple upstream issues, consistent with the
401/unauthorized error hit here). Gitea's own community guidance is to
use a real Personal Access Token instead. Switches docker/login-action to
a REGISTRY_TOKEN repo secret (a PAT with package write scope, created in
Gitea's user settings) with an explicit username rather than the
gitea.actor context, and drops the now-unused permissions: packages:
write block that only applied to the auto token.
_face_aware_crop_box() previously always centered the crop on the union
of all detected faces' centroid, even when the plain center-crop already
kept every face fully on screen -- unnecessarily moving a composition
that didn't need fixing. Now starts from the plain center-crop and only
shifts it the minimum amount needed to bring an otherwise-cropped-out
face back into frame; already-fine framing is left untouched (falls back
to centering on the faces' midpoint only if they're spread too wide for
any single shift to contain them all, which is unchanged from before).
Verified: a face safely inside the plain center-crop now produces byte-
identical output to the no-shift case (previously it still would have
been re-centered); an edge face gets a 100px shift instead of the 1050px
a full re-center would have applied. Re-ran against the real 4-face test
photo from earlier -- all four were already fully visible, so the refined
box now exactly matches the plain center-crop instead of shifting
unnecessarily.
Replaces check_server_reachable() (bare bool, GET /health) with
fetch_frame_config(), which GETs the server's new /frame/config endpoint
instead -- doubles as the reachability check (any completed HTTP response
counts, same as before) and delivers the server-configured
refresh_interval_s, used for the success-path deep sleep duration instead
of the Kconfig-only default.
Parses the tiny JSON response with a hand-rolled scalar extractor
(json_extract_uint) rather than pulling in a JSON library -- cJSON isn't
bundled in this ESP-IDF install, and a single flat integer field doesn't
justify a new dependency. Verified standalone against exactly the JSON
shape the server emits, including a missing-field fallback case.
FRAME_SLEEP_INTERVAL_S (Kconfig) is now just the fallback used before the
device has ever reached a configured server, or if the response is
missing/unparseable -- documented as such in its help text.
Two features, both toggleable/settable from the web config UI:
Refresh interval: new GET /frame/config returns
{"refresh_interval_s": ...} as plain JSON. Reuses the endpoint the frame
already needs to hit for a reachability check each wake cycle (previously
/health) rather than adding a third round trip, and always returns 200
with current settings regardless of Immich-configured state so it stays
valid as a pure reachability signal. Clamped to [60, 86400] seconds in
POST /api/config.
Face-aware cropping: GET /api/faces?id={assetId} on Immich already
returns real per-photo face bounding boxes from its own People-feature
ML -- confirmed against a live instance, boxes scaled to the asset's
native resolution. No face detection built or bundled here at all, just
an API call plus rectangle math. image_pipeline.render_frame() gains an
optional `faces` param: when present, computes the largest crop window
matching the panel's aspect ratio that fits in the source image, centered
on the union of all face boxes' centroid (scaled into the downloaded
preview's actual resolution) instead of the image's geometric center,
clamped to stay within bounds. No faces (or the smart_crop_faces config
toggle off) falls straight back to the existing ImageOps.fit() center-crop
-- zero behavior change in that case. A faces-lookup failure logs and
degrades to center-crop rather than failing the whole request.
Verified: unit tests for the crop-box math (horizontal shift toward an
off-center face, edge clamping), a full mock-Immich end-to-end pass
(extended to serve /faces) confirming the toggle changes output and the
response is still exactly 192,000 bytes, and a live comparison against a
real 4-face photo on the user's Immich instance (crop top shifted from
528px to 246px toward the detected faces).
tfaour
tfaour