# 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
```

## 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:

```bash
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:

```bash
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

```yaml
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`