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>
1.6 KiB
1.6 KiB
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, 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
# 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 thedialoutgroup — resolve both before attempting to flash. - Gateway speech deps are optional extras;
make setupalone runs the app and tests without GPU/ML packages.