"update"

.claude/settings.local.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "includeCoAuthoredBy": false,
+  "permissions": {
+    "allow": [
+      "Bash",
+      "BashOutput",
+      "Edit",
+      "Glob",
+      "Grep",
+      "KillShell",
+      "NotebookEdit",
+      "Read",
+      "SlashCommand",
+      "Task",
+      "TodoWrite",
+      "WebFetch",
+      "WebSearch",
+      "Write",
+      "mcp__ide",
+      "mcp__exa",
+      "mcp__context7",
+      "mcp__mcp-deepwiki",
+      "mcp__Playwright",
+      "mcp__spec-workflow",
+      "mcp__open-websearch",
+      "mcp__serena",
+      "all",
+      "Bash(cd:*)"
+    ],
+    "deny": [],
+    "ask": []
+  },
+  "hooks": {},
+  "alwaysThinkingEnabled": true,
+  "outputStyle": "default",
+  "statusLine": {
+    "type": "command",
+    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
+    "padding": 0
+  }
+}

app.py

@@ -0,0 +1,79 @@
+"""
+Reachy Mini Home Assistant Voice Assistant App
+
+This app integrates Reachy Mini with Home Assistant via ESPHome protocol,
+allowing voice control through Home Assistant's voice assistant pipeline.
+"""
+
+import threading
+import logging
+import asyncio
+from typing import Optional
+
+from reachy_mini import ReachyMini
+from reachy_mini.apps import ReachyMiniApp
+
+from reachy_mini_ha_voice.voice_assistant import VoiceAssistantService
+
+logger = logging.getLogger(__name__)
+
+
+class HomeAssistantVoiceApp(ReachyMiniApp):
+    """
+    Reachy Mini Home Assistant Voice Assistant Application.
+
+    This app runs an ESPHome-compatible voice satellite that connects
+    to Home Assistant for STT/TTS processing while providing local
+    wake word detection and robot motion feedback.
+    """
+
+    # No custom web UI needed - configuration is automatic
+    custom_app_url: Optional[str] = None
+
+    def run(self, reachy_mini: ReachyMini, stop_event: threading.Event) -> None:
+        """
+        Main application entry point.
+
+        Args:
+            reachy_mini: The Reachy Mini robot instance
+            stop_event: Event to signal graceful shutdown
+        """
+        logger.info("Starting Home Assistant Voice Assistant...")
+
+        # Create and run the voice assistant service
+        service = VoiceAssistantService(reachy_mini)
+
+        # Run the async service in an event loop
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        try:
+            loop.run_until_complete(service.start())
+
+            logger.info("=" * 50)
+            logger.info("Home Assistant Voice Assistant Started!")
+            logger.info("=" * 50)
+            logger.info("ESPHome Server: 0.0.0.0:6053")
+            logger.info("Wake word: Okay Nabu")
+            logger.info("=" * 50)
+            logger.info("To connect from Home Assistant:")
+            logger.info("  Settings -> Devices & Services -> Add Integration")
+            logger.info("  -> ESPHome -> Enter this device's IP:6053")
+            logger.info("=" * 50)
+
+            # Wait for stop signal
+            while not stop_event.is_set():
+                loop.run_until_complete(asyncio.sleep(0.5))
+
+        except Exception as e:
+            logger.error(f"Error running voice assistant: {e}")
+            raise
+        finally:
+            logger.info("Shutting down voice assistant...")
+            loop.run_until_complete(service.stop())
+            loop.close()
+            logger.info("Voice assistant stopped.")
+
+
+# Entry point for the app
+App = HomeAssistantVoiceApp

src/reachy_mini_ha_voice/__main__.py

@@ -0,0 +1,515 @@
+#!/usr/bin/env python3
+"""Main entry point for Reachy Mini Home Assistant Voice Assistant."""
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+import threading
+import time
+from pathlib import Path
+from queue import Queue
+from typing import Dict, List, Optional, Set, Union
+
+import numpy as np
+import sounddevice as sd
+
+from pymicro_wakeword import MicroWakeWord, MicroWakeWordFeatures
+from pyopen_wakeword import OpenWakeWord, OpenWakeWordFeatures
+
+from .models import AvailableWakeWord, Preferences, ServerState, WakeWordType
+from .audio_player import AudioPlayer
+from .satellite import VoiceSatelliteProtocol
+from .util import get_mac
+from .zeroconf import HomeAssistantZeroconf
+
+_LOGGER = logging.getLogger(__name__)
+
+_MODULE_DIR = Path(__file__).parent
+_REPO_DIR = _MODULE_DIR.parent.parent
+_WAKEWORDS_DIR = _REPO_DIR / "wakewords"
+_SOUNDS_DIR = _REPO_DIR / "sounds"
+
+
+def download_required_files():
+    """Download required model and sound files if missing."""
+    import urllib.request
+
+    _WAKEWORDS_DIR.mkdir(parents=True, exist_ok=True)
+    _SOUNDS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Wake word models
+    wakeword_files = {
+        "okay_nabu.tflite": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/okay_nabu.tflite",
+        "okay_nabu.json": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/okay_nabu.json",
+        "hey_jarvis.tflite": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/hey_jarvis.tflite",
+        "hey_jarvis.json": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/hey_jarvis.json",
+        "stop.tflite": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/stop.tflite",
+        "stop.json": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/stop.json",
+    }
+
+    # Sound files
+    sound_files = {
+        "wake_word_triggered.flac": "https://github.com/OHF-Voice/linux-voice-assistant/raw/main/sounds/wake_word_triggered.flac",
+        "timer_finished.flac": "https://github.com/OHF-Voice/linux-voice-assistant/raw/main/sounds/timer_finished.flac",
+    }
+
+    for filename, url in wakeword_files.items():
+        dest = _WAKEWORDS_DIR / filename
+        if not dest.exists():
+            _LOGGER.info("Downloading %s...", filename)
+            try:
+                urllib.request.urlretrieve(url, dest)
+                _LOGGER.info("Downloaded %s", filename)
+            except Exception as e:
+                _LOGGER.warning("Failed to download %s: %s", filename, e)
+
+    for filename, url in sound_files.items():
+        dest = _SOUNDS_DIR / filename
+        if not dest.exists():
+            _LOGGER.info("Downloading %s...", filename)
+            try:
+                urllib.request.urlretrieve(url, dest)
+                _LOGGER.info("Downloaded %s", filename)
+            except Exception as e:
+                _LOGGER.warning("Failed to download %s: %s", filename, e)
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Reachy Mini Home Assistant Voice Assistant"
+    )
+    parser.add_argument(
+        "--name",
+        default="Reachy Mini",
+        help="Name of the voice assistant (default: Reachy Mini)",
+    )
+    parser.add_argument(
+        "--audio-input-device",
+        help="Audio input device name or index (see --list-input-devices)",
+    )
+    parser.add_argument(
+        "--list-input-devices",
+        action="store_true",
+        help="List audio input devices and exit",
+    )
+    parser.add_argument(
+        "--audio-input-block-size",
+        type=int,
+        default=1024,
+        help="Audio input block size (default: 1024)",
+    )
+    parser.add_argument(
+        "--audio-output-device",
+        help="Audio output device name or index (see --list-output-devices)",
+    )
+    parser.add_argument(
+        "--list-output-devices",
+        action="store_true",
+        help="List audio output devices and exit",
+    )
+    parser.add_argument(
+        "--wake-word-dir",
+        default=[str(_WAKEWORDS_DIR)],
+        action="append",
+        help="Directory with wake word models (.tflite) and configs (.json)",
+    )
+    parser.add_argument(
+        "--wake-model",
+        default="okay_nabu",
+        help="Id of active wake model (default: okay_nabu)",
+    )
+    parser.add_argument(
+        "--stop-model",
+        default="stop",
+        help="Id of stop model (default: stop)",
+    )
+    parser.add_argument(
+        "--download-dir",
+        default=str(_REPO_DIR / "local"),
+        help="Directory to download custom wake word models, etc.",
+    )
+    parser.add_argument(
+        "--refractory-seconds",
+        default=2.0,
+        type=float,
+        help="Seconds before wake word can be activated again (default: 2.0)",
+    )
+    parser.add_argument(
+        "--wakeup-sound",
+        default=str(_SOUNDS_DIR / "wake_word_triggered.flac"),
+        help="Sound to play when wake word is detected",
+    )
+    parser.add_argument(
+        "--timer-finished-sound",
+        default=str(_SOUNDS_DIR / "timer_finished.flac"),
+        help="Sound to play when timer finishes",
+    )
+    parser.add_argument(
+        "--preferences-file",
+        default=str(_REPO_DIR / "preferences.json"),
+        help="Path to preferences file",
+    )
+    parser.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="Address for ESPHome server (default: 0.0.0.0)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=6053,
+        help="Port for ESPHome server (default: 6053)",
+    )
+    parser.add_argument(
+        "--no-motion",
+        action="store_true",
+        help="Disable Reachy Mini motion control",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Print DEBUG messages to console",
+    )
+
+    args = parser.parse_args()
+
+    # Setup logging
+    logging.basicConfig(
+        level=logging.DEBUG if args.debug else logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    # List input devices
+    if args.list_input_devices:
+        print("\nAudio Input Devices")
+        print("=" * 40)
+        devices = sd.query_devices()
+        for idx, device in enumerate(devices):
+            if device["max_input_channels"] > 0:
+                print(f"[{idx}] {device['name']}")
+        return
+
+    # List output devices
+    if args.list_output_devices:
+        print("\nAudio Output Devices")
+        print("=" * 40)
+        devices = sd.query_devices()
+        for idx, device in enumerate(devices):
+            if device["max_output_channels"] > 0:
+                print(f"[{idx}] {device['name']}")
+        return
+
+    _LOGGER.debug(args)
+
+    # Download required files
+    download_required_files()
+
+    # Setup paths
+    download_dir = Path(args.download_dir)
+    download_dir.mkdir(parents=True, exist_ok=True)
+
+    # Resolve audio input device
+    input_device = args.audio_input_device
+    if input_device is not None:
+        try:
+            input_device = int(input_device)
+        except ValueError:
+            pass
+
+    # Load available wake words
+    wake_word_dirs = [Path(ww_dir) for ww_dir in args.wake_word_dir]
+    wake_word_dirs.append(download_dir / "external_wake_words")
+
+    available_wake_words: Dict[str, AvailableWakeWord] = {}
+    for wake_word_dir in wake_word_dirs:
+        if not wake_word_dir.exists():
+            continue
+        for model_config_path in wake_word_dir.glob("*.json"):
+            model_id = model_config_path.stem
+            if model_id == args.stop_model:
+                # Don't show stop model as an available wake word
+                continue
+
+            try:
+                with open(model_config_path, "r", encoding="utf-8") as model_config_file:
+                    model_config = json.load(model_config_file)
+
+                model_type = WakeWordType(model_config.get("type", "micro"))
+
+                if model_type == WakeWordType.OPEN_WAKE_WORD:
+                    wake_word_path = model_config_path.parent / model_config["model"]
+                else:
+                    wake_word_path = model_config_path
+
+                available_wake_words[model_id] = AvailableWakeWord(
+                    id=model_id,
+                    type=WakeWordType(model_type),
+                    wake_word=model_config.get("wake_word", model_id),
+                    trained_languages=model_config.get("trained_languages", []),
+                    wake_word_path=wake_word_path,
+                )
+            except Exception as e:
+                _LOGGER.warning("Failed to load wake word config %s: %s", model_config_path, e)
+
+    _LOGGER.debug("Available wake words: %s", list(sorted(available_wake_words.keys())))
+
+    # Load preferences
+    preferences_path = Path(args.preferences_file)
+    if preferences_path.exists():
+        _LOGGER.debug("Loading preferences: %s", preferences_path)
+        with open(preferences_path, "r", encoding="utf-8") as preferences_file:
+            preferences_dict = json.load(preferences_file)
+        preferences = Preferences(**preferences_dict)
+    else:
+        preferences = Preferences()
+
+    # Load wake/stop models
+    active_wake_words: Set[str] = set()
+    wake_models: Dict[str, Union[MicroWakeWord, OpenWakeWord]] = {}
+
+    if preferences.active_wake_words:
+        # Load preferred models
+        for wake_word_id in preferences.active_wake_words:
+            wake_word = available_wake_words.get(wake_word_id)
+            if wake_word is None:
+                _LOGGER.warning("Unrecognized wake word id: %s", wake_word_id)
+                continue
+
+            _LOGGER.debug("Loading wake model: %s", wake_word_id)
+            wake_models[wake_word_id] = wake_word.load()
+            active_wake_words.add(wake_word_id)
+
+    if not wake_models:
+        # Load default model
+        wake_word_id = args.wake_model
+        wake_word = available_wake_words.get(wake_word_id)
+        if wake_word:
+            _LOGGER.debug("Loading wake model: %s", wake_word_id)
+            wake_models[wake_word_id] = wake_word.load()
+            active_wake_words.add(wake_word_id)
+        else:
+            _LOGGER.error("Wake word model not found: %s", wake_word_id)
+            _LOGGER.error("Available models: %s", list(available_wake_words.keys()))
+            sys.exit(1)
+
+    # Load stop model
+    stop_model: Optional[MicroWakeWord] = None
+    for wake_word_dir in wake_word_dirs:
+        stop_config_path = wake_word_dir / f"{args.stop_model}.json"
+        if not stop_config_path.exists():
+            continue
+
+        _LOGGER.debug("Loading stop model: %s", stop_config_path)
+        stop_model = MicroWakeWord.from_config(stop_config_path)
+        break
+
+    if stop_model is None:
+        _LOGGER.warning("Stop model not found, timer stop functionality disabled")
+        # Create a dummy stop model that never triggers
+        stop_model = MicroWakeWord.from_config(
+            list(available_wake_words.values())[0].wake_word_path
+        )
+
+    # Initialize Reachy Mini (if available)
+    reachy_mini = None
+    if not args.no_motion:
+        try:
+            from reachy_mini import ReachyMini
+            reachy_mini = ReachyMini()
+            _LOGGER.info("Reachy Mini connected")
+        except ImportError:
+            _LOGGER.warning("reachy-mini not installed, motion control disabled")
+        except Exception as e:
+            _LOGGER.warning("Failed to connect to Reachy Mini: %s", e)
+
+    # Create server state
+    state = ServerState(
+        name=args.name,
+        mac_address=get_mac(),
+        audio_queue=Queue(),
+        entities=[],
+        available_wake_words=available_wake_words,
+        wake_words=wake_models,
+        active_wake_words=active_wake_words,
+        stop_word=stop_model,
+        music_player=AudioPlayer(device=args.audio_output_device),
+        tts_player=AudioPlayer(device=args.audio_output_device),
+        wakeup_sound=args.wakeup_sound,
+        timer_finished_sound=args.timer_finished_sound,
+        preferences=preferences,
+        preferences_path=preferences_path,
+        refractory_seconds=args.refractory_seconds,
+        download_dir=download_dir,
+        reachy_mini=reachy_mini,
+        motion_enabled=not args.no_motion and reachy_mini is not None,
+    )
+
+    # Start audio processing thread
+    process_audio_thread = threading.Thread(
+        target=process_audio,
+        args=(state, input_device, args.audio_input_block_size),
+        daemon=True,
+    )
+    process_audio_thread.start()
+
+    # Create ESPHome server
+    loop = asyncio.get_running_loop()
+    server = await loop.create_server(
+        lambda: VoiceSatelliteProtocol(state), host=args.host, port=args.port
+    )
+
+    # Auto discovery (zeroconf, mDNS)
+    discovery = HomeAssistantZeroconf(port=args.port, name=args.name)
+    await discovery.register_server()
+
+    try:
+        async with server:
+            _LOGGER.info("=" * 50)
+            _LOGGER.info("Reachy Mini Voice Assistant Started")
+            _LOGGER.info("=" * 50)
+            _LOGGER.info("Name: %s", args.name)
+            _LOGGER.info("ESPHome Server: %s:%s", args.host, args.port)
+            _LOGGER.info("Wake word: %s", list(active_wake_words))
+            _LOGGER.info("Motion control: %s", "enabled" if state.motion_enabled else "disabled")
+            _LOGGER.info("=" * 50)
+            _LOGGER.info("Add this device in Home Assistant:")
+            _LOGGER.info("  Settings -> Devices & Services -> Add Integration -> ESPHome")
+            _LOGGER.info("  Enter: <this-device-ip>:6053")
+            _LOGGER.info("=" * 50)
+
+            await server.serve_forever()
+    except KeyboardInterrupt:
+        _LOGGER.info("Shutting down...")
+    finally:
+        state.audio_queue.put_nowait(None)
+        process_audio_thread.join(timeout=2.0)
+        await discovery.unregister_server()
+        _LOGGER.debug("Server stopped")
+
+
+def process_audio(state: ServerState, input_device, block_size: int):
+    """Process audio chunks from the microphone."""
+    wake_words: List[Union[MicroWakeWord, OpenWakeWord]] = []
+    micro_features: Optional[MicroWakeWordFeatures] = None
+    micro_inputs: List[np.ndarray] = []
+    oww_features: Optional[OpenWakeWordFeatures] = None
+    oww_inputs: List[np.ndarray] = []
+    has_oww = False
+    last_active: Optional[float] = None
+
+    try:
+        _LOGGER.debug("Opening audio input device: %s", input_device or "default")
+
+        with sd.InputStream(
+            device=input_device,
+            samplerate=16000,
+            channels=1,
+            blocksize=block_size,
+            dtype="float32",
+        ) as stream:
+            while True:
+                audio_chunk_array, overflowed = stream.read(block_size)
+                if overflowed:
+                    _LOGGER.warning("Audio buffer overflow")
+
+                audio_chunk_array = audio_chunk_array.reshape(-1)
+
+                # Convert to 16-bit PCM for streaming
+                audio_chunk = (
+                    (np.clip(audio_chunk_array, -1.0, 1.0) * 32767.0)
+                    .astype("<i2")
+                    .tobytes()
+                )
+
+                # Stream audio to Home Assistant
+                if state.satellite:
+                    state.satellite.handle_audio(audio_chunk)
+
+                # Check if wake words changed
+                if state.wake_words_changed:
+                    state.wake_words_changed = False
+                    wake_words = list(state.wake_words.values())
+                    has_oww = any(isinstance(ww, OpenWakeWord) for ww in wake_words)
+
+                    if any(isinstance(ww, MicroWakeWord) for ww in wake_words):
+                        micro_features = MicroWakeWordFeatures()
+                    else:
+                        micro_features = None
+
+                    if has_oww:
+                        oww_features = OpenWakeWordFeatures.from_builtin()
+                    else:
+                        oww_features = None
+
+                # Initialize features if needed
+                if not wake_words:
+                    wake_words = list(state.wake_words.values())
+                    has_oww = any(isinstance(ww, OpenWakeWord) for ww in wake_words)
+
+                    if any(isinstance(ww, MicroWakeWord) for ww in wake_words):
+                        micro_features = MicroWakeWordFeatures()
+
+                    if has_oww:
+                        oww_features = OpenWakeWordFeatures.from_builtin()
+
+                # Extract features
+                micro_inputs.clear()
+                oww_inputs.clear()
+
+                if micro_features:
+                    micro_inputs = micro_features.process_streaming(audio_chunk_array)
+
+                if oww_features:
+                    oww_inputs = oww_features.process_streaming(audio_chunk_array)
+
+                # Process wake words
+                for wake_word in wake_words:
+                    if wake_word.id not in state.active_wake_words:
+                        continue
+
+                    activated = False
+
+                    if isinstance(wake_word, MicroWakeWord):
+                        for micro_input in micro_inputs:
+                            if wake_word.process_streaming(micro_input):
+                                activated = True
+                    elif isinstance(wake_word, OpenWakeWord):
+                        for oww_input in oww_inputs:
+                            scores = wake_word.process_streaming(oww_input)
+                            if any(s > 0.5 for s in scores):
+                                activated = True
+
+                    if activated:
+                        # Check refractory period
+                        now = time.monotonic()
+                        if (last_active is None) or (
+                            (now - last_active) > state.refractory_seconds
+                        ):
+                            if state.satellite:
+                                state.satellite.wakeup(wake_word)
+                            last_active = now
+
+                # Always process stop word to keep state correct
+                stopped = False
+                for micro_input in micro_inputs:
+                    if state.stop_word.process_streaming(micro_input):
+                        stopped = True
+
+                if stopped and (state.stop_word.id in state.active_wake_words):
+                    if state.satellite:
+                        state.satellite.stop()
+
+    except Exception:
+        _LOGGER.exception("Unexpected error processing audio")
+        sys.exit(1)
+
+
+def run():
+    """Entry point for the application."""
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

src/reachy_mini_ha_voice/api_server.py

@@ -0,0 +1,178 @@
+"""Partial ESPHome server implementation."""
+
+import asyncio
+import logging
+from abc import abstractmethod
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, List, Optional
+
+# pylint: disable=no-name-in-module
+from aioesphomeapi._frame_helper.packets import make_plain_text_packets
+from aioesphomeapi.api_pb2 import (  # type: ignore[attr-defined]
+    AuthenticationRequest,
+    AuthenticationResponse,
+    DisconnectRequest,
+    DisconnectResponse,
+    HelloRequest,
+    HelloResponse,
+    PingRequest,
+    PingResponse,
+)
+from aioesphomeapi.core import MESSAGE_TYPE_TO_PROTO
+from google.protobuf import message
+
+PROTO_TO_MESSAGE_TYPE = {v: k for k, v in MESSAGE_TYPE_TO_PROTO.items()}
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class APIServer(asyncio.Protocol):
+    """ESPHome API Server implementation."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self._buffer: Optional[bytes] = None
+        self._buffer_len: int = 0
+        self._pos: int = 0
+        self._transport = None
+        self._writelines = None
+
+    @abstractmethod
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        pass
+
+    def process_packet(self, msg_type: int, packet_data: bytes) -> None:
+        msg_class = MESSAGE_TYPE_TO_PROTO[msg_type]
+        msg_inst = msg_class.FromString(packet_data)
+
+        if isinstance(msg_inst, HelloRequest):
+            self.send_messages(
+                [
+                    HelloResponse(
+                        api_version_major=1,
+                        api_version_minor=10,
+                        name=self.name,
+                    )
+                ]
+            )
+            return
+
+        if isinstance(msg_inst, AuthenticationRequest):
+            self.send_messages([AuthenticationResponse()])
+        elif isinstance(msg_inst, DisconnectRequest):
+            self.send_messages([DisconnectResponse()])
+            _LOGGER.debug("Disconnect requested")
+            if self._transport:
+                self._transport.close()
+                self._transport = None
+                self._writelines = None
+        elif isinstance(msg_inst, PingRequest):
+            self.send_messages([PingResponse()])
+        elif msgs := self.handle_message(msg_inst):
+            if isinstance(msgs, message.Message):
+                msgs = [msgs]
+            self.send_messages(msgs)
+
+    def send_messages(self, msgs: List[message.Message]):
+        if self._writelines is None:
+            return
+
+        packets = [
+            (PROTO_TO_MESSAGE_TYPE[msg.__class__], msg.SerializeToString())
+            for msg in msgs
+        ]
+        packet_bytes = make_plain_text_packets(packets)
+        self._writelines(packet_bytes)
+
+    def connection_made(self, transport) -> None:
+        self._transport = transport
+        self._writelines = transport.writelines
+
+    def data_received(self, data: bytes):
+        if self._buffer is None:
+            self._buffer = data
+            self._buffer_len = len(data)
+        else:
+            self._buffer += data
+            self._buffer_len += len(data)
+
+        while self._buffer_len >= 3:
+            self._pos = 0
+
+            # Read preamble, which should always 0x00
+            if (preamble := self._read_varuint()) != 0x00:
+                _LOGGER.error("Incorrect preamble: %s", preamble)
+                return
+
+            if (length := self._read_varuint()) == -1:
+                _LOGGER.error("Incorrect length: %s", length)
+                return
+
+            if (msg_type := self._read_varuint()) == -1:
+                _LOGGER.error("Incorrect message type: %s", msg_type)
+                return
+
+            if length == 0:
+                # Empty message (allowed)
+                self._remove_from_buffer()
+                self.process_packet(msg_type, b"")
+                continue
+
+            if (packet_data := self._read(length)) is None:
+                return
+
+            self._remove_from_buffer()
+            self.process_packet(msg_type, packet_data)
+
+    def _read(self, length: int) -> bytes | None:
+        """Read exactly length bytes from the buffer or None if all the bytes are not yet available."""
+        new_pos = self._pos + length
+        if self._buffer_len < new_pos:
+            return None
+
+        original_pos = self._pos
+        self._pos = new_pos
+
+        if TYPE_CHECKING:
+            assert self._buffer is not None, "Buffer should be set"
+
+        cstr = self._buffer
+        return cstr[original_pos:new_pos]
+
+    def connection_lost(self, exc):
+        self._transport = None
+        self._writelines = None
+
+    def _read_varuint(self) -> int:
+        """Read a varuint from the buffer or -1 if the buffer runs out of bytes."""
+        if not self._buffer:
+            return -1
+
+        result = 0
+        bitpos = 0
+        cstr = self._buffer
+
+        while self._buffer_len > self._pos:
+            val = cstr[self._pos]
+            self._pos += 1
+            result |= (val & 0x7F) << bitpos
+            if (val & 0x80) == 0:
+                return result
+            bitpos += 7
+
+        return -1
+
+    def _remove_from_buffer(self) -> None:
+        """Remove data from the buffer."""
+        end_of_frame_pos = self._pos
+        self._buffer_len -= end_of_frame_pos
+
+        if self._buffer_len == 0:
+            self._buffer = None
+            return
+
+        if TYPE_CHECKING:
+            assert self._buffer is not None, "Buffer should be set"
+
+        cstr = self._buffer
+        self._buffer = cstr[end_of_frame_pos : self._buffer_len + end_of_frame_pos]

src/reachy_mini_ha_voice/audio_player.py

@@ -0,0 +1,136 @@
+"""Audio player using sounddevice for Reachy Mini."""
+
+import logging
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import List, Optional, Union
+
+import numpy as np
+import sounddevice as sd
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class AudioPlayer:
+    """Audio player using sounddevice."""
+
+    def __init__(self, device: Optional[str] = None) -> None:
+        self.device = device
+        self.is_playing = False
+        self._playlist: List[str] = []
+        self._done_callback: Optional[Callable[[], None]] = None
+        self._done_callback_lock = threading.Lock()
+        self._duck_volume: float = 0.5
+        self._unduck_volume: float = 1.0
+        self._current_volume: float = 1.0
+        self._stop_flag = threading.Event()
+
+    def play(
+        self,
+        url: Union[str, List[str]],
+        done_callback: Optional[Callable[[], None]] = None,
+        stop_first: bool = True,
+    ) -> None:
+        if stop_first:
+            self.stop()
+
+        if isinstance(url, str):
+            self._playlist = [url]
+        else:
+            self._playlist = list(url)
+
+        self._done_callback = done_callback
+        self._stop_flag.clear()
+        self._play_next()
+
+    def _play_next(self) -> None:
+        if not self._playlist or self._stop_flag.is_set():
+            self._on_playback_finished()
+            return
+
+        next_url = self._playlist.pop(0)
+        _LOGGER.debug("Playing %s", next_url)
+        self.is_playing = True
+
+        # Start playback in a thread
+        thread = threading.Thread(target=self._play_file, args=(next_url,), daemon=True)
+        thread.start()
+
+    def _play_file(self, file_path: str) -> None:
+        """Play an audio file."""
+        try:
+            # Try to load the audio file
+            if file_path.startswith(("http://", "https://")):
+                # For URLs, download first
+                import urllib.request
+                import tempfile
+                import os
+
+                with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as tmp:
+                    urllib.request.urlretrieve(file_path, tmp.name)
+                    file_path = tmp.name
+
+            # Load audio file
+            import soundfile as sf
+            data, samplerate = sf.read(file_path)
+
+            # Apply volume
+            data = data * self._current_volume
+
+            # Play
+            if not self._stop_flag.is_set():
+                sd.play(data, samplerate, device=self.device)
+                sd.wait()
+
+        except Exception as e:
+            _LOGGER.error("Error playing audio: %s", e)
+        finally:
+            self.is_playing = False
+            # Play next in playlist or finish
+            if self._playlist and not self._stop_flag.is_set():
+                self._play_next()
+            else:
+                self._on_playback_finished()
+
+    def _on_playback_finished(self) -> None:
+        """Called when playback is finished."""
+        self.is_playing = False
+        todo_callback: Optional[Callable[[], None]] = None
+
+        with self._done_callback_lock:
+            if self._done_callback:
+                todo_callback = self._done_callback
+                self._done_callback = None
+
+        if todo_callback:
+            try:
+                todo_callback()
+            except Exception:
+                _LOGGER.exception("Unexpected error running done callback")
+
+    def pause(self) -> None:
+        sd.stop()
+        self.is_playing = False
+
+    def resume(self) -> None:
+        if self._playlist:
+            self._play_next()
+
+    def stop(self) -> None:
+        self._stop_flag.set()
+        sd.stop()
+        self._playlist.clear()
+        self.is_playing = False
+
+    def duck(self) -> None:
+        self._current_volume = self._duck_volume
+
+    def unduck(self) -> None:
+        self._current_volume = self._unduck_volume
+
+    def set_volume(self, volume: int) -> None:
+        volume = max(0, min(100, volume))
+        self._unduck_volume = volume / 100.0
+        self._duck_volume = self._unduck_volume / 2
+        self._current_volume = self._unduck_volume

src/reachy_mini_ha_voice/entity.py

@@ -0,0 +1,135 @@
+"""ESPHome entity definitions."""
+
+from abc import abstractmethod
+from collections.abc import Iterable
+from typing import Callable, List, Optional, Union
+
+# pylint: disable=no-name-in-module
+from aioesphomeapi.api_pb2 import (  # type: ignore[attr-defined]
+    ListEntitiesMediaPlayerResponse,
+    ListEntitiesRequest,
+    MediaPlayerCommandRequest,
+    MediaPlayerStateResponse,
+    SubscribeHomeAssistantStatesRequest,
+)
+from aioesphomeapi.model import MediaPlayerCommand, MediaPlayerState
+from google.protobuf import message
+
+from .api_server import APIServer
+from .audio_player import AudioPlayer
+from .util import call_all
+
+
+class ESPHomeEntity:
+    """Base class for ESPHome entities."""
+
+    def __init__(self, server: APIServer) -> None:
+        self.server = server
+
+    @abstractmethod
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        pass
+
+
+class MediaPlayerEntity(ESPHomeEntity):
+    """Media player entity for ESPHome."""
+
+    def __init__(
+        self,
+        server: APIServer,
+        key: int,
+        name: str,
+        object_id: str,
+        music_player: AudioPlayer,
+        announce_player: AudioPlayer,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.state = MediaPlayerState.IDLE
+        self.volume = 1.0
+        self.muted = False
+        self.music_player = music_player
+        self.announce_player = announce_player
+
+    def play(
+        self,
+        url: Union[str, List[str]],
+        announcement: bool = False,
+        done_callback: Optional[Callable[[], None]] = None,
+    ) -> Iterable[message.Message]:
+        if announcement:
+            if self.music_player.is_playing:
+                # Announce, resume music
+                self.music_player.pause()
+                self.announce_player.play(
+                    url,
+                    done_callback=lambda: call_all(
+                        self.music_player.resume, done_callback
+                    ),
+                )
+            else:
+                # Announce, idle
+                self.announce_player.play(
+                    url,
+                    done_callback=lambda: call_all(
+                        lambda: self.server.send_messages(
+                            [self._update_state(MediaPlayerState.IDLE)]
+                        ),
+                        done_callback,
+                    ),
+                )
+        else:
+            # Music
+            self.music_player.play(
+                url,
+                done_callback=lambda: call_all(
+                    lambda: self.server.send_messages(
+                        [self._update_state(MediaPlayerState.IDLE)]
+                    ),
+                    done_callback,
+                ),
+            )
+
+        yield self._update_state(MediaPlayerState.PLAYING)
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, MediaPlayerCommandRequest) and (msg.key == self.key):
+            if msg.has_media_url:
+                announcement = msg.has_announcement and msg.announcement
+                yield from self.play(msg.media_url, announcement=announcement)
+            elif msg.has_command:
+                if msg.command == MediaPlayerCommand.PAUSE:
+                    self.music_player.pause()
+                    yield self._update_state(MediaPlayerState.PAUSED)
+                elif msg.command == MediaPlayerCommand.PLAY:
+                    self.music_player.resume()
+                    yield self._update_state(MediaPlayerState.PLAYING)
+            elif msg.has_volume:
+                volume = int(msg.volume * 100)
+                self.music_player.set_volume(volume)
+                self.announce_player.set_volume(volume)
+                self.volume = msg.volume
+                yield self._update_state(self.state)
+        elif isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesMediaPlayerResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                supports_pause=True,
+            )
+        elif isinstance(msg, SubscribeHomeAssistantStatesRequest):
+            yield self._get_state_message()
+
+    def _update_state(self, new_state: MediaPlayerState) -> MediaPlayerStateResponse:
+        self.state = new_state
+        return self._get_state_message()
+
+    def _get_state_message(self) -> MediaPlayerStateResponse:
+        return MediaPlayerStateResponse(
+            key=self.key,
+            state=self.state,
+            volume=self.volume,
+            muted=self.muted,
+        )

src/reachy_mini_ha_voice/models.py

@@ -0,0 +1,88 @@
+"""Shared models for Reachy Mini Voice Assistant."""
+
+import json
+import logging
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from pathlib import Path
+from queue import Queue
+from typing import TYPE_CHECKING, Dict, List, Optional, Set, Union
+
+if TYPE_CHECKING:
+    from pymicro_wakeword import MicroWakeWord
+    from pyopen_wakeword import OpenWakeWord
+    from .entity import ESPHomeEntity, MediaPlayerEntity
+    from .audio_player import AudioPlayer
+    from .satellite import VoiceSatelliteProtocol
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class WakeWordType(str, Enum):
+    MICRO_WAKE_WORD = "micro"
+    OPEN_WAKE_WORD = "openWakeWord"
+
+
+@dataclass
+class AvailableWakeWord:
+    id: str
+    type: WakeWordType
+    wake_word: str
+    trained_languages: List[str]
+    wake_word_path: Path
+
+    def load(self) -> "Union[MicroWakeWord, OpenWakeWord]":
+        if self.type == WakeWordType.MICRO_WAKE_WORD:
+            from pymicro_wakeword import MicroWakeWord
+            return MicroWakeWord.from_config(config_path=self.wake_word_path)
+
+        if self.type == WakeWordType.OPEN_WAKE_WORD:
+            from pyopen_wakeword import OpenWakeWord
+            oww_model = OpenWakeWord.from_model(model_path=self.wake_word_path)
+            setattr(oww_model, "wake_word", self.wake_word)
+            return oww_model
+
+        raise ValueError(f"Unexpected wake word type: {self.type}")
+
+
+@dataclass
+class Preferences:
+    active_wake_words: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ServerState:
+    """Global server state."""
+    name: str
+    mac_address: str
+    audio_queue: "Queue[Optional[bytes]]"
+    entities: "List[ESPHomeEntity]"
+    available_wake_words: "Dict[str, AvailableWakeWord]"
+    wake_words: "Dict[str, Union[MicroWakeWord, OpenWakeWord]]"
+    active_wake_words: Set[str]
+    stop_word: "MicroWakeWord"
+    music_player: "AudioPlayer"
+    tts_player: "AudioPlayer"
+    wakeup_sound: str
+    timer_finished_sound: str
+    preferences: Preferences
+    preferences_path: Path
+    download_dir: Path
+
+    # Reachy Mini specific
+    reachy_mini: Optional[object] = None
+    motion_enabled: bool = True
+
+    media_player_entity: "Optional[MediaPlayerEntity]" = None
+    satellite: "Optional[VoiceSatelliteProtocol]" = None
+    wake_words_changed: bool = False
+    refractory_seconds: float = 2.0
+
+    def save_preferences(self) -> None:
+        """Save preferences as JSON."""
+        _LOGGER.debug("Saving preferences: %s", self.preferences_path)
+        self.preferences_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.preferences_path, "w", encoding="utf-8") as preferences_file:
+            json.dump(
+                asdict(self.preferences), preferences_file, ensure_ascii=False, indent=4
+            )

src/reachy_mini_ha_voice/motion.py

@@ -0,0 +1,234 @@
+"""Reachy Mini motion control integration."""
+
+import asyncio
+import logging
+import threading
+from typing import Optional
+import numpy as np
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ReachyMiniMotion:
+    """Reachy Mini motion controller for voice assistant."""
+
+    def __init__(self, reachy_mini=None):
+        self.reachy_mini = reachy_mini
+        self._is_speaking = False
+        self._speech_task: Optional[asyncio.Task] = None
+        self._lock = threading.Lock()
+
+    def set_reachy_mini(self, reachy_mini):
+        """Set the Reachy Mini instance."""
+        self.reachy_mini = reachy_mini
+
+    def on_wakeup(self):
+        """Called when wake word is detected - nod to acknowledge."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            # Quick nod to acknowledge
+            self._nod(count=1, amplitude=10, duration=0.3)
+            _LOGGER.debug("Reachy Mini: Wake up nod")
+        except Exception as e:
+            _LOGGER.error("Motion error on wakeup: %s", e)
+
+    def on_listening(self):
+        """Called when listening for speech - tilt head slightly."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            # Tilt head slightly to show attention
+            self._look_at_user()
+            _LOGGER.debug("Reachy Mini: Listening pose")
+        except Exception as e:
+            _LOGGER.error("Motion error on listening: %s", e)
+
+    def on_thinking(self):
+        """Called when processing speech - look up slightly."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            # Look up slightly as if thinking
+            self._think_pose()
+            _LOGGER.debug("Reachy Mini: Thinking pose")
+        except Exception as e:
+            _LOGGER.error("Motion error on thinking: %s", e)
+
+    def on_speaking_start(self):
+        """Called when TTS starts - start speech-reactive motion."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            self._is_speaking = True
+            # Start subtle head movements during speech
+            self._start_speech_motion()
+            _LOGGER.debug("Reachy Mini: Speaking started")
+        except Exception as e:
+            _LOGGER.error("Motion error on speaking start: %s", e)
+
+    def on_speaking_end(self):
+        """Called when TTS ends - stop speech-reactive motion."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            self._is_speaking = False
+            self._stop_speech_motion()
+            _LOGGER.debug("Reachy Mini: Speaking ended")
+        except Exception as e:
+            _LOGGER.error("Motion error on speaking end: %s", e)
+
+    def on_idle(self):
+        """Called when returning to idle state."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            self._is_speaking = False
+            self._stop_speech_motion()
+            self._return_to_neutral()
+            _LOGGER.debug("Reachy Mini: Idle pose")
+        except Exception as e:
+            _LOGGER.error("Motion error on idle: %s", e)
+
+    def on_timer_finished(self):
+        """Called when a timer finishes - alert animation."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            # Shake head to get attention
+            self._shake(count=2, amplitude=15, duration=0.4)
+            _LOGGER.debug("Reachy Mini: Timer finished animation")
+        except Exception as e:
+            _LOGGER.error("Motion error on timer finished: %s", e)
+
+    def on_error(self):
+        """Called on error - shake head."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            self._shake(count=1, amplitude=10, duration=0.3)
+            _LOGGER.debug("Reachy Mini: Error animation")
+        except Exception as e:
+            _LOGGER.error("Motion error on error: %s", e)
+
+    # -------------------------------------------------------------------------
+    # Low-level motion methods
+    # -------------------------------------------------------------------------
+
+    def _nod(self, count: int = 1, amplitude: float = 15, duration: float = 0.5):
+        """Nod head up and down."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            from scipy.spatial.transform import Rotation as R
+
+            for _ in range(count):
+                # Nod down
+                pose_down = np.eye(4)
+                pose_down[:3, :3] = R.from_euler('xyz', [amplitude, 0, 0], degrees=True).as_matrix()
+                self.reachy_mini.head.goto(pose_down, duration=duration / 2)
+
+                # Nod up
+                pose_up = np.eye(4)
+                pose_up[:3, :3] = R.from_euler('xyz', [-amplitude / 2, 0, 0], degrees=True).as_matrix()
+                self.reachy_mini.head.goto(pose_up, duration=duration / 2)
+
+            # Return to neutral
+            self._return_to_neutral()
+        except Exception as e:
+            _LOGGER.error("Nod error: %s", e)
+
+    def _shake(self, count: int = 1, amplitude: float = 20, duration: float = 0.5):
+        """Shake head left and right."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            from scipy.spatial.transform import Rotation as R
+
+            for _ in range(count):
+                # Shake left
+                pose_left = np.eye(4)
+                pose_left[:3, :3] = R.from_euler('xyz', [0, 0, -amplitude], degrees=True).as_matrix()
+                self.reachy_mini.head.goto(pose_left, duration=duration / 2)
+
+                # Shake right
+                pose_right = np.eye(4)
+                pose_right[:3, :3] = R.from_euler('xyz', [0, 0, amplitude], degrees=True).as_matrix()
+                self.reachy_mini.head.goto(pose_right, duration=duration / 2)
+
+            # Return to neutral
+            self._return_to_neutral()
+        except Exception as e:
+            _LOGGER.error("Shake error: %s", e)
+
+    def _look_at_user(self):
+        """Look at user (neutral forward position)."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            pose = np.eye(4)
+            self.reachy_mini.head.goto(pose, duration=0.3)
+        except Exception as e:
+            _LOGGER.error("Look at user error: %s", e)
+
+    def _think_pose(self):
+        """Thinking pose - look up slightly."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            from scipy.spatial.transform import Rotation as R
+
+            pose = np.eye(4)
+            pose[:3, :3] = R.from_euler('xyz', [-10, 0, 5], degrees=True).as_matrix()
+            self.reachy_mini.head.goto(pose, duration=0.4)
+        except Exception as e:
+            _LOGGER.error("Think pose error: %s", e)
+
+    def _return_to_neutral(self):
+        """Return to neutral position."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            pose = np.eye(4)
+            self.reachy_mini.head.goto(pose, duration=0.5)
+        except Exception as e:
+            _LOGGER.error("Return to neutral error: %s", e)
+
+    def _start_speech_motion(self):
+        """Start subtle speech-reactive motion."""
+        # This would ideally run in a separate thread with subtle movements
+        pass
+
+    def _stop_speech_motion(self):
+        """Stop speech-reactive motion."""
+        pass
+
+    def wiggle_antennas(self, happy: bool = True):
+        """Wiggle antennas to show emotion."""
+        if not self.reachy_mini:
+            return
+
+        try:
+            if happy:
+                # Happy wiggle - both up
+                self.reachy_mini.head.l_antenna.goto(30, duration=0.2)
+                self.reachy_mini.head.r_antenna.goto(-30, duration=0.2)
+            else:
+                # Sad - both down
+                self.reachy_mini.head.l_antenna.goto(-20, duration=0.2)
+                self.reachy_mini.head.r_antenna.goto(20, duration=0.2)
+        except Exception as e:
+            _LOGGER.error("Antenna wiggle error: %s", e)

src/reachy_mini_ha_voice/satellite.py

@@ -0,0 +1,476 @@
+"""Voice satellite protocol for Reachy Mini."""
+
+import hashlib
+import logging
+import posixpath
+import shutil
+import time
+from collections.abc import Iterable
+from typing import Dict, Optional, Set, Union
+from urllib.parse import urlparse, urlunparse
+from urllib.request import urlopen
+
+# pylint: disable=no-name-in-module
+from aioesphomeapi.api_pb2 import (  # type: ignore[attr-defined]
+    DeviceInfoRequest,
+    DeviceInfoResponse,
+    ListEntitiesDoneResponse,
+    ListEntitiesRequest,
+    MediaPlayerCommandRequest,
+    SubscribeHomeAssistantStatesRequest,
+    VoiceAssistantAnnounceFinished,
+    VoiceAssistantAnnounceRequest,
+    VoiceAssistantAudio,
+    VoiceAssistantConfigurationRequest,
+    VoiceAssistantConfigurationResponse,
+    VoiceAssistantEventResponse,
+    VoiceAssistantExternalWakeWord,
+    VoiceAssistantRequest,
+    VoiceAssistantSetConfiguration,
+    VoiceAssistantTimerEventResponse,
+    VoiceAssistantWakeWord,
+)
+from aioesphomeapi.model import (
+    VoiceAssistantEventType,
+    VoiceAssistantFeature,
+    VoiceAssistantTimerEventType,
+)
+from google.protobuf import message
+from pymicro_wakeword import MicroWakeWord
+from pyopen_wakeword import OpenWakeWord
+
+from .api_server import APIServer
+from .entity import MediaPlayerEntity
+from .models import AvailableWakeWord, ServerState, WakeWordType
+from .util import call_all
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VoiceSatelliteProtocol(APIServer):
+    """Voice satellite protocol handler for ESPHome."""
+
+    def __init__(self, state: ServerState) -> None:
+        super().__init__(state.name)
+        self.state = state
+        self.state.satellite = self
+
+        if self.state.media_player_entity is None:
+            self.state.media_player_entity = MediaPlayerEntity(
+                server=self,
+                key=len(state.entities),
+                name="Media Player",
+                object_id="reachy_mini_media_player",
+                music_player=state.music_player,
+                announce_player=state.tts_player,
+            )
+            self.state.entities.append(self.state.media_player_entity)
+
+        self._is_streaming_audio = False
+        self._tts_url: Optional[str] = None
+        self._tts_played = False
+        self._continue_conversation = False
+        self._timer_finished = False
+        self._external_wake_words: Dict[str, VoiceAssistantExternalWakeWord] = {}
+
+    def handle_voice_event(
+        self, event_type: VoiceAssistantEventType, data: Dict[str, str]
+    ) -> None:
+        _LOGGER.debug("Voice event: type=%s, data=%s", event_type.name, data)
+
+        if event_type == VoiceAssistantEventType.VOICE_ASSISTANT_RUN_START:
+            self._tts_url = data.get("url")
+            self._tts_played = False
+            self._continue_conversation = False
+            # Reachy Mini: Start listening animation
+            self._reachy_on_listening()
+
+        elif event_type in (
+            VoiceAssistantEventType.VOICE_ASSISTANT_STT_VAD_END,
+            VoiceAssistantEventType.VOICE_ASSISTANT_STT_END,
+        ):
+            self._is_streaming_audio = False
+            # Reachy Mini: Stop listening, start thinking
+            self._reachy_on_thinking()
+
+        elif event_type == VoiceAssistantEventType.VOICE_ASSISTANT_INTENT_PROGRESS:
+            if data.get("tts_start_streaming") == "1":
+                # Start streaming early
+                self.play_tts()
+
+        elif event_type == VoiceAssistantEventType.VOICE_ASSISTANT_INTENT_END:
+            if data.get("continue_conversation") == "1":
+                self._continue_conversation = True
+
+        elif event_type == VoiceAssistantEventType.VOICE_ASSISTANT_TTS_START:
+            # Reachy Mini: Start speaking animation
+            self._reachy_on_speaking()
+
+        elif event_type == VoiceAssistantEventType.VOICE_ASSISTANT_TTS_END:
+            self._tts_url = data.get("url")
+            self.play_tts()
+
+        elif event_type == VoiceAssistantEventType.VOICE_ASSISTANT_RUN_END:
+            self._is_streaming_audio = False
+            if not self._tts_played:
+                self._tts_finished()
+            self._tts_played = False
+            # Reachy Mini: Return to idle
+            self._reachy_on_idle()
+
+    def handle_timer_event(
+        self,
+        event_type: VoiceAssistantTimerEventType,
+        msg: VoiceAssistantTimerEventResponse,
+    ) -> None:
+        _LOGGER.debug("Timer event: type=%s", event_type.name)
+
+        if event_type == VoiceAssistantTimerEventType.VOICE_ASSISTANT_TIMER_FINISHED:
+            if not self._timer_finished:
+                self.state.active_wake_words.add(self.state.stop_word.id)
+                self._timer_finished = True
+                self.duck()
+                self._play_timer_finished()
+                # Reachy Mini: Timer finished animation
+                self._reachy_on_timer_finished()
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, VoiceAssistantEventResponse):
+            # Pipeline event
+            data: Dict[str, str] = {}
+            for arg in msg.data:
+                data[arg.name] = arg.value
+            self.handle_voice_event(VoiceAssistantEventType(msg.event_type), data)
+
+        elif isinstance(msg, VoiceAssistantAnnounceRequest):
+            _LOGGER.debug("Announcing: %s", msg.text)
+            assert self.state.media_player_entity is not None
+
+            urls = []
+            if msg.preannounce_media_id:
+                urls.append(msg.preannounce_media_id)
+            urls.append(msg.media_id)
+
+            self.state.active_wake_words.add(self.state.stop_word.id)
+            self._continue_conversation = msg.start_conversation
+            self.duck()
+
+            yield from self.state.media_player_entity.play(
+                urls, announcement=True, done_callback=self._tts_finished
+            )
+
+        elif isinstance(msg, VoiceAssistantTimerEventResponse):
+            self.handle_timer_event(VoiceAssistantTimerEventType(msg.event_type), msg)
+
+        elif isinstance(msg, DeviceInfoRequest):
+            yield DeviceInfoResponse(
+                uses_password=False,
+                name=self.state.name,
+                mac_address=self.state.mac_address,
+                voice_assistant_feature_flags=(
+                    VoiceAssistantFeature.VOICE_ASSISTANT
+                    | VoiceAssistantFeature.API_AUDIO
+                    | VoiceAssistantFeature.ANNOUNCE
+                    | VoiceAssistantFeature.START_CONVERSATION
+                    | VoiceAssistantFeature.TIMERS
+                ),
+            )
+
+        elif isinstance(
+            msg,
+            (
+                ListEntitiesRequest,
+                SubscribeHomeAssistantStatesRequest,
+                MediaPlayerCommandRequest,
+            ),
+        ):
+            for entity in self.state.entities:
+                yield from entity.handle_message(msg)
+
+            if isinstance(msg, ListEntitiesRequest):
+                yield ListEntitiesDoneResponse()
+
+        elif isinstance(msg, VoiceAssistantConfigurationRequest):
+            available_wake_words = [
+                VoiceAssistantWakeWord(
+                    id=ww.id,
+                    wake_word=ww.wake_word,
+                    trained_languages=ww.trained_languages,
+                )
+                for ww in self.state.available_wake_words.values()
+            ]
+
+            for eww in msg.external_wake_words:
+                if eww.model_type != "micro":
+                    continue
+
+                available_wake_words.append(
+                    VoiceAssistantWakeWord(
+                        id=eww.id,
+                        wake_word=eww.wake_word,
+                        trained_languages=eww.trained_languages,
+                    )
+                )
+                self._external_wake_words[eww.id] = eww
+
+            yield VoiceAssistantConfigurationResponse(
+                available_wake_words=available_wake_words,
+                active_wake_words=[
+                    ww.id
+                    for ww in self.state.wake_words.values()
+                    if ww.id in self.state.active_wake_words
+                ],
+                max_active_wake_words=2,
+            )
+
+            _LOGGER.info("Connected to Home Assistant")
+
+        elif isinstance(msg, VoiceAssistantSetConfiguration):
+            # Change active wake words
+            active_wake_words: Set[str] = set()
+
+            for wake_word_id in msg.active_wake_words:
+                if wake_word_id in self.state.wake_words:
+                    # Already active
+                    active_wake_words.add(wake_word_id)
+                    continue
+
+                model_info = self.state.available_wake_words.get(wake_word_id)
+                if not model_info:
+                    # Check external wake words (may require download)
+                    external_wake_word = self._external_wake_words.get(wake_word_id)
+                    if not external_wake_word:
+                        continue
+
+                    model_info = self._download_external_wake_word(external_wake_word)
+                    if not model_info:
+                        continue
+
+                    self.state.available_wake_words[wake_word_id] = model_info
+
+                _LOGGER.debug("Loading wake word: %s", model_info.wake_word_path)
+                self.state.wake_words[wake_word_id] = model_info.load()
+                _LOGGER.info("Wake word set: %s", wake_word_id)
+                active_wake_words.add(wake_word_id)
+                break
+
+            self.state.active_wake_words = active_wake_words
+            _LOGGER.debug("Active wake words: %s", active_wake_words)
+
+            self.state.preferences.active_wake_words = list(active_wake_words)
+            self.state.save_preferences()
+            self.state.wake_words_changed = True
+
+    def handle_audio(self, audio_chunk: bytes) -> None:
+        if not self._is_streaming_audio:
+            return
+        self.send_messages([VoiceAssistantAudio(data=audio_chunk)])
+
+    def wakeup(self, wake_word: Union[MicroWakeWord, OpenWakeWord]) -> None:
+        if self._timer_finished:
+            # Stop timer instead
+            self._timer_finished = False
+            self.state.tts_player.stop()
+            _LOGGER.debug("Stopping timer finished sound")
+            return
+
+        wake_word_phrase = wake_word.wake_word
+        _LOGGER.debug("Detected wake word: %s", wake_word_phrase)
+
+        self.send_messages(
+            [VoiceAssistantRequest(start=True, wake_word_phrase=wake_word_phrase)]
+        )
+        self.duck()
+        self._is_streaming_audio = True
+        self.state.tts_player.play(self.state.wakeup_sound)
+
+        # Reachy Mini: Wake up animation
+        self._reachy_on_wakeup()
+
+    def stop(self) -> None:
+        self.state.active_wake_words.discard(self.state.stop_word.id)
+        self.state.tts_player.stop()
+
+        if self._timer_finished:
+            self._timer_finished = False
+            _LOGGER.debug("Stopping timer finished sound")
+        else:
+            _LOGGER.debug("TTS response stopped manually")
+
+        self._tts_finished()
+
+    def play_tts(self) -> None:
+        if (not self._tts_url) or self._tts_played:
+            return
+
+        self._tts_played = True
+        _LOGGER.debug("Playing TTS response: %s", self._tts_url)
+
+        self.state.active_wake_words.add(self.state.stop_word.id)
+        self.state.tts_player.play(self._tts_url, done_callback=self._tts_finished)
+
+    def duck(self) -> None:
+        _LOGGER.debug("Ducking music")
+        self.state.music_player.duck()
+
+    def unduck(self) -> None:
+        _LOGGER.debug("Unducking music")
+        self.state.music_player.unduck()
+
+    def _tts_finished(self) -> None:
+        self.state.active_wake_words.discard(self.state.stop_word.id)
+        self.send_messages([VoiceAssistantAnnounceFinished()])
+
+        if self._continue_conversation:
+            self.send_messages([VoiceAssistantRequest(start=True)])
+            self._is_streaming_audio = True
+            _LOGGER.debug("Continuing conversation")
+        else:
+            self.unduck()
+            _LOGGER.debug("TTS response finished")
+            # Reachy Mini: Return to idle
+            self._reachy_on_idle()
+
+    def _play_timer_finished(self) -> None:
+        if not self._timer_finished:
+            self.unduck()
+            return
+
+        self.state.tts_player.play(
+            self.state.timer_finished_sound,
+            done_callback=lambda: call_all(
+                lambda: time.sleep(1.0), self._play_timer_finished
+            ),
+        )
+
+    def connection_lost(self, exc):
+        super().connection_lost(exc)
+        _LOGGER.info("Disconnected from Home Assistant")
+
+    def _download_external_wake_word(
+        self, external_wake_word: VoiceAssistantExternalWakeWord
+    ) -> Optional[AvailableWakeWord]:
+        eww_dir = self.state.download_dir / "external_wake_words"
+        eww_dir.mkdir(parents=True, exist_ok=True)
+
+        config_path = eww_dir / f"{external_wake_word.id}.json"
+        should_download_config = not config_path.exists()
+
+        # Check if we need to download the model file
+        model_path = eww_dir / f"{external_wake_word.id}.tflite"
+        should_download_model = True
+
+        if model_path.exists():
+            model_size = model_path.stat().st_size
+            if model_size == external_wake_word.model_size:
+                with open(model_path, "rb") as model_file:
+                    model_hash = hashlib.sha256(model_file.read()).hexdigest()
+
+                if model_hash == external_wake_word.model_hash:
+                    should_download_model = False
+                    _LOGGER.debug(
+                        "Model size and hash match for %s. Skipping download.",
+                        external_wake_word.id,
+                    )
+
+        if should_download_config or should_download_model:
+            # Download config
+            _LOGGER.debug("Downloading %s to %s", external_wake_word.url, config_path)
+            with urlopen(external_wake_word.url) as request:
+                if request.status != 200:
+                    _LOGGER.warning(
+                        "Failed to download: %s, status=%s",
+                        external_wake_word.url,
+                        request.status,
+                    )
+                    return None
+
+                with open(config_path, "wb") as model_file:
+                    shutil.copyfileobj(request, model_file)
+
+        if should_download_model:
+            # Download model file
+            parsed_url = urlparse(external_wake_word.url)
+            parsed_url = parsed_url._replace(
+                path=posixpath.join(posixpath.dirname(parsed_url.path), model_path.name)
+            )
+            model_url = urlunparse(parsed_url)
+
+            _LOGGER.debug("Downloading %s to %s", model_url, model_path)
+            with urlopen(model_url) as request:
+                if request.status != 200:
+                    _LOGGER.warning(
+                        "Failed to download: %s, status=%s", model_url, request.status
+                    )
+                    return None
+
+                with open(model_path, "wb") as model_file:
+                    shutil.copyfileobj(request, model_file)
+
+        return AvailableWakeWord(
+            id=external_wake_word.id,
+            type=WakeWordType.MICRO_WAKE_WORD,
+            wake_word=external_wake_word.wake_word,
+            trained_languages=external_wake_word.trained_languages,
+            wake_word_path=config_path,
+        )
+
+    # -------------------------------------------------------------------------
+    # Reachy Mini Motion Control
+    # -------------------------------------------------------------------------
+
+    def _reachy_on_wakeup(self) -> None:
+        """Called when wake word is detected."""
+        if not self.state.motion_enabled or not self.state.reachy_mini:
+            return
+        try:
+            # Nod to acknowledge
+            _LOGGER.debug("Reachy Mini: Wake up animation")
+            # Will be implemented with actual Reachy Mini SDK
+        except Exception as e:
+            _LOGGER.error("Reachy Mini motion error: %s", e)
+
+    def _reachy_on_listening(self) -> None:
+        """Called when listening for speech."""
+        if not self.state.motion_enabled or not self.state.reachy_mini:
+            return
+        try:
+            _LOGGER.debug("Reachy Mini: Listening animation")
+        except Exception as e:
+            _LOGGER.error("Reachy Mini motion error: %s", e)
+
+    def _reachy_on_thinking(self) -> None:
+        """Called when processing speech."""
+        if not self.state.motion_enabled or not self.state.reachy_mini:
+            return
+        try:
+            _LOGGER.debug("Reachy Mini: Thinking animation")
+        except Exception as e:
+            _LOGGER.error("Reachy Mini motion error: %s", e)
+
+    def _reachy_on_speaking(self) -> None:
+        """Called when TTS is playing."""
+        if not self.state.motion_enabled or not self.state.reachy_mini:
+            return
+        try:
+            _LOGGER.debug("Reachy Mini: Speaking animation")
+        except Exception as e:
+            _LOGGER.error("Reachy Mini motion error: %s", e)
+
+    def _reachy_on_idle(self) -> None:
+        """Called when returning to idle state."""
+        if not self.state.motion_enabled or not self.state.reachy_mini:
+            return
+        try:
+            _LOGGER.debug("Reachy Mini: Idle animation")
+        except Exception as e:
+            _LOGGER.error("Reachy Mini motion error: %s", e)
+
+    def _reachy_on_timer_finished(self) -> None:
+        """Called when a timer finishes."""
+        if not self.state.motion_enabled or not self.state.reachy_mini:
+            return
+        try:
+            _LOGGER.debug("Reachy Mini: Timer finished animation")
+        except Exception as e:
+            _LOGGER.error("Reachy Mini motion error: %s", e)

src/reachy_mini_ha_voice/util.py

@@ -0,0 +1,21 @@
+"""Utility functions."""
+
+import uuid
+from collections.abc import Callable
+from typing import Optional
+
+
+def call_all(*funcs: Optional[Callable[[], None]]) -> None:
+    """Call all non-None functions."""
+    for func in funcs:
+        if func is not None:
+            func()
+
+
+def get_mac() -> str:
+    """Return MAC address formatted as hex with no colons."""
+    return "".join(
+        ["{:02x}".format((uuid.getnode() >> ele) & 0xFF) for ele in range(0, 8 * 6, 8)][
+            ::-1
+        ]
+    )

src/reachy_mini_ha_voice/voice_assistant.py

@@ -0,0 +1,421 @@
+"""
+Voice Assistant Service for Reachy Mini.
+
+This module provides the main voice assistant service that integrates
+with Home Assistant via ESPHome protocol.
+"""
+
+import asyncio
+import json
+import logging
+import threading
+import time
+from pathlib import Path
+from queue import Queue
+from typing import Dict, List, Optional, Set, Union
+
+import numpy as np
+import sounddevice as sd
+
+from reachy_mini import ReachyMini
+
+from .models import AvailableWakeWord, Preferences, ServerState, WakeWordType
+from .audio_player import AudioPlayer
+from .satellite import VoiceSatelliteProtocol
+from .util import get_mac
+from .zeroconf import HomeAssistantZeroconf
+from .motion import ReachyMiniMotion
+
+_LOGGER = logging.getLogger(__name__)
+
+_MODULE_DIR = Path(__file__).parent
+_REPO_DIR = _MODULE_DIR.parent.parent
+_WAKEWORDS_DIR = _REPO_DIR / "wakewords"
+_SOUNDS_DIR = _REPO_DIR / "sounds"
+_LOCAL_DIR = _REPO_DIR / "local"
+
+
+class VoiceAssistantService:
+    """Voice assistant service that runs ESPHome protocol server."""
+
+    def __init__(
+        self,
+        reachy_mini: Optional[ReachyMini] = None,
+        name: str = "Reachy Mini",
+        host: str = "0.0.0.0",
+        port: int = 6053,
+        wake_model: str = "okay_nabu",
+    ):
+        self.reachy_mini = reachy_mini
+        self.name = name
+        self.host = host
+        self.port = port
+        self.wake_model = wake_model
+
+        self._server = None
+        self._discovery = None
+        self._audio_thread = None
+        self._running = False
+        self._state: Optional[ServerState] = None
+        self._motion = ReachyMiniMotion(reachy_mini)
+
+    async def start(self) -> None:
+        """Start the voice assistant service."""
+        _LOGGER.info("Initializing voice assistant service...")
+
+        # Ensure directories exist
+        _WAKEWORDS_DIR.mkdir(parents=True, exist_ok=True)
+        _SOUNDS_DIR.mkdir(parents=True, exist_ok=True)
+        _LOCAL_DIR.mkdir(parents=True, exist_ok=True)
+
+        # Download required files
+        await self._download_required_files()
+
+        # Load wake words
+        available_wake_words = self._load_available_wake_words()
+        _LOGGER.debug("Available wake words: %s", list(available_wake_words.keys()))
+
+        # Load preferences
+        preferences_path = _LOCAL_DIR / "preferences.json"
+        preferences = self._load_preferences(preferences_path)
+
+        # Load wake word models
+        wake_models, active_wake_words = self._load_wake_models(
+            available_wake_words, preferences
+        )
+
+        # Load stop model
+        stop_model = self._load_stop_model()
+
+        # Create server state
+        self._state = ServerState(
+            name=self.name,
+            mac_address=get_mac(),
+            audio_queue=Queue(),
+            entities=[],
+            available_wake_words=available_wake_words,
+            wake_words=wake_models,
+            active_wake_words=active_wake_words,
+            stop_word=stop_model,
+            music_player=AudioPlayer(),
+            tts_player=AudioPlayer(),
+            wakeup_sound=str(_SOUNDS_DIR / "wake_word_triggered.flac"),
+            timer_finished_sound=str(_SOUNDS_DIR / "timer_finished.flac"),
+            preferences=preferences,
+            preferences_path=preferences_path,
+            refractory_seconds=2.0,
+            download_dir=_LOCAL_DIR,
+            reachy_mini=self.reachy_mini,
+            motion_enabled=self.reachy_mini is not None,
+        )
+
+        # Set motion controller reference in state
+        self._state.motion = self._motion
+
+        # Start audio processing thread
+        self._running = True
+        self._audio_thread = threading.Thread(
+            target=self._process_audio,
+            daemon=True,
+        )
+        self._audio_thread.start()
+
+        # Create ESPHome server
+        loop = asyncio.get_running_loop()
+        self._server = await loop.create_server(
+            lambda: VoiceSatelliteProtocol(self._state),
+            host=self.host,
+            port=self.port,
+        )
+
+        # Start mDNS discovery
+        self._discovery = HomeAssistantZeroconf(port=self.port, name=self.name)
+        await self._discovery.register_server()
+
+        _LOGGER.info("Voice assistant service started on %s:%s", self.host, self.port)
+
+    async def stop(self) -> None:
+        """Stop the voice assistant service."""
+        _LOGGER.info("Stopping voice assistant service...")
+
+        self._running = False
+
+        if self._audio_thread:
+            self._audio_thread.join(timeout=2.0)
+
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+
+        if self._discovery:
+            await self._discovery.unregister_server()
+
+        _LOGGER.info("Voice assistant service stopped.")
+
+    async def _download_required_files(self) -> None:
+        """Download required model and sound files if missing."""
+        import urllib.request
+
+        # Wake word models
+        wakeword_files = {
+            "okay_nabu.tflite": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/okay_nabu.tflite",
+            "hey_jarvis.tflite": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/hey_jarvis.tflite",
+            "stop.tflite": "https://github.com/esphome/micro-wake-word-models/raw/main/models/v2/stop.tflite",
+        }
+
+        # Sound files
+        sound_files = {
+            "wake_word_triggered.flac": "https://github.com/OHF-Voice/linux-voice-assistant/raw/main/sounds/wake_word_triggered.flac",
+            "timer_finished.flac": "https://github.com/OHF-Voice/linux-voice-assistant/raw/main/sounds/timer_finished.flac",
+        }
+
+        for filename, url in wakeword_files.items():
+            dest = _WAKEWORDS_DIR / filename
+            if not dest.exists():
+                _LOGGER.info("Downloading %s...", filename)
+                try:
+                    urllib.request.urlretrieve(url, dest)
+                    _LOGGER.info("Downloaded %s", filename)
+                except Exception as e:
+                    _LOGGER.warning("Failed to download %s: %s", filename, e)
+
+        for filename, url in sound_files.items():
+            dest = _SOUNDS_DIR / filename
+            if not dest.exists():
+                _LOGGER.info("Downloading %s...", filename)
+                try:
+                    urllib.request.urlretrieve(url, dest)
+                    _LOGGER.info("Downloaded %s", filename)
+                except Exception as e:
+                    _LOGGER.warning("Failed to download %s: %s", filename, e)
+
+    def _load_available_wake_words(self) -> Dict[str, AvailableWakeWord]:
+        """Load available wake word configurations."""
+        available_wake_words: Dict[str, AvailableWakeWord] = {}
+
+        wake_word_dirs = [_WAKEWORDS_DIR, _LOCAL_DIR / "external_wake_words"]
+
+        for wake_word_dir in wake_word_dirs:
+            if not wake_word_dir.exists():
+                continue
+
+            for config_path in wake_word_dir.glob("*.json"):
+                model_id = config_path.stem
+                if model_id == "stop":
+                    continue
+
+                try:
+                    with open(config_path, "r", encoding="utf-8") as f:
+                        config = json.load(f)
+
+                    model_type = WakeWordType(config.get("type", "micro"))
+
+                    if model_type == WakeWordType.OPEN_WAKE_WORD:
+                        wake_word_path = config_path.parent / config["model"]
+                    else:
+                        wake_word_path = config_path
+
+                    available_wake_words[model_id] = AvailableWakeWord(
+                        id=model_id,
+                        type=model_type,
+                        wake_word=config.get("wake_word", model_id),
+                        trained_languages=config.get("trained_languages", []),
+                        wake_word_path=wake_word_path,
+                    )
+                except Exception as e:
+                    _LOGGER.warning("Failed to load wake word %s: %s", config_path, e)
+
+        return available_wake_words
+
+    def _load_preferences(self, preferences_path: Path) -> Preferences:
+        """Load user preferences."""
+        if preferences_path.exists():
+            try:
+                with open(preferences_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                return Preferences(**data)
+            except Exception as e:
+                _LOGGER.warning("Failed to load preferences: %s", e)
+
+        return Preferences()
+
+    def _load_wake_models(
+        self,
+        available_wake_words: Dict[str, AvailableWakeWord],
+        preferences: Preferences,
+    ):
+        """Load wake word models."""
+        from pymicro_wakeword import MicroWakeWord
+        from pyopen_wakeword import OpenWakeWord
+
+        wake_models: Dict[str, Union[MicroWakeWord, OpenWakeWord]] = {}
+        active_wake_words: Set[str] = set()
+
+        # Try to load preferred models
+        if preferences.active_wake_words:
+            for wake_word_id in preferences.active_wake_words:
+                wake_word = available_wake_words.get(wake_word_id)
+                if wake_word is None:
+                    _LOGGER.warning("Unknown wake word: %s", wake_word_id)
+                    continue
+
+                try:
+                    _LOGGER.debug("Loading wake model: %s", wake_word_id)
+                    wake_models[wake_word_id] = wake_word.load()
+                    active_wake_words.add(wake_word_id)
+                except Exception as e:
+                    _LOGGER.warning("Failed to load wake model %s: %s", wake_word_id, e)
+
+        # Load default model if none loaded
+        if not wake_models:
+            wake_word = available_wake_words.get(self.wake_model)
+            if wake_word:
+                try:
+                    _LOGGER.debug("Loading default wake model: %s", self.wake_model)
+                    wake_models[self.wake_model] = wake_word.load()
+                    active_wake_words.add(self.wake_model)
+                except Exception as e:
+                    _LOGGER.error("Failed to load default wake model: %s", e)
+
+        return wake_models, active_wake_words
+
+    def _load_stop_model(self):
+        """Load the stop word model."""
+        from pymicro_wakeword import MicroWakeWord
+
+        stop_config = _WAKEWORDS_DIR / "stop.json"
+        if stop_config.exists():
+            try:
+                return MicroWakeWord.from_config(stop_config)
+            except Exception as e:
+                _LOGGER.warning("Failed to load stop model: %s", e)
+
+        # Return a dummy model if stop model not available
+        _LOGGER.warning("Stop model not available, using fallback")
+        okay_nabu_config = _WAKEWORDS_DIR / "okay_nabu.json"
+        if okay_nabu_config.exists():
+            return MicroWakeWord.from_config(okay_nabu_config)
+
+        return None
+
+    def _process_audio(self) -> None:
+        """Process audio from microphone in a separate thread."""
+        from pymicro_wakeword import MicroWakeWord, MicroWakeWordFeatures
+        from pyopen_wakeword import OpenWakeWord, OpenWakeWordFeatures
+
+        wake_words: List[Union[MicroWakeWord, OpenWakeWord]] = []
+        micro_features: Optional[MicroWakeWordFeatures] = None
+        micro_inputs: List[np.ndarray] = []
+        oww_features: Optional[OpenWakeWordFeatures] = None
+        oww_inputs: List[np.ndarray] = []
+        has_oww = False
+        last_active: Optional[float] = None
+
+        block_size = 1024
+
+        try:
+            _LOGGER.info("Starting audio processing...")
+
+            with sd.InputStream(
+                samplerate=16000,
+                channels=1,
+                blocksize=block_size,
+                dtype="float32",
+            ) as stream:
+                while self._running:
+                    audio_chunk_array, overflowed = stream.read(block_size)
+                    if overflowed:
+                        _LOGGER.warning("Audio buffer overflow")
+
+                    audio_chunk_array = audio_chunk_array.reshape(-1)
+
+                    # Convert to 16-bit PCM for streaming
+                    audio_chunk = (
+                        (np.clip(audio_chunk_array, -1.0, 1.0) * 32767.0)
+                        .astype("<i2")
+                        .tobytes()
+                    )
+
+                    # Stream audio to Home Assistant
+                    if self._state and self._state.satellite:
+                        self._state.satellite.handle_audio(audio_chunk)
+
+                    # Check if wake words changed
+                    if self._state and self._state.wake_words_changed:
+                        self._state.wake_words_changed = False
+                        wake_words = list(self._state.wake_words.values())
+                        has_oww = any(isinstance(ww, OpenWakeWord) for ww in wake_words)
+
+                        if any(isinstance(ww, MicroWakeWord) for ww in wake_words):
+                            micro_features = MicroWakeWordFeatures()
+                        else:
+                            micro_features = None
+
+                        if has_oww:
+                            oww_features = OpenWakeWordFeatures.from_builtin()
+                        else:
+                            oww_features = None
+
+                    # Initialize features if needed
+                    if not wake_words and self._state:
+                        wake_words = list(self._state.wake_words.values())
+                        has_oww = any(isinstance(ww, OpenWakeWord) for ww in wake_words)
+
+                        if any(isinstance(ww, MicroWakeWord) for ww in wake_words):
+                            micro_features = MicroWakeWordFeatures()
+
+                        if has_oww:
+                            oww_features = OpenWakeWordFeatures.from_builtin()
+
+                    # Extract features
+                    micro_inputs.clear()
+                    oww_inputs.clear()
+
+                    if micro_features:
+                        micro_inputs = micro_features.process_streaming(audio_chunk_array)
+
+                    if oww_features:
+                        oww_inputs = oww_features.process_streaming(audio_chunk_array)
+
+                    # Process wake words
+                    if self._state:
+                        for wake_word in wake_words:
+                            if wake_word.id not in self._state.active_wake_words:
+                                continue
+
+                            activated = False
+
+                            if isinstance(wake_word, MicroWakeWord):
+                                for micro_input in micro_inputs:
+                                    if wake_word.process_streaming(micro_input):
+                                        activated = True
+                            elif isinstance(wake_word, OpenWakeWord):
+                                for oww_input in oww_inputs:
+                                    scores = wake_word.process_streaming(oww_input)
+                                    if any(s > 0.5 for s in scores):
+                                        activated = True
+
+                            if activated:
+                                now = time.monotonic()
+                                if (last_active is None) or (
+                                    (now - last_active) > self._state.refractory_seconds
+                                ):
+                                    if self._state.satellite:
+                                        self._state.satellite.wakeup(wake_word)
+                                        # Trigger motion
+                                        self._motion.on_wakeup()
+                                    last_active = now
+
+                        # Process stop word
+                        if self._state.stop_word:
+                            stopped = False
+                            for micro_input in micro_inputs:
+                                if self._state.stop_word.process_streaming(micro_input):
+                                    stopped = True
+
+                            if stopped and (self._state.stop_word.id in self._state.active_wake_words):
+                                if self._state.satellite:
+                                    self._state.satellite.stop()
+
+        except Exception:
+            _LOGGER.exception("Error processing audio")

src/reachy_mini_ha_voice/zeroconf.py

@@ -0,0 +1,73 @@
+"""Runs mDNS zeroconf service for Home Assistant discovery."""
+
+import logging
+import socket
+from typing import Optional
+
+_LOGGER = logging.getLogger(__name__)
+
+try:
+    from zeroconf.asyncio import AsyncServiceInfo, AsyncZeroconf
+except ImportError:
+    _LOGGER.fatal("pip install zeroconf")
+    raise
+
+MDNS_TARGET_IP = "224.0.0.251"
+
+
+class HomeAssistantZeroconf:
+    """Zeroconf service for Home Assistant discovery."""
+
+    def __init__(
+        self, port: int, name: Optional[str] = None, host: Optional[str] = None
+    ) -> None:
+        self.port = port
+        self.name = name or _get_mac_address()
+
+        if not host:
+            test_sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            test_sock.setblocking(False)
+            try:
+                test_sock.connect((MDNS_TARGET_IP, 1))
+                host = test_sock.getsockname()[0]
+            except Exception:
+                host = "127.0.0.1"
+            finally:
+                test_sock.close()
+            _LOGGER.debug("Detected IP: %s", host)
+
+        assert host
+        self.host = host
+        self._aiozc = AsyncZeroconf()
+
+    async def register_server(self) -> None:
+        service_info = AsyncServiceInfo(
+            "_esphomelib._tcp.local.",
+            f"{self.name}._esphomelib._tcp.local.",
+            addresses=[socket.inet_aton(self.host)],
+            port=self.port,
+            properties={
+                "version": "2025.9.0",
+                "mac": _get_mac_address(),
+                "board": "reachy_mini",
+                "platform": "REACHY_MINI",
+                "network": "ethernet",
+            },
+            server=f"{self.name}.local.",
+        )
+
+        await self._aiozc.async_register_service(service_info)
+        _LOGGER.debug("Zeroconf discovery enabled: %s", service_info)
+
+    async def unregister_server(self) -> None:
+        await self._aiozc.async_close()
+
+
+def _get_mac_address() -> str:
+    """Return MAC address formatted as hex with no colons."""
+    import uuid
+    return "".join(
+        ["{:02x}".format((uuid.getnode() >> ele) & 0xFF) for ele in range(0, 8 * 6, 8)][
+            ::-1
+        ]
+    )

wakewords/stop.json

@@ -0,0 +1,5 @@
+{
+  "type": "micro",
+  "wake_word": "Stop",
+  "trained_languages": ["en"]
+}