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

1.1) Registry image naming

Recommended image path in your Gitea registry:

• git.khnm-zimmerling.de/kai/evs-bridge:latest
• git.khnm-zimmerling.de/kai/evs-bridge:v0.1.0

Recommended tags:

• latest for current default deployment
• vX.Y.Z for stable releases

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

7) Build and push to Gitea registry

From repository root:

docker login git.khnm-zimmerling.de
docker build -f bridge/Dockerfile -t git.khnm-zimmerling.de/kai/evs-bridge:latest bridge
docker push git.khnm-zimmerling.de/kai/evs-bridge:latest

Optional release tag:

docker tag git.khnm-zimmerling.de/kai/evs-bridge:latest git.khnm-zimmerling.de/kai/evs-bridge:v0.1.0
docker push git.khnm-zimmerling.de/kai/evs-bridge:v0.1.0

8) Portainer stack with registry image

services:
  evs-bridge:
    image: git.khnm-zimmerling.de/kai/evs-bridge:latest
    container_name: evs-bridge
    restart: unless-stopped
    ports:
      - "8765:8765"
    environment:
      WS_HOST: "0.0.0.0"
      WS_PORT: "8765"
      WS_PATH: "/audio"
      ECHO_ENABLED: "true"
      LOG_LEVEL: "INFO"
      MQTT_ENABLED: "true"
      MQTT_HOST: "10.100.3.247"
      MQTT_PORT: "1883"
      MQTT_USER: ""
      MQTT_PASSWORD: ""
      MQTT_BASE_TOPIC: "evs"
      MQTT_TTS_TOPIC: "evs/+/play_pcm16le"
      MQTT_STATUS_RETAIN: "true"
      HA_WEBHOOK_URL: ""
      SAVE_SESSIONS: "true"
      SESSIONS_DIR: "/data/sessions"
      PCM_SAMPLE_RATE: "16000"
    volumes:
      - evs_bridge_data:/data

volumes:
  evs_bridge_data:

9) Optional: auto-push via Gitea Actions

Workflow file:

• .gitea/workflows/bridge-image.yml

Required repository secrets:

• REGISTRY_USERNAME
• REGISTRY_TOKEN

The workflow builds bridge/Dockerfile and pushes:

• git.khnm-zimmerling.de/kai/evs-bridge:latest