Installation

Installation

The firmware is split in two: a small config file you keep locally (waveshare-va.yaml) and the always-on core (base/core.yaml), which is pulled from GitHub at compile time. You only ever edit the thin file.

Requires ESPHome 2025.8.0 or newer.

1. Get the two local files

From the repository, take:

• waveshare-va.yaml: your config.
• secrets.example.yaml: the template for credentials.

Copy secrets.example.yaml to secrets.yaml and fill in your Wi-Fi:

wifi_ssid: "YOUR_WIFI_SSID"
wifi_password: "YOUR_WIFI_PASSWORD"

The native API is unencrypted by default (this is a LAN-only device). If you want encryption, enable it in the commented block in base/core.yaml and add the base64 key to secrets.yaml as well. See Configuration.

2. Edit the thin config

Open waveshare-va.yaml and set the substitutions at the top:

substitutions:
  name: waveshare-va
  friendly_name: "Waveshare Voice"
  posix_timezone: "CET-1CEST,M3.5.0,M10.5.0/3"   # your zone in POSIX form
  volume_min: '0.4'
  volume_max: '0.8'
  hidden_ssid: 'false'

Every field is explained in Configuration. The packages: block below pins the release; leave it as is for a stable build.

3. First flash over USB

The first flash has to happen over USB; after that, updates go over the network.

With the ESPHome command line:

esphome run waveshare-va.yaml

Or with the ESPHome dashboard: drop waveshare-va.yaml and secrets.yaml into /config/esphome/, open the device and hit Install, then Plug into this computer for the first flash.

The board flashes over its USB-C port. If the board does not appear as a serial port, hold BOOT while plugging it in to force download mode.

4. Add it in Home Assistant

1. The new ESPHome device is discovered automatically. Add it.
2. Open the device, choose Configure, and assign an Assist pipeline (your STT, conversation agent and TTS).
3. Optionally assign it to an Area so voice intents can target "this room".

5. Test

Say "Alexa" (or "OK Nabu"). The ring should turn violet and you should hear the wake beep. Ask something, and the reply plays back through the speaker.

If nothing happens, see Troubleshooting.

Updating

The example config pins the v1.0.0 release tag, so a build is reproducible. To move to a newer release:

1. Change ref: in the packages: block of waveshare-va.yaml to a later tag, or to main to track the latest.

2. Clear the package cache and rebuild:

   esphome clean waveshare-va.yaml
   esphome run   waveshare-va.yaml
   

The esphome clean step matters: without it the old cached copy of the core is reused and your change is not picked up. In the dashboard the equivalent is Clean Build Files before Install.