EVS-Embedded-Voice-System/README.md

EVS - Embedded Voice System

ESP32-based voice client with:

• INMP441 microphone (I2S)
• PAM8403 amplifier (analog input from ESP32 DAC)
• WebSocket audio streaming to central bridge
• MQTT remote control
• optional UDP microphone stream (remote switchable)

Project Structure

• src/main.cpp: Firmware (audio, WiFi, WebSocket, MQTT commands, UDP stream)
• include/secrets.h: local environment values (not versioned)
• include/secrets.example.h: template for secrets.h
• bridge/: EVS bridge (WebSocket + MQTT + VAD + STT integration)
• stt-worker/: MQTT-based STT worker (vad_segment -> transcript)

Firmware Behavior

• On WebSocket connect: mode switches automatically to StreamToServer
• On WebSocket disconnect: mode switches automatically to Idle
• Serial commands (115200 baud):
  • p = print network and mode status
  • h = help

MQTT Remote Control

Topics:

• command: evs/<device_id>/command
• status: evs/<device_id>/status

Example commands:

• {"cmd":"status"}
• {"cmd":"mode","value":"idle"}
• {"cmd":"mode","value":"stream"}
• {"cmd":"io_mode","value":"mic"}
• {"cmd":"io_mode","value":"spk"}
• {"cmd":"udp_stream","enabled":true,"target_host":"10.100.3.247","target_port":5004}
• {"cmd":"udp_stream","enabled":false}

Status payload includes:

• current mode
• current io_mode (mic or spk)
• WS/MQTT connectivity
• UDP stream state and target (only relevant in mic mode)

ESP32 Setup

1. Copy include/secrets.example.h to include/secrets.h.
2. Set values in include/secrets.h:

• WiFi credentials
• EVS_BRIDGE_HOST
• EVS_WS_PORT, EVS_WS_PATH
• EVS_DEVICE_ID
• role config:
  • EVS_ENABLE_MIC
  • EVS_ENABLE_SPEAKER
  • EVS_DEFAULT_IO_MODE ("mic" or "spk")
  • EVS_SPK_DAC_PIN (25 or 26)
• optional MQTT overrides:
  • EVS_MQTT_HOST, EVS_MQTT_PORT
  • EVS_MQTT_USER, EVS_MQTT_PASSWORD
  • EVS_MQTT_BASE_TOPIC

3. Build/flash:

pio run -e esp32dev_core2 -t upload
pio device monitor -b 115200

Audio Format

• PCM16LE
• mono
• 16 kHz

Notes

• include/secrets.h is intentionally ignored in git.
• Speaker path is DAC-only (PWM removed):
  • GPIO25 (DAC1) or GPIO26 (DAC2) -> amplifier input (L+ or R+)
  • common GND between ESP32 and amplifier is mandatory
• INMP441 wiring (default in firmware):
  • WS -> GPIO25
  • SCK -> GPIO26
  • SD -> GPIO33
  • VDD -> 3V3
  • GND -> GND
• For newer Arduino core testing, esp32dev_core3 is available in platformio.ini.
• Bridge and STT worker details are in bridge/README.md and stt-worker/README.md.