jpmschweitzerandClaude Fable 5
450bac1c81
- firmware boots to a rendered LVGL face in 1.57s (eyes + smile + tag) - sdkconfig: CONFIG_IDF_EXPERIMENTAL_FEATURES=y unlocks SPIRAM 200MHz (silently degraded to 20MHz before -> MIPI-DSI underrun -> LVGL lock starvation -> task watchdog); mirrors official 08_lvgl_demo_v9 config - architecture.md: power management section (user prime concern) — active/ambient/dormant/night ladder, levers, hard edges, <=300ms wake - AGENTS/CLAUDE: replace stale bring-up warnings with verified commands Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
42 lines
1.8 KiB
Markdown
42 lines
1.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
Claude Code-specific notes for this project. For architecture, hard rules, and full
|
|
command reference — see [AGENTS.md](AGENTS.md), and read it before starting work.
|
|
|
|
## Quick orientation
|
|
|
|
DeskLock = firmware for a Waveshare ESP32-P4 round-display device (`firmware/`, ESP-IDF/C/LVGL)
|
|
plus a voice gateway container (`gateway/`, Python/FastAPI, port 8600) that bridges device
|
|
audio to the Tatlock butler API. The device↔gateway WebSocket protocol lives in
|
|
`docs/architecture.md` and must stay in sync with both implementations.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Firmware (requires `source ~/esp-idf/export.sh` first; IDF ≥ 5.4)
|
|
cd firmware && idf.py build
|
|
idf.py -p /dev/ttyACM0 flash monitor
|
|
|
|
# Gateway
|
|
cd gateway && make setup # once
|
|
make run # dev server :8600
|
|
make test # pytest; single test: .venv/bin/pytest tests/test_health.py -k healthz
|
|
make lint typecheck
|
|
```
|
|
|
|
## Gotchas
|
|
|
|
- ESP-IDF v5.5 lives at `~/esp-idf` (`source ~/esp-idf/export.sh`). Flash via
|
|
`sg dialout -c …` (see AGENTS.md) — the login session predates dialout membership.
|
|
- **PSRAM 200 MHz requires `CONFIG_IDF_EXPERIMENTAL_FEATURES=y`** — without it the
|
|
option silently degrades to 20 MHz and the DSI display underruns into a watchdog
|
|
loop. Details in AGENTS.md.
|
|
- Gateway speech deps are optional extras; `make setup` alone runs the app and tests
|
|
without GPU/ML packages. `make setup` uses `python3.12` (system python3 is 3.8).
|
|
- Tatlock replies open with a `<think>` block — always strip via
|
|
`tatlock.strip_reasoning()` before TTS or display.
|
|
- Low power is a prime user requirement: see "Power management" in
|
|
docs/architecture.md before touching the face/render loop.
|