74 lines
1.8 KiB
Markdown
74 lines
1.8 KiB
Markdown
# 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
|