# 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