Bouwplan S3R voice satellite

docs/build-plan.md

@@ -0,0 +1,56 @@
+# Bouwplan: ATOM VoiceS3R als HA-voice-satelliet
+
+## Waarom dit board
+
+ESP32-S3-PICO-1-N8R8 met 8 MB PSRAM: genoeg voor on-device wake word
+(microWakeWord, "Okay Nabu"). ES8311-codec, MEMS-mic, NS4150B + 1 W
+speaker, plus IR-zender als bonus.
+
+## Stap 1 — Voice-pipeline in Home Assistant (eenmalig)
+
+STT + TTS achter Assist. Twee routes:
+
+- **HA OS / Supervised:** add-ons *Whisper* + *Piper* (Instellingen →
+  Add-ons). Whisper-model **small** of **medium** voor Nederlands
+  (tiny/base is te zwak). Bij Piper een `nl_*`-stem downloaden.
+  openWakeWord-add-on is **niet** nodig (wake word draait on-device).
+- **HA Container:** `rhasspy/wyoming-whisper` en `rhassmy/wyoming-piper`
+  als Docker-containers, daarna als Wyoming-integraties toevoegen.
+
+Daarna: Instellingen → Spraakassistenten → Assist-pipeline met NL als
+taal, Whisper als STT, Piper als TTS.
+
+## Stap 2 — ESPHome-firmware
+
+ESPHome Builder-add-on installeren + in zijbalk. Nieuw device, naam
+`atom-echos3r-voice-assistant`, ESP32-S3, board `esp32s3box`.
+Gegenereerde API-key kopieren en de YAML uit
+`../esphome/atom-echos3r-voice-assistant.yaml` gebruiken (drie
+placeholders invullen: API-key, OTA-wachtwoord, wifi via secrets).
+
+## Stap 3 — Flashen
+
+USB-C **datakabel**. Reset ingedrukt houden tot groene LED brandt, dan
+loslaten (= download mode). In ESPHome op Install → bij voorkeur
+*manual download* (factory-format) → flashen via https://web.esphome.io
+→ resetten. Eerste compilatie duurt lang; normaal.
+
+## Stap 4 — Koppelen en testen
+
+Na reboot: discovery onder Instellingen → Apparaten → ESPHome →
+toevoegen → NL-pipeline selecteren. Test: "Okay Nabu, doe het licht in
+de woonkamer aan". Geen wake word: eerst pipeline/add-ons checken, pas
+daarna aan YAML komen. Ziet de browser het board niet: kabel (data!),
+download mode, serial-permissies.
+
+## Stap 5 — Eerste automatisering
+
+Zie `../automations/s3r-rooktest.yaml`: gesproken melding bij
+zonsondergang als rooktest. Daarna uitbreiden: deurbel, wasmachine-klaar
+via stekker-vermogen, WAN-IP-wissel, etc.
+
+## Volgorde-advies
+
+Pipeline (stap 1) eerst testen met de browser-mic in HA, dan pas
+flashen. Zo weet je bij problemen zeker dat het aan het board ligt en
+niet aan Whisper/Piper.