tfaour
914eaed71c
Repo-tracked context so a fresh Claude Code session (this machine or a remote/cloud one) gets accurate project context without relying on this session's local, machine-specific memory: repo conventions (no co-author trailers, flag copyleft deps explicitly, scope security gates broadly -- each backed by a real past incident), testing/deploy workflow, and pointers into the existing docs. docs/architecture.md's sequence diagram and boot-flow text still described the pre-widget-system single-photo-queue model (e.g. "force- advance to next queued photo") even though that was fully replaced by the widget system across this branch's recent history -- fixed, and added docs/widgets.md distilling the widget system's actual design (data model, grid placement, compositor, button-action dispatch) as current-state documentation, including the still-open Phase 6 cleanup (legacy Frame columns not yet dropped) as a known gap.
58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# ESPresso Frame
|
|
|
|
A DIY e-ink photo frame: an ESP32-C6 pulls photos from your
|
|
[Immich](https://immich.app) library and displays them on a 7.3" full-color
|
|
e-paper panel, waking on a timer to refresh and spending the rest of its
|
|
time in deep sleep.
|
|
|
|
- **No cables to a computer, no SD card shuffling.** Provisioning is a
|
|
captive portal with a QR code drawn on the panel itself -- scan, join,
|
|
fill in your WiFi and server address, done.
|
|
- **The frame never decodes an image.** A small self-hosted server does
|
|
all the work (pulling from Immich, cropping, dithering, packing into
|
|
the panel's exact pixel format) and hands the device a stream it can
|
|
write straight to SPI. The ESP32-C6 has no PSRAM and not much SRAM to
|
|
spare -- keeping it a dumb display client is what makes that workable.
|
|
- **Crops toward faces, not just the center**, using face bounding boxes
|
|
Immich already computed for its own People feature -- no bundled face
|
|
detector.
|
|
- **Refresh interval and album are configurable from a web UI**, no
|
|
reflashing needed to change them.
|
|
|
|
## Hardware
|
|
|
|
- ESP32-C6 dev board (8MB flash)
|
|
- [Waveshare 7.3" E Ink Spectra 6 (E6)](https://www.waveshare.com/7.3inch-e-paper-hat-e.htm) panel -- 800x480, 6-color, SPI
|
|
|
|
See [`docs/hardware.md`](docs/hardware.md) for wiring,
|
|
[`docs/architecture.md`](docs/architecture.md) for how the two halves talk
|
|
to each other, and [`docs/widgets.md`](docs/widgets.md) for the server's
|
|
placeable photos/calendar/whiteboard widget system.
|
|
|
|
## Getting started
|
|
|
|
1. **[`server/`](server/)** -- run the FastAPI server first (Docker
|
|
Compose, points at your Immich instance). See
|
|
[`server/README.md`](server/README.md).
|
|
2. **[`firmware/`](firmware/)** -- build and flash the ESP32-C6, then
|
|
scan the QR codes it draws on first boot to provision it. See
|
|
[`firmware/README.md`](firmware/README.md).
|
|
|
|
## Repo layout
|
|
|
|
```
|
|
firmware/ ESP-IDF project for the ESP32-C6
|
|
server/ FastAPI server: Immich -> crop/dither/pack -> the frame
|
|
docs/ Wiring and architecture notes
|
|
```
|
|
|
|
## License
|
|
|
|
MIT -- see [`LICENSE`](LICENSE). A few small pieces of vendored
|
|
third-party code (a QR code generator, a bitmap font table) keep their
|
|
own permissive licenses; see `LICENSE` for details.
|
|
|
|
---
|
|
|
|
Built with substantial assistance from [Claude Code](https://claude.com/claude-code).
|