Initial EVS client + bridge setup

bridge/README.md

@@ -0,0 +1,73 @@
+# EVS Bridge (Home Assistant + MQTT + WebSocket)
+
+This service is the audio bridge between your ESP32 client and your Home Assistant stack.
+
+It provides:
+- WebSocket endpoint for raw PCM audio (`/audio`)
+- MQTT status/events (`evs/<device_id>/status`)
+- MQTT playback input (`evs/<device_id>/play_pcm16le`)
+- Optional Home Assistant webhook callbacks (`connected`, `start`, `stop`, `disconnected`)
+
+## 1) Start the bridge
+
+1. Copy env template:
+```bash
+cp .env.example .env
+```
+2. Edit `.env`:
+- `MQTT_HOST`, `MQTT_USER`, `MQTT_PASSWORD`
+- `HA_WEBHOOK_URL` (optional)
+3. Start:
+```bash
+docker compose up -d --build
+```
+
+## 2) Configure ESP32
+
+In `src/main.cpp`:
+- no environment-specific values should be edited directly
+
+In `include/secrets.h`:
+- copy from `include/secrets.example.h`
+- set WiFi credentials
+- set bridge host
+- set WS port/path
+- set unique `EVS_DEVICE_ID`
+
+Then upload firmware.
+
+## 3) Test flow
+
+1. Flash ESP32
+2. Open serial monitor
+3. Send `s` (stream mode)
+4. In bridge logs, you should see the device connection
+5. If `ECHO_ENABLED=true`, incoming audio is returned to ESP32 speaker
+
+## 4) MQTT topics
+
+- Status/events published by bridge:
+  - `evs/<device_id>/status` (JSON)
+- Playback input to device:
+  - `evs/<device_id>/play_pcm16le`
+  - payload options:
+    - raw binary PCM16LE
+    - JSON `{ "pcm16le_b64": "<base64>" }`
+
+## 5) Home Assistant integration
+
+Use webhook for event hooks:
+- Configure `HA_WEBHOOK_URL` in `.env`
+- Bridge sends JSON with event and metadata on:
+  - `connected`
+  - `start`
+  - `stop`
+  - `disconnected`
+
+You can build automations on these events (for STT/TTS pipelines or Node-RED handoff).
+
+## 6) Notes
+
+- Audio format: PCM16LE, mono, 16 kHz
+- `SAVE_SESSIONS=true` stores `.wav` files in `bridge/data/sessions`
+- MQTT is recommended for control/events, WebSocket for streaming audio