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

# Changelog

## [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`.