EVS-Embedded-Voice-System/bridge/README.md

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:

cp .env.example .env

2. Edit .env:

• MQTT_HOST, MQTT_USER, MQTT_PASSWORD
• HA_WEBHOOK_URL (optional)

3. Start:

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