From 664a23c48dd2e7c8b9d1a5cd9bdf73677d9e24c3 Mon Sep 17 00:00:00 2001
From: Kai <kai@local>
Date: Fri, 13 Feb 2026 10:13:36 +0100
Subject: [PATCH] Add root README with project overview and setup

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..972ddff
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# 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
+
+## Ziel
+
+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
+
+## Projektstruktur
+
+- `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)
+
+## Firmware-Modi
+
+Serielle Kommandos (`115200 Baud`):
+- `l` = Local Loopback (Mic direkt auf Speaker)
+- `s` = Stream to Server (Audio zur Bridge)
+- `i` = Idle
+- `p` = Netzwerkstatus
+- `h` = Hilfe
+
+## Setup (ESP32)
+
+1. `include/secrets.example.h` nach `include/secrets.h` kopieren.
+2. In `include/secrets.h` setzen:
+- WiFi-Zugang
+- `EVS_BRIDGE_HOST`
+- `EVS_WS_PORT`, `EVS_WS_PATH`
+- `EVS_DEVICE_ID`
+3. Firmware bauen/flashen:
+```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
+
+- PCM16LE
+- Mono
+- 16 kHz
+
+## Hinweise
+
+- `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`.