Add EVS control portal, io_mode switching, and DAC-only speaker path

README.md

@@ -1,68 +1,89 @@
 # EVS - Embedded Voice System
 
-ESP32-basierter Voice-Client mit:
-- `INMP441` als Mikrofon (I2S)
-- `PAM8403` als Verstärker (PWM-Audio vom ESP32)
-- WebSocket-Audio-Streaming zur zentralen Bridge
-- optionaler Home-Assistant/MQTT-Integration
+ESP32-based voice client with:
+- `INMP441` microphone (I2S)
+- `PAM8403` amplifier (analog input from ESP32 DAC)
+- WebSocket audio streaming to central bridge
+- MQTT remote control
+- optional UDP microphone stream (remote switchable)
 
-## Ziel
+## Project Structure
 
-Dieses Projekt bildet die Basis für eine lokale "Echo-Alternative":
-- Audioaufnahme am ESP32
-- Verarbeitung zentral (z. B. Home Assistant / Container)
-- Audioantwort zurück an den ESP32-Lautsprecher
+- `src/main.cpp`: Firmware (audio, WiFi, WebSocket, MQTT commands, UDP stream)
+- `include/secrets.h`: local environment values (not versioned)
+- `include/secrets.example.h`: template for `secrets.h`
+- `bridge/`: EVS bridge (WebSocket + MQTT + VAD + STT integration)
+- `stt-worker/`: MQTT-based STT worker (`vad_segment` -> `transcript`)
 
-## Projektstruktur
+## Firmware Behavior
 
-- `src/main.cpp`: Firmware (Audio, WiFi, WebSocket, Modi)
-- `include/secrets.h`: lokale Umgebungswerte (nicht versioniert)
-- `include/secrets.example.h`: Vorlage für `secrets.h`
-- `bridge/`: Dockerisierte EVS-Bridge (WebSocket + MQTT + HA-Hooks)
+- On WebSocket connect: mode switches automatically to `StreamToServer`
+- On WebSocket disconnect: mode switches automatically to `Idle`
+- Serial commands (`115200 baud`):
+  - `p` = print network and mode status
+  - `h` = help
 
-## Firmware-Modi
+## MQTT Remote Control
 
-Serielle Kommandos (`115200 Baud`):
-- `l` = Local Loopback (Mic direkt auf Speaker)
-- `s` = Stream to Server (Audio zur Bridge)
-- `i` = Idle
-- `p` = Netzwerkstatus
-- `h` = Hilfe
+Topics:
+- command: `evs/<device_id>/command`
+- status: `evs/<device_id>/status`
 
-## Setup (ESP32)
+Example commands:
+- `{"cmd":"status"}`
+- `{"cmd":"mode","value":"idle"}`
+- `{"cmd":"mode","value":"stream"}`
+- `{"cmd":"io_mode","value":"mic"}`
+- `{"cmd":"io_mode","value":"spk"}`
+- `{"cmd":"udp_stream","enabled":true,"target_host":"10.100.3.247","target_port":5004}`
+- `{"cmd":"udp_stream","enabled":false}`
 
-1. `include/secrets.example.h` nach `include/secrets.h` kopieren.
-2. In `include/secrets.h` setzen:
-- WiFi-Zugang
+Status payload includes:
+- current mode
+- current `io_mode` (`mic` or `spk`)
+- WS/MQTT connectivity
+- UDP stream state and target (only relevant in `mic` mode)
+
+## ESP32 Setup
+
+1. Copy `include/secrets.example.h` to `include/secrets.h`.
+2. Set values in `include/secrets.h`:
+- WiFi credentials
 - `EVS_BRIDGE_HOST`
 - `EVS_WS_PORT`, `EVS_WS_PATH`
 - `EVS_DEVICE_ID`
-3. Firmware bauen/flashen:
+- role config:
+  - `EVS_ENABLE_MIC`
+  - `EVS_ENABLE_SPEAKER`
+  - `EVS_DEFAULT_IO_MODE` (`"mic"` or `"spk"`)
+  - `EVS_SPK_DAC_PIN` (`25` or `26`)
+- optional MQTT overrides:
+  - `EVS_MQTT_HOST`, `EVS_MQTT_PORT`
+  - `EVS_MQTT_USER`, `EVS_MQTT_PASSWORD`
+  - `EVS_MQTT_BASE_TOPIC`
+3. Build/flash:
 ```bash
 pio run -e esp32dev_core2 -t upload
 pio device monitor -b 115200
 ```
 
-## Setup (Bridge)
-
-1. In `bridge/` wechseln.
-2. `.env.example` nach `.env` kopieren und Werte setzen.
-3. Bridge starten:
-```bash
-docker compose up -d --build
-```
-
-Standard-WebSocket-Endpunkt:
-- `ws://<bridge-host>:8765/audio`
-
-## Audioformat
+## Audio Format
 
 - PCM16LE
-- Mono
+- mono
 - 16 kHz
 
-## Hinweise
+## Notes
 
-- `include/secrets.h` ist absichtlich in `.gitignore`.
-- Für den Core-3-Test ist in `platformio.ini` eine eigene Environment vorbereitet.
-- Details zur Bridge findest du in `bridge/README.md`.
+- `include/secrets.h` is intentionally ignored in git.
+- Speaker path is DAC-only (PWM removed):
+  - `GPIO25` (DAC1) or `GPIO26` (DAC2) -> amplifier input (`L+` or `R+`)
+  - common `GND` between ESP32 and amplifier is mandatory
+- INMP441 wiring (default in firmware):
+  - `WS` -> `GPIO25`
+  - `SCK` -> `GPIO26`
+  - `SD` -> `GPIO33`
+  - `VDD` -> `3V3`
+  - `GND` -> `GND`
+- For newer Arduino core testing, `esp32dev_core3` is available in `platformio.ini`.
+- Bridge and STT worker details are in `bridge/README.md` and `stt-worker/README.md`.