jpmschweitzerandClaude Fable 5
576fd7d237
DeskLock gives the Tatlock butler a face and voice on a Waveshare ESP32-P4-WIFI6-Touch-LCD-3.4C round display in the living room. - firmware/: ESP-IDF project targeting esp32p4 with the Waveshare XC BSP - gateway/: FastAPI voice bridge (faster-whisper STT, Tatlock chat, Piper TTS) - docs/architecture.md: component design and device<->gateway WS protocol Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
39 lines
1.6 KiB
Markdown
39 lines
1.6 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 is not yet installed on this machine** — install instructions in AGENTS.md.
|
|
- The firmware scaffold has never been built; treat BSP calls and sdkconfig as
|
|
provisional until first successful `idf.py build` (see warning in AGENTS.md).
|
|
- The device flashes over USB-C on this server, but it doesn't currently enumerate
|
|
(`/dev/ttyACM*` empty) and this user lacks the `dialout` group — resolve both before
|
|
attempting to flash.
|
|
- Gateway speech deps are optional extras; `make setup` alone runs the app and tests
|
|
without GPU/ML packages.
|