esphome-waveshare-esp32-s3-audio-va/CHANGELOG.md

# Changelog

## [1.0.1] - 2026-09-20

Patch release fixing the mic gain control. Tagged `v1.0.1`; the example config
now pins this tag.

### Fixed
- **Mic gain slider snapped back to its old value in Home Assistant.** The
  `Mic gain (ES7210)` number had a `set_action` but was not `optimistic`, so the
  new value was never published back. The ES7210 was reprogrammed correctly (the
  device log showed the new gain), but HA kept displaying the previous value and
  reset the slider on the next visit. The number now publishes its state after
  every change.
- **A saved mic gain was not applied to the ES7210 after a reboot.** A template
  number restores its value from flash in `setup()` and publishes it, but does
  not run `set_action`, so HA showed the saved gain while the codec started at
  the default from `audio_adc`. `on_boot` (priority -100) now pushes the restored
  value to the ES7210. `set_mic_gain()` is safe to call there because the driver
  stores the value even before its own setup completes.

## [1.0.0] - 2026-07-18

First stable release. The full voice assistant is confirmed on hardware, the
regressions found during bring-up testing are fixed, and the project ships with
complete documentation and a wiki. Tagged `v1.0.0`; the example config pins this
tag so a build is reproducible instead of tracking a moving `main`.

### Fixed
- **Boot loop into safe mode after selecting a ring effect.** The three
  effect selects restore their saved option during `setup()` (at HARDWARE
  priority), which fired `on_value` and ran the LED state machine before the
  light/RMT and voice_assistant were initialised, painting an effect on an
  uninitialised strip and crashing the boot. The `on_value` is now gated on
  `init_in_progress` (cleared by `on_boot` at priority -100), so it only runs
  once setup is complete; a live effect change from HA still repaints the ring.

### Changed
- **Boot chime is now a bundled sound, not the wake-word beep.**
  `base/sounds/startup.mp3` (16 kHz mono, ~11 KB) plays on connect to HA and is
  swappable through the `boot_sound_file` substitution (any URL or local
  MP3/FLAC/WAV; the media player decodes all three).

### Removed
- **The Flicker ring effect** (weak visually); 15 effects remain.

## [0.2.0] - 2026-07-18

First on-hardware bring-up. The full voice assistant works: on-device wake word,
STT/intent/TTS, clean playback, no boot hiss - all on stock ESPHome components.

### Changed
- **Audio reworked to two I2S buses with the mic as master; the patched es8311
  and `force_master` are gone.** The board shares BCLK/LRCLK between the DAC and
  ADC, and ESPHome can't run one bus full-duplex (the speaker hits "Parent bus
  is busy"). Two buses over the shared pins, with the always-capturing mic
  mastering the clock and the speaker slaving to it, gives simultaneous capture
  and playback on stock components. The mic is pinned to 16-bit so its master
  frame matches the DAC (a 32-bit frame played back as noise).
- **The amplifier is gated on playback** (`ALWAYS_OFF` at boot, turned on by the
  media_player `on_state`) to remove the idle hiss the always-on amp produced
  before the first playback.
- **API encryption dropped** (LAN-only device); `secrets.yaml` is now just Wi-Fi.
  Re-enable it via the commented block in `base/core.yaml` if you want it.
- **Timers are visible in HA** (the "Next timer" / "Next timer name" sensors are
  no longer `disabled_by_default`).
- **Boot chime**: a short "ready" sound plays once the device connects to HA,
  played after the mic (I2S master) is clocking so the slave speaker can output
  it. New `boot_sound` switch toggles it. The sound ships with the repo
  (`base/sounds/startup.mp3`, 16 kHz mono) and is swappable via the
  `boot_sound_file` substitution (any URL or local MP3/FLAC/WAV).

### Added
- **Per-phase ring animation, pickable from HA.** New "Listening effect",
  "Thinking effect" and "Replying effect" selects choose the animation for those
  voice-assistant phases (the phase colour stays fixed). 15 effects to choose
  from: solid, three pulses, Breathe, Wipe, Scan, Spinner, Comet, Twinkle,
  Random Twinkle, Fireworks, Fire, and two rainbows. Breathe / Spinner /
  Comet / Fire are custom `addressable_lambda` effects.

### Fixed
- **The Pulse LED effects showed a solid colour instead of pulsing.** Their
  `update_interval` (16 ms) was shorter than the transition (300-1000 ms);
  `update_interval` is how often the pulse flips its brightness target, so it
  flipped faster than the brightness could move. Now ~2x the transition, with
  30-100% min/max brightness.
- Compile-time issues found during bring-up: a quoted `mclk_multiple`
  substitution (string vs the int a `cv.one_of` wants), a `template select`
  missing its `options:`, `select` `.state` -> `current_option()`, the dead
  microWakeWord model URLs (404), and a `/` in a switch name.

### Removed
- **The `stop` wake word.** This board has no usable hardware AEC, so the mic
  hears the device's own TTS far louder than the user; "stop" is detected only
  weakly and too late to be useful.
- **The daily-alarm entities** (Alarm time / Alarm on / Alarm action), the
  device-clock text sensor, and the diagnostic mic-disable switch are now
  `internal:` (hidden from HA). The logic stays; the clutter is gone.
- The dead "Mute and unmute sound" switch and its unused sound files.
- `components/es8311/` and the `external_components:` block - no longer needed.

## [0.1.0] - 2026-07-17

First cut. A working single-file config for the Waveshare ESP32-S3-AUDIO-Board,
restructured into a core package + a thin user config, with the patched
`es8311` component brought in-tree so nothing depends on an upstream repo that
has gone quiet.

### Added
- `base/core.yaml`: the always-on core with ES8311 speaker, ES7210 dual mic,
  on-device wake word (`alexa` + `okay_nabu`), the HA Assist pipeline,
  music/announcement mixing with ducking, the 7x WS2812 status ring state
  machine, the three onboard buttons, voice timers and an alarm clock.
- `waveshare-va.yaml`: thin user config. Pulls the core from GitHub at compile
  time, so it is the only file you keep.
- `components/es8311/`: vendored fork of ESPHome's `es8311` adding
  `force_master` + `mclk_multiple`. Origin, credits and the licensing situation
  are in the README.
- `docs/HARDWARE.md`: board pinout and the I2C device map.
- `skill/waveshare-esp32-s3-audio/`: Claude Code skill with pinout + gotchas.
- `scripts/validate.py`: offline YAML check (syntax, substitutions, duplicate
  ids) so a typo does not cost a dashboard round trip.
- `scripts/esplog.py`: stream device logs over the native API.

### Fixed
Bugs carried over from the config this started as:

- **The mic was stopped on every boot.** The `diag_disable_mic` check was
  inverted: with the switch in its default OFF position `on_boot` ran
  `micro_wake_word.stop` + `microphone.stop_capture`. It only ever recovered
  because `on_client_connected` restarted the wake word, so the switch also did
  not actually work, in either direction.
- **"Microphone Mute" did not mute.** It dropped the ES7210 gain to `0.0f`,
  but 0 dB is *unity* gain, not silence. The mic kept hearing the room and only
  the wake-word handler ignored it. It now uses ESPHome's own `microphone.mute`,
  which hands every consumer a zero-filled buffer, so the wake word hears actual
  silence with no I2S restart.
- **A test sound fired on every LED repaint during boot.** A leftover
  `id(play_sound).execute(1, id(wake_word_triggered_sound)); //TEST` sat in the
  `init_in_progress` branch of `control_leds`.
- **Wake word sensitivity did nothing.** The select only set cutoffs on
  `okay_nabu`, while the primary wake word is `alexa`. It now sets both.
- **Mic gain slider promised 42 dB.** The ES7210 caps at 37.5 dB and the driver
  silently clamps, so the top third of the slider was a lie. Range is now
  0 to 37.5 dB in 1.5 dB steps (the chip's real granularity), and the boot value
  in `audio_adc` matches the number entity instead of contradicting it (24 dB vs
  a 32 dB global).
- **The API encryption key was hard-coded in the config.** It now comes from
  `!secret api_encryption_key`.
- **The `time:` block was half-commented-out**, leaving `id: rtc` dangling under
  `platform: homeassistant`. Cleaned up. PCF85063 support is not in this build.
- **Two `on_boot: priority: -100` blocks** ran in an order nobody had chosen.
  Merged into one.

### Changed
- All pins, audio format and the HA-facing values are `substitutions:` with
  documented defaults, instead of literals scattered through the file.
- `${mic_channel_${which_mic}}` nested-substitution trickery replaced with two
  plainly named knobs: `mic_channel` (the I2S slot) and `mic_va_channel` (the
  index handed to Assist). These are genuinely different things and the old
  names implied they were the same one.
- Dropped dead substitutions (`i2s_bits_per_sample`, `i2s_mode_speaker`,
  `rtc_int`, `mic_channel_2`) and the now-unused `mic_gain_saved` global.
- Timezone is a `posix_timezone` substitution rather than a hard-coded `UTC0`.