Configuration
Two layers: a handful of substitutions in your thin waveshare-va.yaml, and
the day-to-day settings that live as Home Assistant entities (no reflashing
to change them).
Substitutions (thin config)
These are the only values most people touch. They sit at the top of
waveshare-va.yaml.
| Substitution | Default | What it does |
|---|---|---|
name / friendly_name |
waveshare-va / Waveshare Voice |
Device name. Changing name re-creates every entity in Home Assistant. |
posix_timezone |
CET-1CEST,M3.5.0,M10.5.0/3 |
Clock zone in POSIX form; the device has no IANA database. DST is automatic. Copy yours from the posix_tz_db list. Home Assistant can also push a zone at runtime, which overrides this and is remembered. |
volume_min / volume_max |
0.4 / 0.8 |
Media-player volume clamps (0.0 to 1.0). The onboard amp distorts near the top, so the usable window is limited. |
hidden_ssid |
false |
Set to true to enable fast_connect for a hidden SSID. |
boot_sound_file |
bundled startup.mp3 |
The connect-to-HA chime. Any URL or local file; MP3, FLAC or WAV. See Boot and wake sounds. |
Pins, the audio format and the voice-assistant phase ids are substitutions too,
but they live in base/core.yaml and you should not need them unless you are
porting to another board. See Hardware for the pin map.
Home Assistant entities
After the device is added, these appear under it. Grouped by what they do.
Voice and audio
| Entity | Type | Notes |
|---|---|---|
| Media player | media_player | Playback and volume. Exposed to Music Assistant. Clamped by volume_min/volume_max. |
| Microphone Mute | switch | A true mute: the microphone hands every consumer a zero-filled buffer, so the wake word hears silence. The stream keeps running, so there is no restart. |
| Mic gain (ES7210) | number | Analog mic gain, 0 to 37.5 dB in 1.5 dB steps (the chip's real granularity). |
| Wake word sensitivity | select | Cutoffs for both wake words: Slightly / Moderately / Very sensitive. |
| Wake sound | switch | The beep played when a wake word is detected. |
| Boot sound | switch | The chime played once on connect to Home Assistant. |
| Amplifier | switch | Power to the Class-D amp. Off at boot and turned on automatically when playback starts; you normally leave it alone. |
LED ring
| Entity | Type | Notes |
|---|---|---|
| Status Ring | light | The 7-LED ring. Controllable, but the state machine repaints it, so manual changes are transient. |
| LED Ring Brightness | number | Ring brightness, applied by every effect. |
| Listening effect | select | Ring animation while listening. See LED ring. |
| Thinking effect | select | Ring animation while thinking. |
| Replying effect | select | Ring animation while replying. |
Timers, buttons, system
| Entity | Type | Notes |
|---|---|---|
| Next timer | sensor | Seconds left on the nearest voice timer. |
| Next timer name | sensor | Name of that timer. |
| Key1 / Key2 / Key3 | binary_sensor | The three onboard buttons (volume down, play-pause, volume up). |
| Restart | button | Reboot. Disabled by default; enable it on the device page if you want it. |
| Logger Level | select | ESPHome log verbosity. Disabled by default. |
Hidden by default
A daily-alarm engine and some diagnostics are present in the firmware but marked
internal, so they do not clutter Home Assistant: the alarm entities (Alarm
time, Alarm on, Alarm action), the device clock, the internal timer-ringing flag,
the diagnostic mic-disable switch and the Factory Reset button. The logic still
runs; only the entities are hidden.
Boot and wake sounds
The boot chime ships with the repository as base/sounds/startup.mp3 (16 kHz
mono, about 11 KB). To use your own, point boot_sound_file at any URL or local
file in your thin config:
substitutions:
boot_sound_file: https://example.com/my-chime.mp3
The media player decodes MP3, FLAC and WAV. Note that the board resamples all playback to 16 kHz mono, so a high-bitrate stereo source buys nothing on this speaker; a 16 kHz mono file is the same on playback and far smaller.
The wake beep and the timer-finished sound come from the Home Assistant Voice PE
sound set, referenced by URL in base/core.yaml.
API encryption
The native API is unencrypted by default, which is fine for a LAN-only device. To
enable encryption, uncomment the encryption: block under api: in
base/core.yaml, then add the key to secrets.yaml:
api_encryption_key: "PUT_YOUR_OWN_BASE64_KEY_HERE"
Generate a key from the ESPHome API docs.