tfaour/espresso_frame
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 13 Wiki Activity

Fix stale documentation found by a doc-accuracy audit

Browse Source 
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).
This commit is contained in:
tfaour
2026-07-19 15:20:12 -04:00
parent aef8a10029
commit d5de882b1e
3 changed files with 48 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+18 -10
View File
@@ -1,8 +1,10 @@
# Architecture
Two independent pieces talk over plain HTTP on the local network: the
ESP32-C6 firmware, and a small FastAPI server that sits between it and
Immich.
Two independent pieces talk over HTTP or HTTPS (the server itself always
speaks plain HTTP; HTTPS means a reverse proxy in front of it, see
[`firmware/README.md`](../firmware/README.md#http-vs-https)) on the local
network: the ESP32-C6 firmware, and a small FastAPI server that sits
between it and Immich.
```mermaid
sequenceDiagram
@@ -16,11 +18,14 @@ sequenceDiagram
Note over Frame: User scans WiFi QR, then config QR -> fills in<br/>home WiFi + "Tools Server" host:port
Frame->>Frame: Save config to NVS, reboot
Note over Frame: Every wake (deep sleep timer, next-photo button,<br/>or any other reboot)
Note over Frame: Every wake (deep sleep timer, next/back-photo button,<br/>or any other reboot)
Frame->>Frame: Connect to home WiFi
alt next-photo button pressed
Frame->>Server: POST /frame/advance
Server->>Server: Force-advance to next queued photo, reset interval clock
else back-photo button pressed
Frame->>Server: POST /frame/back
Server->>Server: Return to previously-current photo (bounded history),<br/>reset interval clock
else normal wake
Frame->>Server: GET /frame/image
Server->>Server: Advance only if refresh_interval_s has elapsed<br/>since the current photo was set -- otherwise a no-op
@@ -52,12 +57,15 @@ sequenceDiagram
2. **Stored config exists**: connect to the saved WiFi network (a few
retries before falling back to provisioning if it fails), then run the
fetch cycle in `frame_client.c`:
- Check the next-photo button (`next_button_check()`) -- if it was
what woke the device (checked via the latched
`esp_sleep_get_gpio_wakeup_status()`, not a live pin read, since a
quick tap can release before boot gets around to polling it) or is
currently held, the fetch below hits `POST /frame/advance` instead
of `GET /frame/image`, forcing the server to skip ahead immediately.
- Check the next-photo and back-photo buttons (`next_button_check()`,
`back_button_check()`) -- if either was what woke the device
(checked via the latched `esp_sleep_get_gpio_wakeup_status()`, not
a live pin read, since a quick tap can release before boot gets
around to polling it) or is currently held, the fetch below hits
`POST /frame/advance` or `POST /frame/back` instead of
`GET /frame/image`, forcing the server to move in that direction
immediately (next takes priority if somehow both read pressed at
once).
- Fetch the frame and write it into the panel's SPI buffer
(`epd_write_frame()`), computing a CRC32 as it streams -- never
buffering the full ~192KB frame in RAM. The panel driver refuses to