gronod/esphome-waveshare-esp32-s3-audio-va
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Home
Pages
Audio architecture Configuration FAQ Hardware Home Installation LED ring Troubleshooting
Clone
3
Home
Michal Zaniewicz edited this page 2026-07-22 22:26:25 +02:00
Table of Contents

ESPHome Voice Assistant for the Waveshare ESP32-S3-AUDIO-Board

A Home Assistant voice satellite running on the Waveshare ESP32-S3-AUDIO-Board, the smart-speaker devkit with a dual-mic array, an ES8311 codec, three buttons and a 7-LED RGB ring. It is pure ESPHome with no custom C firmware: an always-on core you pull as a package, plus one thin config file you edit.

This wiki is the full guide. For a quick overview and the source, see the repository README.

What it does

  • Voice assistant: on-device wake word (alexa, okay_nabu) via micro_wake_word, the full Home Assistant Assist pipeline (STT, intent, TTS), a wake beep and music ducking while it listens.
  • Simultaneous music and announcements: a mixer speaker blends the media and announcement pipelines, so an announcement ducks the music instead of fighting it. Both are exposed to Music Assistant.
  • LED ring: a single state machine drives it. Boot, no Wi-Fi, no HA, listening, thinking, replying, timer counting, ringing and volume changed are each a distinct colour or effect. Brightness and the animation for the listening, thinking and replying phases are pickable from Home Assistant: solid plus 14 animations.
  • Timers: set by voice, with an on-ring countdown and a "Next timer" sensor in Home Assistant.
  • Buttons: the three onboard keys do volume down, play-pause, volume up.
  • Boot chime: a short sound once the device connects to Home Assistant, toggleable and swappable.
  • Tunable live from Home Assistant: microphone mute, mic gain, LED brightness and wake-word sensitivity are entities, so there is no reflashing to tune it.

Where to go next

  • Installation: first flash, Home Assistant setup, updating.
  • Configuration: every substitution and every Home Assistant entity.
  • Audio architecture: the shared-I2S two-bus design, in depth.
  • LED ring: the state machine and every ring effect.
  • Hardware: pinout, I2C map and sourced gotchas.
  • Troubleshooting: boot loops, no sound, wake word, safe mode.
  • FAQ: short answers to common questions.

Requirements

  • A Waveshare ESP32-S3-AUDIO-Board.
  • Home Assistant with the ESPHome integration and an Assist pipeline.
  • ESPHome 2025.8.0 or newer.

Guide

Links