ha-esphome-voice-satellite-add

HA ESPHome Voice Satellite Add

Spec: spec/claude/ha-esphome-voice-satellite-add/en.md (EN canonical) / spec/claude/ha-esphome-voice-satellite-add/de.md (DE translation). Grounding specs: spec/ha/esp32-s3-box/en.md §Audio binding / §Voice-assistant binding (device side) and spec/ha/assist-pipeline/en.md (Home Assistant side).

Binds the voice path of one device per invocation, and states plainly which half of the result lives in Home Assistant rather than in the YAML.

Why this is a skill, not an agent

• Mid-flow approval is the contract (decisive): the board generation, the wake-word placement, and the engine consequences are decisions with hardware and privacy weight — a wrong codec pair addresses ICs that are not on the board, and server-side wake word means satellites stream continuously.
• Two-sided result: the device YAML is written here, the pipeline is configured by the operator in Home Assistant; that handover is a conversation, not a report.
• Counter-dimension considered: the pin and codec lookup per generation is mechanical (agent bias), but it is inseparable from the "which generation is actually in hand" question the operator answers; skill wins.

When this skill activates

The user wants an ESPHome device to hear and speak — "mach die Box zum Assist-Satelliten", "add wake word to this device", "wire the microphone and speaker".

When NOT to activate

• what the screen shows during a pipeline run → ha-esphome-display-author
• a Home-Assistant-driven value or command unrelated to voice → ha-esphome-binding-add
• a sensor, bus, or component → ha-esphome-config-augment
• custom sentences, intent_script, or automations reacting to the satellite → ha-automation-solution
• installing or hosting the speech engines (Wyoming services, Supervisor apps) → the operator's Home Assistant host

Hard rules

1. Read both grounding specs first, plus the device file and its packages. Never generate pins, codecs, or component keys from memory.
2. Determine the board generation before writing anything, and record it in the config. The backlight ⇄ LRCLK swap between generations produces a device that boots and logs normally while showing nothing or staying silent.
3. Bind the codec pair the board actually carries. An es7210 / es8311 pair on a board fitted with es7243e / es8156 addresses ICs that do not exist there. Declare the converters as external, and keep the deliberate 16 kHz capture / 48 kHz playback asymmetry.
4. State bits_per_sample: 16bit explicitly on the microphone rather than relying on the 32-bit platform default — a silent mismatch produces noise, not an error — and set adc_type: external.
5. Expose the power amplifier as a GPIO switch with restore_mode: RESTORE_DEFAULT_ON. With it disabled the pipeline runs and logs normally while the speaker stays silent.
6. voice_assistant: binds a microphone and a response path. The schema enforces neither — every key is optional — so a device that binds nothing validates cleanly and does nothing. This is a portfolio rule the skill applies.
7. Prefer on-device wake word (micro_wake_word: with the pipeline started from on_wake_word_detected), and where the placement is offered at runtime, switch between micro_wake_word.start and voice_assistant.start_continuous rather than deciding it at compile time.
8. A discoverable mute is mandatory. A voice device without one is a privacy defect, not a missing convenience; wire it to microphone.mute / microphone.unmute and reflect the muted state.
9. Handle the disconnected cases explicitly — dedicated no-Wi-Fi and no-Home-Assistant states, wake-word processing stopped when the API client disconnects — and keep the ap: fallback plus captive_portal: recovery path intact.
10. Never duplicate the pipeline's own text-to-speech with a manual tts.speak for the same response; that produces doubled or overlapping audio.
11. Tune gain once in the chain. Either the audio ADC's mic_gain or the pipeline's auto_gain / volume_multiplier — not both, and record which was chosen and why.
12. Report the Home-Assistant-side steps rather than pretending they are done: one pipeline per language with an explicit per-satellite assignment, the engine choice against documented host capacity (a speech-to-text engine that does not support naming a timer strips that feature), the assist_satellite entity binding with any deprecated voice binary sensors migrated, minimal entity exposure as a security boundary, and the debugging order — sentence parser, then pipeline debug, then time-boxed debug recording that is deleted afterwards.
13. One device per run. No deploy. The run ends at the edited file, the Home-Assistant checklist, and the validation report.