Initial scaffold: ESP32-P4 firmware + voice gateway for Tatlock endpoint

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>
2026-07-14 16:58:59 +02:00
commit 576fd7d237
20 changed files with 622 additions and 0 deletions
@@ -0,0 +1,72 @@
+# DeskLock
+
+A living-room visual/audio endpoint for **Tatlock**, the homelab butler. DeskLock gives
+Tatlock a face and a voice on a Waveshare round touch display: you talk to it, it listens,
+thinks, and answers — the first line of contact with the butler backend running on
+tower-of-joy.
+
+## Hardware
+
+**Waveshare ESP32-P4-WIFI6-Touch-LCD-3.4C**
+
+| Component | Details |
+|-----------|---------|
+| SoC | ESP32-P4NRW32 — dual-core RISC-V @ 400 MHz + LP core |
+| Memory | 32 MB PSRAM (in-package), 32 MB NOR flash |
+| Display | 3.4" round IPS, 800×800, MIPI-DSI 2-lane, capacitive touch |
+| Radio | ESP32-C6-MINI-1 (Wi-Fi 6 + BLE 5) over SDIO via ESP-Hosted |
+| Audio in | Dual onboard microphones + ES7210 echo-cancellation ADC |
+| Audio out | ES8311 codec, PH2.0 2-pin speaker connector (8Ω 2W recommended) |
+| Flashing | USB-C (hold BOOT during reset for download mode) |
+
+The device is currently connected over USB-C directly to tower-of-joy, so build/flash
+happens on this server.
+
+## Architecture
+
+```
+┌─────────────────────┐        WebSocket (PCM audio + JSON events)
+│  DeskLock device    │◄──────────────────────────────────────────┐
+│  (ESP32-P4)         │                                           │
+│                     │        ┌──────────────────────────────────┴──┐
+│  • LVGL face        │        │  DeskLock Gateway (container)        │
+│  • Touch input      │        │  on tower-of-joy                     │
+│  • Mic capture+AEC  │        │                                      │
+│  • TTS playback     │        │  • STT: faster-whisper (GPU)         │
+└─────────────────────┘        │  • TTS: Piper                        │
+                               │  • Chat: Tatlock /v1/chat/completions│
+                               └──────────────────┬───────────────────┘
+                                                  │ HTTP (LAN, :8000)
+                                       ┌──────────┴──────────┐
+                                       │  Tatlock (butler)   │
+                                       │  tatlock.schweitz.  │
+                                       │  internal           │
+                                       └─────────────────────┘
+```
+
+Tatlock stays a text-only brain. The **gateway** is Tatlock's ears and mouth: it converts
+speech to text on the way in and text to speech on the way out, keeping the device firmware
+thin (audio transport + face rendering only).
+
+See [docs/architecture.md](docs/architecture.md) for the full design.
+
+## Repository layout
+
+- `firmware/` — ESP-IDF (C, LVGL 9) application for the ESP32-P4
+- `gateway/` — Python FastAPI voice gateway, deployed as a container on tower-of-joy
+- `docs/` — architecture and design notes
+
+## Roadmap
+
+1. **Bring-up** — ESP-IDF toolchain, build/flash, BSP display + Wi-Fi working
+2. **Face** — LVGL face with idle/listening/thinking/speaking states, clock while idle
+3. **Voice (touch-to-talk)** — tap to talk → gateway → Tatlock → spoken reply
+4. **Wake word** — esp-sr WakeNet on-device, echo cancellation, barge-in
+5. **Polish** — Tatlock-initiated notifications, presence, OTA updates
+
+## References
+
+- [Waveshare wiki: ESP32-P4-WIFI6-Touch-LCD-3.4C](https://www.waveshare.com/wiki/ESP32-P4-WIFI6-Touch-LCD-3.4C)
+- [Official examples repo (waveshareteam/ESP32-P4-WIFI6-Touch-LCD-XC)](https://github.com/waveshareteam/ESP32-P4-WIFI6-Touch-LCD-XC)
+- [BSP component: waveshare/esp32_p4_wifi6_touch_lcd_xc](https://components.espressif.com/components/waveshare/esp32_p4_wifi6_touch_lcd_xc)
+- Tatlock backend: `/mnt/media/Projects/tatlock` — https://tatlock.schweitz.net