Fresh sync: 2026-05-05 13:12:05

.claude/settings.local.json

@@ -0,0 +1,55 @@
+{
+  "$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(copy:*)",
+      "mcp__zread__search_doc",
+      "mcp__zread__read_file",
+      "Bash(cd:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "mcp__acp__Bash",
+      "Skill(commit-commands:commit)",
+      "Skill(commit-commands:commit:*)"
+    ],
+    "deny": [],
+    "ask": []
+  },
+  "model": "opus",
+  "hooks": {},
+  "statusLine": {
+    "type": "command",
+    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
+    "padding": 0
+  },
+  "enabledPlugins": {
+    "glm-plan-usage@zai-coding-plugins": true,
+    "glm-plan-bug@zai-coding-plugins": true
+  },
+  "outputStyle": "Explanatory",
+  "alwaysThinkingEnabled": true
+}

.gitattributes

@@ -0,0 +1,5 @@
+# LFS tracking for large binary files
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  # Enable version updates for pip
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # Ignore PyTorch updates - locked version required for compatibility
+    ignore:
+      - dependency-name: "torch"
+        versions: [">2.5.1"]
+      - dependency-name: "torchvision"
+        versions: [">0.20.1"]

.github/workflows/sync_develop_to_hf_edge.yml

@@ -0,0 +1,86 @@
+name: Sync Develop to Hugging Face Edge
+
+on:
+  push:
+    branches: [develop]
+  workflow_dispatch:
+
+jobs:
+  sync-edge:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout GitHub repo
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Transform project name for edge channel
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+
+          # Keep runtime module path unchanged, only rewrite package/app naming metadata.
+          pyproject = Path('pyproject.toml')
+          text = pyproject.read_text(encoding='utf-8')
+          text = text.replace(
+              'name = "reachy_mini_home_assistant"',
+              'name = "reachy_mini_home_assistant_edge"',
+              1,
+          )
+          text = text.replace(
+              'reachy_mini_home_assistant = "reachy_mini_home_assistant.main:ReachyMiniHaVoice"',
+              'reachy_mini_home_assistant_edge = "reachy_mini_home_assistant.main:ReachyMiniHaVoice"',
+              1,
+          )
+          pyproject.write_text(text, encoding='utf-8')
+
+          init_file = Path('reachy_mini_home_assistant/__init__.py')
+          init_text = init_file.read_text(encoding='utf-8')
+          init_text = init_text.replace(
+              'version("reachy_mini_home_assistant")',
+              'version("reachy_mini_home_assistant_edge")',
+              1,
+          )
+          init_file.write_text(init_text, encoding='utf-8')
+
+          readme = Path('README.md')
+          if readme.exists():
+              readme_text = readme.read_text(encoding='utf-8')
+              readme_text = readme_text.replace(
+                  'title: Reachy Mini for Home Assistant',
+                  'title: Reachy Mini for Home Assistant (Edge)',
+                  1,
+              )
+              readme_text = readme_text.replace(
+                  'short_description: Deep integration of Reachy Mini robot with Home Assistant',
+                  'short_description: Edge channel for Reachy Mini Home Assistant integration',
+                  1,
+              )
+              readme_text = readme_text.replace(
+                  '  - reachy_mini_home_assistant',
+                  '  - reachy_mini_home_assistant_edge',
+                  1,
+              )
+              readme.write_text(readme_text, encoding='utf-8')
+          PY
+
+      - name: Create fresh commit and push to Hugging Face edge space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git config --global user.email "action@github.com"
+          git config --global user.name "GitHub Action"
+
+          # Create a new orphan branch with no history
+          git checkout --orphan hf-edge-sync
+          git add -A
+          git commit -m "Fresh edge sync: $(date +%Y-%m-%d_%H:%M:%S)"
+
+          # Add Hugging Face edge remote
+          git remote add hf-edge https://djhui5710:$HF_TOKEN@huggingface.co/spaces/djhui5710/reachy_mini_home_assistant_edge
+
+          # Push LFS objects first
+          git lfs push hf-edge hf-edge-sync --all
+
+          # Force push as main to HF edge space
+          git push hf-edge hf-edge-sync:main --force

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,36 @@
+name: Sync to Hugging Face
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout GitHub repo
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+
+      - name: Create fresh commit and push to Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git config --global user.email "action@github.com"
+          git config --global user.name "GitHub Action"
+          
+          # Create a new orphan branch with no history
+          git checkout --orphan hf-sync
+          git add -A
+          git commit -m "Fresh sync: $(date +%Y-%m-%d\ %H:%M:%S)"
+          
+          # Add Hugging Face remote
+          git remote add hf https://djhui5710:$HF_TOKEN@huggingface.co/spaces/djhui5710/reachy_mini_home_assistant
+          
+          # Push LFS objects first
+          git lfs push hf hf-sync --all
+          
+          # Force push as main to HF (overwrites all history)
+          git push hf hf-sync:main --force

.gitignore

@@ -0,0 +1,83 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.claude/*
+.serena/*
+.spec-workflow/
+.playwright-mcp/
+*~
+CLAUDE.md
+commit_msg.txt
+
+# Configuration
+config.json
+.env
+*.log
+
+# Cache
+.cache/
+*.cache
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Audio (exclude package bundled files)
+*.wav
+*.mp3
+# *.flac - bundled in package
+!reachy_mini_ha_voice/sounds/*.flac
+
+# Models (exclude package bundled files)
+# models/ - ignore external models directory
+models/
+# Package bundled models
+!reachy_mini_ha_voice/models/
+reachy_mini_ha_voice/models/*.tflite
+reachy_mini_ha_voice/models/*.onnx
+reachy_mini_ha_voice/models/*.pt
+
+# SDK Reference (local development only)
+reference/
+local/
+# ha/ - temporarily commented out for path fixes
+# ha/ will be moved to separate repository soon
+
+# Temporary check scripts
+temp_check_scripts/

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Pre-commit hooks for code quality
+# Install: pip install pre-commit && pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        additional_dependencies: []
+        args: [--ignore-missing-imports]
+        # Only check changed files for speed
+        pass_filenames: true

CHANGELOG.md

@@ -0,0 +1,713 @@
+# Changelog
+
+All notable changes to the Reachy Mini HA Voice project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+- **NameError** - Add missing deque import in gesture smoother
+- **Syntax Error** - Add missing class indentation for volume methods in audio_player.py
+- **Audio Card Name Detection** - Use SDK's detection logic instead of hardcoded values
+- **SDK Port 8000 Blocking** - Use amixer directly for volume control to avoid SDK HTTP API blocking
+- **Memory Leak Root Cause** - Audio buffer array creation in loop causing unbounded memory growth
+- **Indentation Error** - Fix indentation in audio_player.py stop_sendspin method
+
+## [1.0.7] - 2026-05-05
+
+### Changed
+- Align audio runtime with current SDK patterns by splitting local TTS playback from Sendspin-capable music playback and moving wakeword/stopword loading into shared helpers
+- Raise the Reachy Mini SDK baseline to `reachy-mini>=1.7.1`
+
+### Fixed
+- Keep wakeup/TTS playback on the local player path while binding both local and Sendspin players to shared speech sway helpers
+- Synchronize `Idle Behavior` shutdown with ESPHome face/gesture switches and runtime state updates
+- Remove obsolete runtime monitor modules that are no longer needed with the current SDK behavior
+
+### Optimized
+- Tighten Sendspin buffering with proactive backpressure and cleaner local queue handling
+
+## [1.0.6] - 2026-05-01
+
+### Changed
+- Align `pyproject.toml` with the current Reachy Mini SDK baseline by requiring `reachy-mini>=1.7.0`, `Python>=3.12`, `zeroconf>=0.131,<1`, `aiohttp`, `websockets>=12,<16`, and `gstreamer-bundle==1.28.1` on non-Linux platforms
+- Align Sendspin client dependency with the current upstream line via `aiosendspin>=5.1,<6.0`
+
+### Fixed
+- Fetch camera snapshot frames on demand when the MJPEG cache is empty so Home Assistant camera proxy requests keep working with the Reachy Mini SDK 1.7.0 media pull model
+
+### Optimized
+- Stop the camera server entirely when `Idle Behavior` is disabled instead of only unloading vision models, so idle-without-animation behaves more like a low-resource sleep state
+
+## [1.0.5] - 2026-04-12
+
+### Changed
+- Remove app-managed robot sleep/wake handling because current Reachy Mini SDK no longer supports mini apps remaining active while the robot enters sleep
+- Keep resource suspend/resume limited to ESPHome-driven runtime toggles such as Home Assistant disconnect, mute, camera disable, and service recovery
+- Align `pyproject.toml` runtime constraints with the current Reachy Mini reference SDK package (`reachy-mini>=1.6.3`, `websockets>=12,<16`, Python baseline `>=3.10`, and uv gstreamer metadata)
+
+### Removed
+- Remove `SleepManager` integration and app-side sleep/wake callback flow from the voice assistant runtime
+- Remove Home Assistant sleep control entities and internal robot sleep state tracking from the mini app
+
+## [1.0.4] - 2026-03-19
+
+### Fixed
+- Align Reachy Mini integration with current SDK assumptions by removing legacy compatibility paths and private client health checks
+- Replace direct SDK private `_respeaker` access with `audio_control_utils`-based ReSpeaker initialization
+- Tighten camera and pose composition to require current SDK media/utils APIs and valid `look_at_image` inputs
+
+### Improved
+- Unify idle behavior into a single persisted Home Assistant entity and remove old idle compatibility aliases
+- Replace separate wake/sleep buttons with a single sleep control entity
+- Update Sendspin integration for current `aiosendspin` lifecycle, stream handling, listener cleanup, and synchronized buffering
+- Standardize daemon URL usage on shared config across controller, sleep manager, and daemon monitor
+
+## [1.0.3] - 2026-03-07
+
+### Added
+- Idle Random Actions switch in Home Assistant with preferences persistence and startup restore
+- Configurable `idle_random_actions` presets in `conversation_animations.json` for centralized idle motion tuning
+
+### Fixed
+- Remove duplicate `idle_random_actions` fields/methods and complete runtime control wiring in controller/entity registry/movement manager
+
+### Optimized
+- Increase idle breathing and antenna sway cadence to 0.24Hz with wiggle antenna profile for more natural standby motion
+- Remove `set_target` global rate limiting and unchanged-pose skip gating to continuously stream motion commands each control tick
+- Remove idle antenna slew-rate limiter so antenna motion follows animation waveforms directly for reference-like smoothness
+
+## [1.0.2] - 2026-03-06
+
+### Fixed
+- Restore idle antenna sway animation and tune idle breathing parameters to reduce perceived stiffness
+- Reintroduce idle anti-chatter smoothing/deadband for antenna and body updates to reduce mechanical jitter/noise
+- Switch sleep/wake control to daemon API (`start` with `wake_up=true`, `stop` with `goto_sleep=true`) so `/api/daemon/status` reflects real sleep state on SDK 1.5
+- Normalize daemon status parsing for SDK 1.5 object-based status responses
+- Remove all app-side antenna power on/off operations to avoid SDK instability and external-control conflicts
+- Sync Idle Motion toggle with Idle Antenna Motion toggle for expected behavior in ESPHome
+- Remove legacy app-managed audio routing hooks and rely on native SDK/system audio selection
+- Harden startup against import-time failures (lazy emotion library loading and graceful Sendspin disable)
+
+### Changed
+- Keep idle antenna behavior as animation-only control (no torque coupling)
+- Tighten preference loading to current schema (no legacy config fallback filtering)
+
+### Added
+- Home Assistant blueprint for Reachy presence companion automation
+- GitHub workflow to auto-create releases when pyproject/changelog version updates produce a new tag
+
+### Improved
+- Blueprint supports device-first auto-binding and richer usage instructions
+- Refresh landing page (`index.html`) with current version, GitHub source link, and new Blueprint/Auto Release capability cards
+
+## [1.0.1] - 2026-03-05
+
+### Changed
+- Update runtime dependency baseline to `reachy-mini>=1.5.0`
+
+### Fixed
+- Remove legacy Zenoh 7447 startup precheck for SDK v1.5 compatibility
+- Remove legacy ZError string matching from connection error handling
+- Adapt daemon status handling to SDK v1.5 `DaemonStatus` object (prevents `AttributeError` on `status.get`)
+- Harden stop-word handling with runtime activation/deactivation and mute-aware trigger gating
+- Align wakeup stream start timing with reference behavior (start microphone stream after wakeup sound)
+- Improve TTS streaming robustness and reduce cutoffs with retry-based audio push
+
+### Optimized
+- Support single-request streaming with in-memory fallback cache for one-time TTS URLs (no temp file dependency)
+- Lower streaming fetch chunk size and apply unthrottled preroll for faster first audio
+
+## [1.0.0] - 2026-03-04
+
+### Changed
+- Require `reachy-mini[gstreamer]>=1.4.1`
+
+### Added
+- Sendspin switch in ESPHome (default OFF, persistent, runtime enable/disable)
+- Face Tracking and Gesture Detection switches in ESPHome (both default OFF, persistent)
+- Face Confidence number entity (0.0-1.0, persistent)
+
+### Fixed
+- Improve gesture responsiveness and stability (faster smoothing, min processing cadence, no-gesture alignment)
+- Auto-match ONNX gesture input size from model shape to prevent `INVALID_ARGUMENT` dimension errors
+- Disable antenna torque in idle mode and re-enable outside idle to reduce chatter/noise
+- Enforce deterministic audio startup path and fail fast when microphone capture is not ready
+- Add on-demand `/snapshot` JPEG generation when no cached stream frame is available
+
+### Optimized
+- Unload/reload face and gesture models when toggled off/on to save resources
+- Update idle behavior to breathing + look-around alternation, idle antenna sway disabled
+- Adjust idle breathing to human-like cadence
+- Make MJPEG streaming viewer-aware (skip continuous JPEG encode/push when no stream clients)
+- Keep face/gesture AI processing active even when stream viewers are absent
+
+### Changed
+- Use camera backend default FPS/resolution for stream path instead of forcing fixed 1080p/25fps
+
+## [0.9.9] - 2026-01-28
+
+### Fixed
+- **SDK Buffer Overflow During Idle**
+  - Add SDK buffer flush on GStreamer lock timeout
+  - Prevents buffer overflow during long idle periods when lock contention prevents buffer drainage
+  - Audio thread flushes SDK audio buffer when lock acquisition times out
+  - Camera thread flushes SDK video buffer when lock acquisition times out
+  - Audio playback flushes SDK playback buffer when lock acquisition times out
+  - Resolves SDK crashes during extended wake-up idle periods without conversation
+  - Requires Reachy Mini hardware (not applicable to simulation mode)
+
+### Fixed
+- **Memory Leaks**
+  - Audio buffer memory leak - added size limit to prevent unbounded growth
+  - Temp file leak - downloaded audio files now cleaned up after playback
+  - Multiple memory leak and resource leak issues fixed
+  - Thread-safe draining flag using threading.Event
+  - Silent failures now logged for debugging
+
+### Optimized
+- **Gesture Recognition Sensitivity**
+  - Simplify GestureSmoother to frequency-based confirmation (1 frame)
+  - Remove all confidence filtering - return all detections to Home Assistant
+  - Remove unused parameters (confidence_threshold, detection_threshold, GestureConfig)
+  - Remove duplicate empty check in gesture detection
+  - Add GestureSmoother class with history tracking for stable output
+  - Reduce gesture detection interval from 3 frames to 1 frame for higher frequency
+  - Fix: Gesture detection now returns all detected hands instead of only the highest confidence one
+  - Matches reference implementation behavior for improved detection rate
+  - No conflicts with face tracking (shared frame, independent processing)
+
+### Code Quality
+- Fix Ruff linter issues (import ordering, missing newlines, __all__ sorting)
+- Format code with Ruff formatter (5 files reformatted)
+- Fix slice index error in gesture detection (convert coordinates to integers)
+- Fix Python 3.12 type annotation compatibility
+
+## [0.9.8] - 2026-01-27
+
+### New
+- Mute switch entity - suspends voice services only (not camera/motion)
+- Disable Camera switch entity - suspends camera and AI processing
+- Home Assistant connection-driven feature loading
+- Automatic suspend/resume on HA disconnect/reconnect
+
+### Fixed
+- Camera disable logic - corrected inverted conditions for proper operation
+- Prevent daemon crash when entering idle state
+- Camera preview in Home Assistant
+- SDK crash during idle - optimized audio processing to skip get_frame() when not streaming to Home Assistant, reducing GStreamer resource competition
+- Add GStreamer threading lock to prevent pipeline competition between audio, playback, and camera threads
+- Audio thread gets priority during conversations - bypasses lock when conversation is active
+- Remove GStreamer lock to fix wake word detection in idle state (lock was preventing wake word detection)
+
+### Optimized
+- Reduce log output by 30-40%
+- Bundle face tracking model with package - eliminated HuggingFace download dependency, removed huggingface_hub from requirements, models now load from local package directory for offline operation
+- Replace HTTP API polling with SDK Zenoh for daemon status monitoring to reduce uvicorn blocking and improve stability
+- Device ID now reads /etc/machine-id directly - removed uuid.getnode() and file persistence
+- Implement high-priority SDK improvements
+- Remove aiohttp dependency from daemon_monitor - fully migrated to SDK Zenoh
+
+### Removed
+- Temporarily disable emotion playback during TTS
+- Unused config items (connection_timeout)
+
+### Code Quality
+- Code quality improvements
+
+## [0.9.7] - 2026-01-20
+
+### Fixed
+- Device ID file path corrected after util.py moved to core/ subdirectory (prevents HA seeing device as new)
+- Animation file path corrected (was looking in wrong directory)
+- Remove hey_jarvis from required wake words (it's optional in openWakeWord/)
+
+## [0.9.6] - 2026-01-20
+
+### New
+- Add ruff linter/formatter and mypy type checker configuration
+- Add pre-commit hooks for automated code quality checks
+
+### Fixed
+- Remove duplicate resume() method in audio_player.py
+- Remove duplicate connection_lost() method in satellite.py
+- Store asyncio task reference in sleep_manager.py to prevent garbage collection
+
+### Optimized
+- Use dict.items() for efficient iteration in smoothing.py
+
+## [0.9.5] - 2026-01-19
+
+### Refactored
+- Modularize codebase - new core/motion/vision/audio/entities module structure
+- Remove legacy/compatibility code
+- Remove audio diagnostics debug code
+
+### New
+- Direct callbacks for HA sleep/wake buttons to suspend/resume services
+
+### Optimized
+- Audio processing latency - reduced chunk size from 1024 to 256 samples (64ms -> 16ms)
+- Audio loop delay reduced from 10ms to 1ms for faster VAD response
+- Stereo to mono conversion uses first channel instead of mean for cleaner signal
+
+### Improved
+- Camera resume_from_suspend now synchronous for reliable wake from sleep
+- Rotation clamping in face tracking to prevent IK collisions
+- Audio gain boosted for faster VAD detection
+- Audio NaN/Inf values causing STT issues fixed
+
+## [0.9.0] - 2026-01-18
+
+### New
+- Robot state monitor for proper sleep mode handling - services pause when robot disconnects and resume on reconnect
+- System diagnostics entities (CPU, memory, disk, uptime) exposed as Home Assistant diagnostic sensors
+- Phase 24 with 9 diagnostic sensors (cpu_percent, cpu_temperature, memory_percent, memory_used_gb, disk_percent, disk_free_gb, uptime_hours, process_cpu_percent, process_memory_mb)
+
+### Fixed
+- Voice assistant and movement manager now properly pause during robot sleep mode instead of generating error spam
+
+### Improved
+- Graceful service lifecycle management with RobotStateMonitor callbacks
+
+## [0.8.7] - 2026-01-18
+
+### Fixed
+- Clamp body_yaw to safe range to prevent IK collision warnings during emotion playback
+- Emotion moves and face tracking now respect SDK safety limits
+
+### Improved
+- Face tracking smoothness - removed EMA smoothing (matches reference project)
+- Face tracking timing updated to match reference (2s delay, 1s interpolation)
+
+## [0.8.6] - 2026-01-18
+
+### Fixed
+- Audio buffer memory leak - added size limit to prevent unbounded growth
+- Temp file leak - downloaded audio files now cleaned up after playback
+- Camera thread termination timeout increased for clean shutdown
+- Thread-safe draining flag using threading.Event
+- Silent failures now logged for debugging
+
+## [0.8.5] - 2026-01-18
+
+### Fixed
+- DOA turn-to-sound direction inverted - now turns correctly toward sound source
+- Graceful shutdown prevents daemon crash on app stop
+
+## [0.8.4] - 2026-01-18
+
+### Improved
+- Smooth idle animation with interpolation phase (matches reference BreathingMove)
+- Two-phase animation - interpolates to neutral before oscillation
+- Antenna frequency updated to 0.5Hz (was 0.15Hz) for more natural sway
+
+## [0.8.3] - 2026-01-18
+
+### Fixed
+- Body now properly follows head rotation during face tracking
+- body_yaw extracted from final head pose matrix and synced with head_yaw
+- Matches reference project sweep_look behavior for natural body movement
+
+## [0.8.2] - 2026-01-18
+
+### Fixed
+- Body follows head rotation during face tracking - body_yaw syncs with head_yaw
+- Matches reference project sweep_look behavior for natural body movement
+
+## [0.8.1] - 2026-01-18
+
+### Fixed
+- face_detected entity now pushes state updates to Home Assistant in real-time
+- Body yaw simplified to match reference project - SDK automatic_body_yaw handles collision prevention
+- Idle animation now starts immediately on app launch
+- Smooth antenna animation - removed pose change threshold for continuous motion
+
+## [0.8.0] - 2026-01-17
+
+### New
+- Comprehensive emotion keyword mapping with 280+ Chinese and English keywords
+- 35 emotion categories mapped to robot expressions
+- Auto-trigger expressions from conversation text patterns
+
+## [0.7.3] - 2026-01-12
+
+### Fixed
+- Revert to reference project pattern - use refractory period instead of state flags
+- Remove broken _in_pipeline and _tts_playing state management
+- Restore correct RUN_END event handling from linux-voice-assistant
+
+## [0.7.2] - 2026-01-12
+
+### Fixed
+- Remove premature _tts_played reset in RUN_END event
+- Ensure _in_pipeline stays True until TTS playback completes
+
+## [0.7.1] - 2026-01-12
+
+### Fixed
+- Prevent wake word detection during TTS playback
+- Add _tts_playing flag to track TTS audio state precisely
+
+## [0.7.0] - 2026-01-12
+
+### New
+- Gesture detection using HaGRID ONNX models (18 gesture classes)
+- gesture_detected and gesture_confidence entities in Home Assistant
+
+### Fixed
+- Gesture state now properly pushed to Home Assistant in real-time
+
+### Optimized
+- Aggressive power saving - 0.5fps idle mode after 30s without face
+- Gesture detection only runs when face detected (saves CPU)
+
+## [0.6.1] - 2026-01-12
+
+### Fixed
+- Prioritize MicroWakeWord over OpenWakeWord for same-name wake words
+- OpenWakeWord wake words now visible in Home Assistant selection
+- Stop word detection now works correctly
+- STT/LLM response time improved with fixed audio chunk size
+
+## [0.6.0] - 2026-01-11
+
+### New
+- Real-time audio-driven speech animation (SwayRollRT algorithm)
+- JSON-driven animation system - all animations configurable
+
+### Refactored
+- Remove hardcoded actions, use animation offsets only
+
+### Fixed
+- TTS audio analysis now works with local playback
+
+## [0.5.16] - 2026-01-11
+
+### Removed
+- Tap-to-wake feature (too many false triggers)
+
+### New
+- Continuous Conversation switch in Home Assistant
+
+### Refactored
+- Simplified satellite.py and voice_assistant.py
+
+## [0.5.15] - 2026-01-11
+
+### New
+- Audio settings persistence (AGC, Noise Suppression, Tap Sensitivity)
+
+### Refactored
+- Move Sendspin mDNS discovery to zeroconf.py
+
+### Fixed
+- Tap detection not re-enabled during emotion playback in conversation
+
+## [0.5.14] - 2026-01-11
+
+### Fixed
+- Skip ALL wake word processing when pipeline is active
+- Eliminate race condition in pipeline state during continuous conversation
+
+### Improved
+- Control loop increased to 100Hz (daemon updated)
+
+## [0.5.13] - 2026-01-10
+
+### New
+- JSON-driven animation system for conversation states
+- AnimationPlayer class inspired by SimpleDances project
+
+### Refactored
+- Replace SpeechSwayGenerator and BreathingAnimation with unified animation system
+
+## [0.5.12] - 2026-01-10
+
+### Removed
+- Deleted broken hey_reachy wake word model
+
+### Revert
+- Default wake word back to "Okay Nabu"
+
+## [0.5.11] - 2026-01-10
+
+### Fixed
+- Reset feature extractors when switching wake words
+- Add refractory period after wake word switch
+
+## [0.5.10] - 2026-01-10
+
+### Fixed
+- Wake word models now have 'id' attribute set correctly
+- Wake word switching from Home Assistant now works
+
+## [0.5.9] - 2026-01-10
+
+### New
+- Default wake word changed to hey_reachy
+
+### Fixed
+- Wake word switching bug
+
+## [0.5.8] - 2026-01-09
+
+### Fixed
+- Tap detection waits for emotion playback to complete
+- Poll daemon API for move completion
+
+## [0.5.7] - 2026-01-09
+
+### New
+- DOA turn-to-sound at wakeup
+
+### Fixed
+- Show raw DOA angle in Home Assistant (0-180)
+- Invert DOA yaw direction
+
+## [0.5.6] - 2026-01-08
+
+### Fixed
+- Better pipeline state tracking to prevent duplicate audio
+
+## [0.5.5] - 2026-01-08
+
+### New
+- Prevent concurrent pipelines
+- Add prompt sound for continuous conversation
+
+## [0.5.4] - 2026-01-08
+
+### Fixed
+- Wait for RUN_END before starting new conversation
+
+## [0.5.3] - 2026-01-08
+
+### Fixed
+- Improve continuous conversation with conversation_id tracking
+
+## [0.5.2] - 2026-01-08
+
+### Fixed
+- Enable HA control of robot pose
+- Continuous conversation improvements
+
+## [0.5.1] - 2026-01-08
+
+### Fixed
+- Sendspin connects to music_player instead of tts_player
+- Persist tap_sensitivity settings
+- Pause Sendspin during voice assistant wakeup
+- Sendspin prioritize 16kHz sample rate
+
+## [0.5.0] - 2026-01-07
+
+### New
+- Face tracking with adaptive frequency
+- Sendspin multi-room audio integration
+
+### Optimized
+- Shutdown mechanism improvements
+
+## [0.4.0] - 2026-01-07
+
+### Fixed
+- Daemon stability fixes
+
+### New
+- Face tracking enabled by default
+
+### Optimized
+- Microphone settings for better sensitivity
+
+## [0.3.0] - 2026-01-06
+
+### New
+- Tap sensitivity slider entity
+
+### Fixed
+- Music Assistant compatibility
+
+### Optimized
+- Face tracking and tap detection
+
+## [0.2.21] - 2026-01-06
+
+### Fixed
+- Daemon crash - reduce control loop to 2Hz
+- Pause control loop during audio playback
+
+## [0.2.20] - 2026-01-06
+
+### Revert
+- Audio/satellite/voice_assistant to v0.2.9 working state
+
+## [0.2.19] - 2026-01-06
+
+### Fixed
+- Force localhost connection mode to prevent WebRTC errors
+
+## [0.2.18] - 2026-01-06
+
+### Fixed
+- Audio playback - restore wakeup sound
+- Use push_audio_sample for TTS
+
+## [0.2.17] - 2026-01-06
+
+### Removed
+- head_joints/passive_joints entities
+- error_message to diagnostic category
+
+## [0.2.16] - 2026-01-06
+
+### Fixed
+- TTS playback - pause recording during playback
+
+## [0.2.15] - 2026-01-06
+
+### Fixed
+- Use play_sound() instead of push_audio_sample() for TTS
+
+## [0.2.14] - 2026-01-06
+
+### Fixed
+- Pause audio recording during TTS playback
+
+## [0.2.13] - 2026-01-06
+
+### Fixed
+- Don't manually start/stop media - let SDK/daemon manage it
+
+## [0.2.12] - 2026-01-05
+
+### Fixed
+- Disable breathing animation to prevent serial port overflow
+
+## [0.2.11] - 2026-01-05
+
+### Fixed
+- Disable wakeup sound to prevent daemon crash
+- Add debug logging for troubleshooting
+
+## [0.2.10] - 2026-01-05
+
+### Added
+- Debug logging for motion init
+
+### Fixed
+- Audio fallback samplerate
+
+## [0.2.9] - 2026-01-05
+
+### Removed
+- DOA/speech detection - replaced by face tracking
+
+## [0.2.8] - 2026-01-05
+
+### New
+- Replace DOA with YOLO face tracking
+
+## [0.2.7] - 2026-01-05
+
+### Fixed
+- Add DOA caching to prevent ReSpeaker query overload
+
+## [0.2.6] - 2026-01-05
+
+### New
+- Thread-safe ReSpeaker USB access to prevent daemon deadlock
+
+## [0.2.4] - 2026-01-05
+
+### Fixed
+- Microphone volume control via daemon HTTP API
+
+## [0.2.3] - 2026-01-05
+
+### Fixed
+- Daemon crash caused by conflicting pose commands
+- Disable: Pose setter methods in ReachyController
+
+## [0.2.2] - 2026-01-05
+
+### Fixed
+- Second conversation motion failure
+- Reduce: Control loop from 20Hz to 10Hz
+- Improve: Connection recovery (faster reconnect)
+
+## [0.2.1] - 2026-01-05
+
+### Fixed
+- Daemon crash issue
+- Optimize: Code structure
+
+## [0.2.0] - 2026-01-05
+
+### New
+- Automatic facial expressions during conversation
+- New: Emotion playback integration
+
+### Refactored
+- Integrate emotion playback into MovementManager
+
+## [0.1.5] - 2026-01-04
+
+### Optimized
+- Code splitting and organization
+
+### Fixed
+- Program crash issues
+
+## [0.1.0] - 2026-01-01
+
+### New
+- Initial release
+- ESPHome protocol server implementation
+- mDNS auto-discovery for Home Assistant
+- Local wake word detection (microWakeWord)
+- Voice assistant pipeline integration
+- Basic motion feedback (nod, shake)
+
+---
+
+## Version History Summary
+
+| Version | Date | Major Changes |
+|---------|------|--------------|
+| 0.9.9 | 2026-01-28 | SDK buffer overflow fixes, memory leak fixes, gesture detection optimization |
+| 0.9.8 | 2026-01-27 | Mute/Disable entities, HA connection-driven features, log reduction |
+| 0.9.7 | 2026-01-20 | Device ID path fix, animation path fix |
+| 0.9.6 | 2026-01-20 | Code quality tools (ruff, mypy, pre-commit) |
+| 0.9.5 | 2026-01-19 | Modular architecture refactoring, audio latency optimization |
+| 0.9.0 | 2026-01-18 | Robot state monitor, system diagnostics entities |
+| 0.8.7 | 2026-01-18 | Body yaw clamping, face tracking smoothness |
+| 0.8.0 | 2026-01-17 | Emotion keyword mapping (280+ keywords, 35 categories) |
+| 0.7.0 | 2026-01-12 | Gesture detection with HaGRID ONNX models (18 gestures) |
+| 0.6.0 | 2026-01-11 | Real-time audio-driven speech animation, JSON animation system |
+| 0.5.0 | 2026-01-07 | Face tracking, Sendspin multi-room audio |
+| 0.4.0 | 2026-01-07 | Daemon stability, microphone optimization |
+| 0.3.0 | 2026-01-06 | Tap sensitivity slider |
+| 0.2.0 | 2026-01-05 | Emotion playback integration |
+| 0.1.0 | 2026-01-01 | Initial release |
+
+## Project Statistics
+
+- **Total Versions**: 29 (from 0.1.0 to 0.9.9)
+- **Development Period**: ~30 days (2026-01-01 to 2026-01-28)
+- **Average Release Rate**: ~1 version per day
+- **Lines of Code**: ~18,000 lines across 52 Python files
+- **ESPHome Entities**: 54 entities implemented
+- **Supported Features**:
+  - Voice assistant pipeline integration
+  - Local wake word detection (multiple models)
+  - Face tracking with YOLO
+  - Gesture detection (18 classes)
+  - Multi-room audio (Sendspin)
+  - Real-time speech animation
+  - Emotion keyword detection (280+ keywords)
+  - System diagnostics
+
+For detailed implementation notes, see [PROJECT_PLAN.md](./PROJECT_PLAN.md).

Project_Summary.md

@@ -0,0 +1,1439 @@
+# Reachy Mini for Home Assistant - Project Plan (Current snapshot: v1.0.6)
+
+## Project Overview
+
+Integrate Home Assistant voice assistant functionality into Reachy Mini Wi-Fi robot, communicating with Home Assistant via ESPHome protocol.
+
+## Local Reference Directories (DO NOT modify any files in reference directories)
+1. [linux-voice-assistant](reference/linux-voice-assistant) - Linux-based Home Assistant voice assistant app for reference
+2. [Reachy Mini SDK](reference/reachy_mini) - Reachy Mini SDK local directory for reference
+3. [reachy_mini_conversation_app](reference/reachy_mini_conversation_app) - Reachy Mini conversation app for reference
+4. [reachy-mini-desktop-app](reference/reachy-mini-desktop-app) - Reachy Mini desktop app for reference
+5. [sendspin](reference/sendspin-cli/) - Sendspin client for reference
+6. [aiosendspin](reference/aiosendspin/) - Sendspin protocol client library reference
+7. [dynamic_gestures](reference/dynamic_gestures/) - Dynamic gesture reference
+8. [SimpleDances](reference/SimpleDances/) - Local reference snapshot
+
+## Core Design Principles
+
+1. **Zero Configuration** - Users only need to install the app, no manual configuration required
+2. **Native Hardware** - Use robot's built-in microphone and speaker
+3. **Home Assistant Centralized Management** - STT/TTS/intent configuration stays on Home Assistant side
+4. **Motion Feedback** - Provide head movement and antenna animation feedback during voice interaction
+5. **Project Constraints** - Strictly follow [Reachy Mini SDK](reachy_mini) architecture design and constraints
+6. **Code Quality** - Follow Python development standards with consistent code style, clear structure, complete comments, comprehensive documentation, high test coverage, high code quality, readability, maintainability, extensibility, and reusability
+7. **Feature Priority** - Voice conversation with Home Assistant is highest priority; other features are auxiliary and must not affect voice conversation functionality or response speed
+8. **No LED Functions** - LEDs are hidden inside the robot; all LED control is ignored
+9. **Preserve Functionality** - Any code modifications should optimize while preserving completed features; do not remove features to solve problems. When issues occur, prioritize solving problems after referencing examples, not adding various log outputs
+10. **No App-Managed Sleep/Wake** - The app no longer manages robot sleep/wake transitions; current SDK behavior is treated as source of truth
+
+## Technical Architecture
+
+```
+鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?
+鈹?                             Reachy Mini (ARM64)                            鈹?
+鈹?                                                                            鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ AUDIO INPUT 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹? 鈹? ReSpeaker XVF3800 (16kHz)                                            鈹? 鈹?
+鈹? 鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹? 鈹?
+鈹? 鈹? 鈹?4-Mic Array  鈹?鈫?鈹?XVF3800 DSP                                  鈹? 鈹? 鈹?
+鈹? 鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹?鈥?Hardware DSP path available                鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?鈥?App currently relies on HA STT/TTS         鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?鈥?DOA/VAD used by the current runtime        鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?鈥?Direction of Arrival (DOA)                 鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?鈥?Voice Activity Detection (VAD)             鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹? 鈹?
+鈹? 鈹?                                     鈹?                               鈹? 鈹?
+鈹? 鈹?                                     鈻?                               鈹? 鈹?
+鈹? 鈹?                    鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?Wake Word Detection (microWakeWord)          鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?鈥?"Okay Nabu" / "Hey Jarvis"                 鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹?鈥?Stop word detection                        鈹? 鈹? 鈹?
+鈹? 鈹?                    鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹? 鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹?                                                                            鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ AUDIO OUTPUT 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹? 鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?   鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? 鈹?
+鈹? 鈹? 鈹?TTS Player               鈹?   鈹?Music Player (Sendspin)          鈹?鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Voice assistant speech 鈹?   鈹?鈥?Multi-room audio streaming     鈹?鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Sound effects          鈹?   鈹?鈥?Auto-discovery via mDNS        鈹?鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Priority over music    鈹?   鈹?鈥?Auto-pause during conversation 鈹?鈹? 鈹?
+鈹? 鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?   鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? 鈹?
+鈹? 鈹?                鈹?                             鈹?                     鈹? 鈹?
+鈹? 鈹?                鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?                     鈹? 鈹?
+鈹? 鈹?                               鈻?                                     鈹? 鈹?
+鈹? 鈹?                鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹? 鈹?
+鈹? 鈹?                鈹?ReSpeaker Speaker (16kHz)                        鈹? 鈹? 鈹?
+鈹? 鈹?                鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹? 鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹?                                                                            鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ VISION & TRACKING 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹? 鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?   鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? 鈹?
+鈹? 鈹? 鈹?Camera (VPU accelerated) 鈹?鈫? 鈹?YOLO Face Detection              鈹?鈹? 鈹?
+鈹? 鈹? 鈹?鈥?MJPEG stream server    鈹?   鈹?鈥?AdamCodd/YOLOv11n-face         鈹?鈹? 鈹?
+鈹? 鈹? 鈹?鈥?ESPHome Camera entity  鈹?   鈹?鈥?Adaptive frame rate:           鈹?鈹? 鈹?
+鈹? 鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?   鈹?  - 15fps: conversation/face     鈹?鈹? 鈹?
+鈹? 鈹?                                 鈹?  - 2fps: idle (power saving)    鈹?鈹? 鈹?
+鈹? 鈹?                                 鈹?鈥?look_at_image() pose calc      鈹?鈹? 鈹?
+鈹? 鈹?                                 鈹?鈥?Smooth return after face lost  鈹?鈹? 鈹?
+鈹? 鈹?                                 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹? 鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹?                                                                            鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ MOTION CONTROL 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹? 鈹? MovementManager (50Hz Control Loop)                                  鈹? 鈹?
+鈹? 鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?Motion Layers (Priority: Move > Action > SpeechSway > Breath)  鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈹?Move Queue 鈹?鈹?Actions    鈹?鈹?SpeechSway 鈹?鈹?Breathing    鈹? 鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈹?(Emotions) 鈹?鈹?(Nod/Shake)鈹?鈹?(Voice VAD)鈹?鈹?(Idle anim)  鈹? 鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?  鈹? 鈹?
+鈹? 鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹? 鈹?
+鈹? 鈹?                                                                      鈹? 鈹?
+鈹? 鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?Face Tracking Offsets (Secondary Pose Overlay)                 鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Pitch offset: +9掳 (down compensation)                        鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Yaw offset: -7掳 (right compensation)                         鈹?  鈹? 鈹?
+鈹? 鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹? 鈹?
+鈹? 鈹?                                                                      鈹? 鈹?
+鈹? 鈹?  State Machine: on_wakeup 鈫?on_listening 鈫?on_speaking 鈫?on_idle     鈹? 鈹?
+鈹? 鈹?                                                                      鈹? 鈹?
+鈹? 鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?Body Following                                                鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Body yaw syncs with head yaw for natural tracking            鈹?  鈹? 鈹?
+鈹? 鈹? 鈹?鈥?Extracted from final head pose matrix                        鈹?  鈹? 鈹?
+鈹? 鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?  鈹? 鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹?                                                                            鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ GESTURE DETECTION 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹? 鈹? HaGRID ONNX Models                                                鈹? 鈹?
+鈹? 鈹? 鈥?18 gesture classes (call, like, dislike, fist, ok, palm, etc.)    鈹? 鈹?
+鈹? 鈹? 鈥?Runtime result publishing only                                    鈹? 鈹?
+鈹? 鈹? 鈥?Batch detection: all hands (not just highest confidence)         鈹? 鈹?
+鈹? 鈹? 鈥?Detection cadence: adaptive scheduler + minimum processing FPS    鈹? 鈹?
+鈹? 鈹? 鈥?No confidence filtering - all detections passed to Home Assistant鈹? 鈹?
+鈹? 鈹? 鈥?Runtime switchable (default OFF, model unloaded when disabled)    鈹? 鈹?
+鈹? 鈹? 鈥?Real-time state push to Home Assistant                            鈹? 鈹?
+鈹? 鈹? 鈥?No conflicts with face tracking (shared frame, independent)       鈹? 鈹?
+鈹? 鈹? 鈥?SDK integration: MediaBackend detection, proper resource cleanup 鈹? 鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹?                                                                            鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ ESPHOME SERVER 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹? 鈹? Port 6053 (mDNS auto-discovery)                                      鈹? 鈹?
+鈹? 鈹? 鈥?Entity count evolves by release (sensors, controls, media, camera) 鈹? 鈹?
+鈹? 鈹? 鈥?Voice Assistant pipeline integration                               鈹? 鈹?
+鈹? 鈹? 鈥?Real-time state synchronization                                    鈹? 鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹���鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹?
+鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?
+                                       鈹?
+                                       鈹?ESPHome Protocol (protobuf)
+                                       鈻?
+鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?
+鈹?                           Home Assistant                                   鈹?
+鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹?
+鈹? 鈹?STT Engine       鈹? 鈹?Intent Processing鈹? 鈹?TTS Engine                 鈹?鈹?
+鈹? 鈹?(User configured)鈹? 鈹?(Conversation)   鈹? 鈹?(User configured)          鈹?鈹?
+鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?鈹?
+鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹?
+```
+
+### Software Module Architecture (v1.0.6)
+
+```
+reachy_mini_home_assistant/
+鈹?
+鈹溾攢鈹€ main.py                    # ReachyMiniApp entry point
+鈹溾攢鈹€ __main__.py                # Standalone CLI entry point
+鈹溾攢鈹€ voice_assistant.py         # Voice assistant service orchestrator
+鈹溾攢鈹€ reachy_controller.py       # Reachy Mini SDK wrapper
+鈹溾攢鈹€ models.py                  # Data models / preferences / server state
+鈹?
+鈹溾攢鈹€ core/                      # Core Infrastructure
+鈹?  鈹溾攢鈹€ config.py              # Centralized nested configuration
+鈹?  鈹溾攢鈹€ service_base.py        # Suspend/resume-aware service helpers
+鈹?  鈹溾攢鈹€ system_diagnostics.py  # System diagnostics
+鈹?  鈹溾攢鈹€ exceptions.py          # Custom exception classes
+鈹?  鈹斺攢鈹€ util.py                # Utility functions
+鈹?
+鈹溾攢鈹€ motion/                    # Motion Control
+鈹?  鈹溾攢鈹€ movement_manager.py    # 50Hz unified motion control loop
+鈹?  鈹溾攢鈹€ command_runtime.py     # Command queue handling / state transitions
+鈹?  鈹溾攢鈹€ control_runtime.py     # Control-loop runtime helpers
+鈹?  鈹溾攢鈹€ idle_runtime.py        # Idle behavior / idle rest handling
+鈹?  鈹溾攢鈹€ antenna.py             # Antenna control / freeze logic
+鈹?  鈹溾攢鈹€ pose_composer.py       # Pose composition from multiple sources
+鈹?  鈹溾攢鈹€ smoothing.py           # Motion smoothing algorithms
+鈹?  鈹溾攢鈹€ state_machine.py       # Robot state definitions / idle config parsing
+鈹?  鈹溾攢鈹€ animation_player.py    # Animation player
+鈹?  鈹溾攢鈹€ emotion_moves.py       # Emotion moves
+鈹?  鈹溾攢鈹€ speech_sway.py         # Speech-driven head micro-movements
+鈹?  鈹斺攢鈹€ reachy_motion.py       # Reachy motion API
+鈹?
+鈹溾攢鈹€ vision/                    # Vision Processing
+鈹?  鈹溾攢鈹€ camera_server.py       # MJPEG camera stream server facade
+鈹?  鈹溾攢鈹€ camera_runtime.py      # Camera lifecycle helpers
+鈹?  鈹溾攢鈹€ camera_processing.py   # Frame capture / AI processing helpers
+鈹?  鈹溾攢鈹€ camera_http.py         # HTTP handlers for stream/snapshot
+鈹?  鈹溾攢鈹€ head_tracker.py        # YOLO face detector
+鈹?  鈹溾攢鈹€ gesture_detector.py    # HaGRID gesture detection
+鈹?  鈹溾攢鈹€ face_tracking_interpolator.py  # Smooth face tracking
+鈹?  鈹斺攢鈹€ frame_processor.py     # Adaptive frame rate management
+鈹?
+鈹溾攢鈹€ audio/                     # Audio runtime support
+鈹?  鈹溾攢鈹€ audio_player.py                # AudioPlayer facade
+鈹?  鈹溾攢鈹€ audio_player_shared.py         # Shared audio/sendspin constants + helpers
+鈹?  鈹溾攢鈹€ audio_player_playback.py       # Playback orchestration / lifecycle
+鈹?  鈹溾攢鈹€ audio_player_local.py          # Local file + fallback playback
+鈹?  鈹溾攢鈹€ audio_player_stream_pcm.py     # PCM streaming playback
+鈹?  鈹溾攢鈹€ audio_player_stream_decoded.py # Decoded/GStreamer streaming playback
+鈹?  鈹溾攢鈹€ audio_player_sendspin.py       # Sendspin runtime integration
+鈹?  鈹溾攢鈹€ microphone.py                  # Hardware audio helper / legacy tuning code
+鈹?  鈹斺攢鈹€ doa_tracker.py                 # Direction of Arrival tracking
+鈹?
+鈹溾攢鈹€ entities/                  # Home Assistant Entities
+鈹?  鈹溾攢鈹€ entity.py              # ESPHome base entity
+鈹?  鈹溾攢鈹€ entity_registry.py     # ESPHome entity registry
+鈹?  鈹溾攢鈹€ entity_factory.py      # Entity creation factory
+鈹?  鈹溾攢鈹€ entity_keys.py         # Entity key constants
+鈹?  鈹溾攢鈹€ entity_extensions.py   # Extended entity types
+鈹?  鈹溾攢鈹€ runtime_entity_setup.py # Runtime/control entity wiring
+鈹?  鈹溾攢鈹€ sensor_entity_setup.py # Sensor/diagnostic entity wiring
+鈹?  鈹溾攢鈹€ event_emotion_mapper.py # HA event 鈫?Emotion mapping
+鈹?  鈹斺攢鈹€ emotion_detector.py    # Disabled runtime path for text emotion detection
+鈹?
+鈹溾攢鈹€ protocol/                  # Protocol Handling
+鈹?  鈹溾攢鈹€ satellite.py           # ESPHome protocol handler facade
+鈹?  鈹溾攢鈹€ api_server.py          # HTTP API server
+鈹?  鈹溾攢鈹€ zeroconf.py            # mDNS discovery
+鈹?  鈹溾攢鈹€ entity_bridge.py       # Protocol/entity bridge helpers
+鈹?  鈹溾攢鈹€ message_dispatch.py    # ESPHome message dispatch
+鈹?  鈹溾攢鈹€ motion_bridge.py       # Voice 鈫?motion bridge
+鈹?  鈹溾攢鈹€ session_flow.py        # Conversation lifecycle helpers
+鈹?  鈹溾攢鈹€ voice_pipeline.py      # Voice event handling / TTS / stop / ducking
+鈹?  鈹斺攢鈹€ wakeword_assets.py     # Wake word asset helpers
+鈹?
+鈹溾攢鈹€ animations/               # Animation definitions
+鈹?  鈹斺攢鈹€ conversation_animations.json  # Unified built-in behavior resource file
+鈹?
+鈹斺攢鈹€ wakewords/                # Wake word models
+    鈹溾攢鈹€ okay_nabu.json/.tflite
+    鈹溾攢鈹€ hey_jarvis.json/.tflite
+    鈹溾攢鈹€ alexa.json/.tflite
+    鈹溾攢鈹€ hey_luna.json/.tflite
+    鈹斺攢鈹€ stop.json/.tflite
+```
+
+
+### Current Runtime Defaults (v1.0.6)
+
+- `idle_behavior_enabled`: user-controlled
+- `sendspin_enabled`: OFF
+- `face_tracking_enabled`: OFF
+- `gesture_detection_enabled`: OFF
+- `face_confidence_threshold`: 0.5 (persistent)
+- `continuous_conversation`: user-controlled
+- `Idle Behavior = OFF` means a parked no-animation state aligned to configured idle rest pose
+- When `Idle Behavior = OFF`, camera server is stopped entirely to save resources
+- When `Idle Behavior = ON`, camera server can run and `/snapshot` supports on-demand frame capture when cache is empty
+- Idle antenna behavior: torque disabled in `IDLE`, re-enabled when leaving `IDLE`
+- Voice phases and HA-triggered emotions are routed through one built-in zero-config behavior layer
+
+When face/gesture switches are OFF, their models are unloaded to save resources.
+
+### Current Audio Startup Note (SDK 1.7.0)
+
+- The app now aligns to the current Reachy Mini SDK media model instead of carrying older compatibility paths.
+- Camera snapshots can be fetched on demand when the MJPEG cache is empty and the camera server is still running.
+- Audio block size is currently `512` samples to reduce CPU overhead versus the earlier `256`-sample path.
+
+### Latest Incremental Update (2026-03-04) - Viewer-Aware Camera Streaming
+
+- MJPEG encoding/push is now viewer-aware: when no `/stream` client is connected, continuous MJPEG encoding is skipped to reduce CPU usage.
+- Face tracking and gesture detection still run without active stream viewers, so AI behavior remains available.
+- `/snapshot` now supports on-demand frame encode when no cached stream frame exists.
+- Stream output no longer forces fixed 1080p/25fps; it follows camera backend defaults (resolution/FPS) and only falls back when backend FPS is unavailable.
+- Transition from "watching" to "not watching" returns to adaptive idle pacing for resource saving.
+
+## Completed Features
+
+### Core Features
+- [x] ESPHome protocol server implementation
+- [x] mDNS service discovery (auto-discovered by Home Assistant)
+- [x] Local wake word detection (microWakeWord)
+- [x] Continuous conversation mode (controlled via Home Assistant switch)
+- [x] Audio stream transmission to Home Assistant
+- [x] TTS audio playback
+- [x] Stop word detection
+
+### Reachy Mini Integration
+- [x] Use Reachy Mini SDK microphone input
+- [x] Use Reachy Mini SDK speaker output
+- [x] Head motion control (nod, shake, gaze)
+- [x] Antenna animation control
+- [x] Voice state feedback actions
+- [x] YOLO face tracking (complements DOA wakeup orientation)
+- [x] 50Hz unified motion control loop
+
+### Application Architecture
+- [x] Compliant with Reachy Mini App architecture
+
+
+
+## File List
+
+```
+reachy_mini_ha_voice/
+鈹溾攢鈹€ reachy_mini_ha_voice/
+鈹?  鈹溾攢鈹€ __init__.py             # Package initialization (v0.9.9)
+鈹?  鈹溾攢鈹€ __main__.py             # Command line entry
+鈹?  鈹溾攢鈹€ main.py                 # ReachyMiniApp entry
+鈹?  鈹溾攢鈹€ voice_assistant.py      # Voice assistant service (1270 lines)
+鈹?  鈹溾攢鈹€ protocol/               # ESPHome protocol handling
+鈹?  鈹?  鈹溾攢鈹€ __init__.py         # Module exports (13 lines)
+鈹?  鈹?  鈹溾攢鈹€ satellite.py        # ESPHome protocol handler facade
+鈹?  鈹?  鈹溾攢鈹€ api_server.py       # HTTP API server
+鈹?  鈹?  鈹溾攢鈹€ zeroconf.py         # mDNS discovery
+鈹?  鈹?  鈹溾攢鈹€ entity_bridge.py    # Protocol/entity bridge helpers
+鈹?  鈹?  鈹溾攢鈹€ message_dispatch.py # ESPHome message dispatch
+鈹?  鈹?  鈹溾攢鈹€ motion_bridge.py    # Voice 鈫?motion bridge
+鈹?  鈹?  鈹溾攢鈹€ session_flow.py     # Conversation lifecycle helpers
+鈹?  鈹?  鈹溾攢鈹€ voice_pipeline.py   # Voice event handling / TTS / stop / ducking
+鈹?  鈹?  鈹斺攢鈹€ wakeword_assets.py  # Wake word asset helpers
+鈹?  鈹溾攢鈹€ models.py               # Data models
+鈹?  鈹斺攢鈹€ reachy_controller.py    # Reachy Mini controller wrapper (961 lines)
+鈹?  鈹?
+鈹?  鈹溾攢鈹€ core/                   # Core infrastructure modules
+鈹?  鈹?  鈹溾攢鈹€ __init__.py         # Module exports
+鈹?  鈹?  鈹溾攢鈹€ config.py           # Centralized configuration (368 lines)
+鈹?  鈹?  鈹溾攢鈹€ service_base.py     # Suspend/resume-aware service helpers
+鈹?  鈹?  鈹溾攢鈹€ system_diagnostics.py   # System diagnostics (250 lines)
+鈹?  鈹?  鈹斺攢鈹€ exceptions.py       # Custom exception classes (68 lines)
+鈹?  鈹?  鈹斺攢鈹€ util.py             # Utility functions (28 lines)
+鈹?  鈹?
+鈹?  鈹溾攢鈹€ motion/                 # Motion control modules
+鈹?  鈹?  鈹溾攢鈹€ __init__.py         # Module exports
+鈹?  鈹?  鈹溾攢鈹€ antenna.py          # Antenna freeze/unfreeze control
+鈹?  鈹?  鈹溾攢鈹€ pose_composer.py    # Pose composition utilities
+鈹?  鈹?  鈹溾攢鈹€ command_runtime.py  # Command queue handling / state transitions
+鈹?  鈹?  鈹溾攢鈹€ control_runtime.py  # Control-loop runtime helpers
+鈹?  鈹?  鈹溾攢鈹€ idle_runtime.py     # Idle behavior / idle rest handling
+鈹?  鈹?  鈹溾攢鈹€ smoothing.py        # Smoothing/transition algorithms
+鈹?  鈹?  鈹溾攢鈹€ state_machine.py    # State machine definitions
+鈹?  鈹?  鈹溾攢鈹€ animation_player.py # Animation player
+鈹?  鈹?  鈹溾攢鈹€ emotion_moves.py    # Emotion moves
+鈹?  鈹?  鈹溾攢鈹€ speech_sway.py      # Speech-driven head micro-movements (338 lines)
+鈹?  鈹?  鈹斺攢鈹€ reachy_motion.py    # Reachy motion API
+鈹?  鈹?
+鈹?  鈹溾攢鈹€ vision/                 # Vision processing modules
+鈹?  鈹?  鈹溾攢鈹€ __init__.py         # Module exports (30 lines)
+鈹?  鈹?  鈹溾攢鈹€ frame_processor.py  # Adaptive frame rate management (227 lines)
+鈹?  鈹?  鈹溾攢鈹€ face_tracking_interpolator.py  # Face lost interpolation (253 lines)
+鈹?  鈹?  鈹溾攢鈹€ gesture_detector.py  # HaGRID gesture detection
+鈹?  鈹?  鈹溾攢鈹€ head_tracker.py     # YOLO face detector
+鈹?  鈹?  鈹溾攢鈹€ camera_runtime.py   # Camera lifecycle helpers
+鈹?  鈹?  鈹溾攢鈹€ camera_processing.py # Frame capture / AI processing helpers
+鈹?  鈹?  鈹溾攢鈹€ camera_http.py      # HTTP handlers for stream/snapshot
+鈹?  鈹?  鈹斺攢鈹€ camera_server.py     # MJPEG camera stream server facade
+鈹?  鈹?
+鈹?  鈹溾攢鈹€ audio/                  # Audio runtime modules
+鈹?  鈹?  鈹溾攢鈹€ __init__.py         # Module exports (21 lines)
+鈹?  鈹?  鈹溾攢鈹€ microphone.py       # Hardware audio helper / legacy tuning code
+鈹?  鈹?  鈹溾攢鈹€ doa_tracker.py      # Direction of Arrival tracking
+鈹?  鈹?  鈹溾攢鈹€ audio_player.py     # AudioPlayer facade
+鈹?  鈹?  鈹溾攢鈹€ audio_player_shared.py # Shared audio/sendspin constants + helpers
+鈹?  鈹?  鈹溾攢鈹€ audio_player_playback.py # Playback orchestration / lifecycle
+鈹?  鈹?  鈹溾攢鈹€ audio_player_local.py # Local file + fallback playback
+鈹?  鈹?  鈹溾攢鈹€ audio_player_stream_pcm.py # PCM streaming playback
+鈹?  鈹?  鈹溾攢鈹€ audio_player_stream_decoded.py # Decoded/GStreamer streaming playback
+鈹?  鈹?  鈹斺攢鈹€ audio_player_sendspin.py # Sendspin runtime integration
+鈹?  鈹?
+鈹?  鈹溾攢鈹€ entities/               # Home Assistant entity modules
+鈹?  鈹?  鈹溾攢鈹€ __init__.py         # Module exports (38 lines)
+鈹?  鈹?  鈹溾攢鈹€ entity.py           # ESPHome base entity (402 lines)
+鈹?  鈹?  鈹溾攢鈹€ entity_factory.py   # Entity factory pattern (440 lines)
+鈹?  鈹?  鈹溾攢鈹€ entity_keys.py      # Entity key constants (155 lines)
+鈹?  鈹?  鈹溾攢鈹€ entity_extensions.py  # Extended entity types (258 lines)
+鈹?  鈹?  鈹溾攢鈹€ entity_registry.py  # ESPHome entity registry
+鈹?  鈹?  鈹溾攢鈹€ runtime_entity_setup.py # Runtime/control entity wiring
+鈹?  鈹?  鈹溾攢鈹€ sensor_entity_setup.py # Sensor/diagnostic entity wiring
+鈹?  鈹?  鈹溾攢鈹€ event_emotion_mapper.py  # HA event to emotion mapping
+鈹?  鈹?  鈹斺攢鈹€ emotion_detector.py # Disabled runtime path for text emotion detection
+鈹?  鈹?
+鈹?  鈹溾攢鈹€ animations/             # Animation definitions
+鈹?  鈹?  鈹斺攢鈹€ conversation_animations.json  # Unified animations / gestures / HA events / keyword resources
+鈹?  鈹?
+鈹?  鈹斺攢鈹€ wakewords/              # Wake word models
+鈹?      鈹溾攢鈹€ okay_nabu.json/.tflite
+鈹?      鈹溾攢鈹€ hey_jarvis.json/.tflite (openWakeWord)
+鈹?      鈹溾攢鈹€ alexa.json/.tflite
+鈹?      鈹溾攢鈹€ hey_luna.json/.tflite
+鈹?      鈹斺攢鈹€ stop.json/.tflite   # Stop word detection
+鈹?
+鈹溾攢鈹€ sounds/                     # Sound effect files (auto-download)
+鈹?  鈹溾攢鈹€ wake_word_triggered.flac
+鈹?  鈹斺攢鈹€ timer_finished.flac
+鈹溾攢鈹€ pyproject.toml              # Project configuration
+鈹溾攢鈹€ README.md                   # Documentation
+鈹溾攢鈹€ changelog.json              # Version changelog
+鈹斺攢鈹€ PROJECT_PLAN.md             # Project plan
+```
+
+## Dependencies
+
+```toml
+dependencies = [
+    "reachy-mini>=1.7.0",
+    "soundfile>=0.13.0",
+    "numpy>=2.2.5,<=2.2.5",
+    "opencv-python>=4.12.0.88",
+    "pymicro-wakeword>=2.0.0,<3.0.0",
+    "pyopen-wakeword>=1.0.0,<2.0.0",
+    "aioesphomeapi>=43.10.1",
+    "zeroconf>=0.131,<1",
+    "websockets>=12,<16",
+    "aiohttp",
+    "scipy>=1.15.3,<2.0.0",
+    "ultralytics",
+    "supervision",
+    "aiosendspin>=5.1,<6.0",
+    "onnxruntime>=1.18.0",
+    "torch==2.5.1",
+    "torchvision==0.20.1",
+    "pillow<12.0",
+    "pydantic<=2.12.5",
+    "requests>=2.33.0",
+    "gstreamer-bundle==1.28.1; sys_platform != 'linux'",
+]
+```
+
+## Usage Flow
+
+1. **Install App**
+   - Install `reachy_mini_ha_voice` from Reachy Mini App Store
+
+2. **Start App**
+   - App auto-starts ESPHome server (port 6053)
+   - Auto-downloads required models and sounds
+
+3. **Connect Home Assistant**
+   - Home Assistant auto-discovers device (mDNS)
+   - Or manually add: Settings 閳?Devices & Services 閳?Add Integration 閳?ESPHome
+
+4. **Use Voice Assistant**
+   - Say "Okay Nabu" to wake
+   - Speak command
+   - Reachy Mini provides motion feedback
+
+## ESPHome Entity Planning
+
+Based on deep analysis of Reachy Mini SDK, the following entities are exposed to Home Assistant:
+
+### Implemented Entities
+
+| Entity Type | Name | Description |
+|-------------|------|-------------|
+| Media Player | `media_player` | Audio playback control |
+| Voice Assistant | `voice_assistant` | Voice assistant pipeline |
+
+### Implemented Control Entities (Read/Write)
+
+#### Phase 1-3: Basic Controls and Pose
+
+| ESPHome Entity Type | Name | SDK API | Range/Options | Description |
+|---------------------|------|---------|---------------|-------------|
+| `Number` | `speaker_volume` | `AudioPlayer.set_volume()` | 0-100 | Speaker volume |
+| `Switch` | `idle_behavior_enabled` | `set_idle_behavior_enabled()` | off=parked/on=idle runtime enabled | Unified idle behavior toggle |
+| `Number` | `head_x` | `goto_target(head=...)` | 卤50mm | Head X position control |
+| `Number` | `head_y` | `goto_target(head=...)` | 卤50mm | Head Y position control |
+| `Number` | `head_z` | `goto_target(head=...)` | 卤50mm | Head Z position control |
+| `Number` | `head_roll` | `goto_target(head=...)` | -40掳 ~ +40掳 | Head roll angle control |
+| `Number` | `head_pitch` | `goto_target(head=...)` | -40掳 ~ +40掳 | Head pitch angle control |
+| `Number` | `head_yaw` | `goto_target(head=...)` | -180掳 ~ +180掳 | Head yaw angle control |
+| `Number` | `body_yaw` | `goto_target(body_yaw=...)` | -160掳 ~ +160掳 | Body yaw angle control |
+| `Number` | `antenna_left` | `goto_target(antennas=...)` | -90掳 ~ +90掳 | Left antenna angle control |
+| `Number` | `antenna_right` | `goto_target(antennas=...)` | -90掳 ~ +90掳 | Right antenna angle control |
+
+#### Phase 4: Gaze Control
+
+| ESPHome Entity Type | Name | SDK API | Range/Options | Description |
+|---------------------|------|---------|---------------|-------------|
+| `Number` | `look_at_x` | `look_at_world(x, y, z)` | World coordinates | Gaze point X coordinate |
+| `Number` | `look_at_y` | `look_at_world(x, y, z)` | World coordinates | Gaze point Y coordinate |
+| `Number` | `look_at_z` | `look_at_world(x, y, z)` | World coordinates | Gaze point Z coordinate |
+
+
+### Implemented Sensor Entities (Read-only)
+
+#### Phase 1 & 5: Basic Status and Audio Sensors
+
+| ESPHome Entity Type | Name | SDK API | Description |
+|---------------------|------|---------|-------------|
+| `Text Sensor` | `daemon_state` | `DaemonStatus.state` | Daemon status |
+| `Binary Sensor` | `backend_ready` | `backend_status.ready` | Backend ready status |
+| `Text Sensor` | `error_message` | `DaemonStatus.error` | Current error message |
+| `Sensor` | `doa_angle` | `DoAInfo.angle` | Sound source direction angle (鎺? |
+| `Binary Sensor` | `speech_detected` | `DoAInfo.speech_detected` | Speech detection status |
+
+#### Phase 6: Diagnostic Information
+
+| ESPHome Entity Type | Name | SDK API | Description |
+|---------------------|------|---------|-------------|
+| `Sensor` | `control_loop_frequency` | `control_loop_stats` | Control loop frequency (Hz) |
+| `Text Sensor` | `sdk_version` | `DaemonStatus.version` | SDK version |
+| `Text Sensor` | `robot_name` | `DaemonStatus.robot_name` | Robot name |
+| `Binary Sensor` | `wireless_version` | `DaemonStatus.wireless_version` | Wireless version flag |
+| `Binary Sensor` | `simulation_mode` | `DaemonStatus.simulation_enabled` | Simulation mode flag |
+| `Text Sensor` | `wlan_ip` | `DaemonStatus.wlan_ip` | Wireless IP address |
+
+#### Phase 7: IMU Sensors (Wireless version only)
+
+| ESPHome Entity Type | Name | SDK API | Description |
+|---------------------|------|---------|-------------|
+| `Sensor` | `imu_accel_x` | `mini.imu["accelerometer"][0]` | X-axis acceleration (m/s铏? |
+| `Sensor` | `imu_accel_y` | `mini.imu["accelerometer"][1]` | Y-axis acceleration (m/s铏? |
+| `Sensor` | `imu_accel_z` | `mini.imu["accelerometer"][2]` | Z-axis acceleration (m/s铏? |
+| `Sensor` | `imu_gyro_x` | `mini.imu["gyroscope"][0]` | X-axis angular velocity (rad/s) |
+| `Sensor` | `imu_gyro_y` | `mini.imu["gyroscope"][1]` | Y-axis angular velocity (rad/s) |
+| `Sensor` | `imu_gyro_z` | `mini.imu["gyroscope"][2]` | Z-axis angular velocity (rad/s) |
+| `Sensor` | `imu_temperature` | `mini.imu["temperature"]` | IMU temperature (鎺矯) |
+
+#### Current Runtime Control and Sensor Entities
+
+| Phase | ESPHome Entity Type | Name | Description |
+|------|---------------------|------|-------------|
+| 1 | `Switch` | `mute` | Suspend/resume the voice pipeline |
+| 1 | `Switch` | `camera_disabled` | Disable/enable camera runtime |
+| 1 | `Switch` | `idle_behavior_enabled` | Unified idle motion / antenna / micro-actions toggle |
+| 1 | `Switch` | `sendspin_enabled` | Enable/disable Sendspin playback integration |
+| 1 | `Switch` | `face_tracking_enabled` | Enable/disable face tracking models |
+| 1 | `Switch` | `gesture_detection_enabled` | Enable/disable gesture detection models |
+| 1 | `Number` | `face_confidence_threshold` | Face tracking confidence threshold (0-1) |
+| 2 | `Binary Sensor` | `services_suspended` | Runtime suspension state |
+| 8 | `Select` | `emotion` | Manual emotion trigger |
+| 10 | `Camera` | `camera` | ESPHome camera entity / live preview |
+| 21 | `Switch` | `continuous_conversation` | Multi-turn conversation mode |
+| 22 | `Text Sensor` | `gesture_detected` | Current detected gesture |
+| 22 | `Sensor` | `gesture_confidence` | Current gesture confidence |
+| 23 | `Binary Sensor` | `face_detected` | Face currently visible |
+
+> **Note**: Head position (x/y/z) and angles (roll/pitch/yaw), body yaw, antenna angles are all **controllable** entities,
+> using `Number` type for bidirectional control. Call `goto_target()` when setting new values, call `get_current_head_pose()` etc. when reading current values.
+
+### Implementation Priority
+
+1. **Phase 1 - Basic Status and Volume** (High Priority) 閴?**Completed**
+   - [x] `daemon_state` - Daemon status sensor
+   - [x] `backend_ready` - Backend ready status
+   - [x] `error_message` - Error message
+   - [x] `speaker_volume` - Speaker volume control
+
+2. **Phase 2 - Runtime State** (High Priority) 鉁?**Completed**
+   - [x] `services_suspended` - Service suspension state sensor
+   - [x] App-managed sleep/wake entities removed from the current runtime
+
+3. **Phase 3 - Pose Control** (Medium Priority) 閴?**Completed**
+   - [x] `head_x/y/z` - Head position control
+   - [x] `head_roll/pitch/yaw` - Head angle control
+   - [x] `body_yaw` - Body yaw angle control
+   - [x] `antenna_left/right` - Antenna angle control
+
+4. **Phase 4 - Gaze Control** (Medium Priority) 閴?**Completed**
+   - [x] `look_at_x/y/z` - Gaze point coordinate control
+
+5. **Phase 5 - DOA (Direction of Arrival)** 閴?**Re-added for wakeup turn-to-sound**
+   - [x] `doa_angle` - Sound source direction (degrees, 0-180鎺? where 0鎺?left, 90鎺?front, 180鎺?right)
+   - [x] `speech_detected` - Speech detection status
+   - [x] Turn-to-sound at wakeup (robot turns toward speaker when wake word detected)
+   - [x] Direction correction: `yaw = 锜?2 - doa` (fixed left/right inversion)
+   - Note: DOA only read once at wakeup to avoid daemon pressure; face tracking takes over after
+
+6. **Phase 6 - Diagnostic Information** (Low Priority) 閴?**Completed**
+   - [x] `control_loop_frequency` - Control loop frequency
+   - [x] `sdk_version` - SDK version
+   - [x] `robot_name` - Robot name
+   - [x] `wireless_version` - Wireless version flag
+   - [x] `simulation_mode` - Simulation mode flag
+   - [x] `wlan_ip` - Wireless IP address
+
+7. **Phase 7 - IMU Sensors** (Optional, wireless version only) 閴?**Completed**
+   - [x] `imu_accel_x/y/z` - Accelerometer
+   - [x] `imu_gyro_x/y/z` - Gyroscope
+   - [x] `imu_temperature` - IMU temperature
+
+8. **Phase 8 - Emotion Control** 閴?**Completed**
+    - [x] `emotion` - Emotion selector (Happy/Sad/Angry/Fear/Surprise/Disgust)
+
+9. **Phase 10 - Camera Integration** 閴?**Completed**
+    - [x] `camera` - ESPHome Camera entity (live preview)
+
+10. **Phase 11 - LED Control** 閴?**Disabled (LEDs hidden inside robot)**
+    - [ ] `led_brightness` - LED brightness (0-100%) - Commented out
+    - [ ] `led_effect` - LED effect (off/solid/breathing/rainbow/doa) - Commented out
+    - [ ] `led_color_r/g/b` - LED RGB color (0-255) - Commented out
+
+11. **Phase 13 - Sendspin Audio Playback Support** 閴?**Completed**
+    - [x] `sendspin_enabled` - Sendspin switch (Switch)
+    - [x] AudioPlayer integrates aiosendspin library
+    - [x] Local music/sendspin path coexists with voice playback and is auto-paused during conversation
+
+12. **Phase 21 - Continuous Conversation** 閴?**Completed**
+    - [x] `continuous_conversation` - Conversation continuation switch
+
+13. **Phase 22 - Gesture Detection** 鉁?**Completed (current runtime behavior)**
+    - [x] `gesture_detected` - Detected gesture name (Text Sensor)
+    - [x] `gesture_confidence` - Gesture detection confidence % (Sensor)
+    - [x] HaGRID ONNX models: hand_detector.onnx + crops_classifier.onnx
+    - [x] Real-time state push to Home Assistant
+    - [x] Runtime gesture result publishing only (no gesture-driven robot actions)
+    - [x] Runtime toggle supported (default OFF, model unload on disable)
+    - [x] Batch detection: returns all detected hands (not just highest confidence)
+    - [x] Minimum processing cadence preserved for responsiveness
+    - [x] No conflicts with face tracking (shared frame, independent processing)
+    - [x] SDK integration: MediaBackend detection, proper resource cleanup on shutdown
+    - [x] 18 supported gestures:
+      | Gesture | Emoji | Gesture | Emoji |
+      |---------|-------|---------|-------|
+      | call | 棣冾樉 | like | 棣冩啢 |
+      | dislike | 棣冩啣 | mute | 棣冦亱 |
+      | fist | 閴?| ok | 棣冩啠 |
+      | four | 棣冩瀾閿?| one | 閳芥繐绗?|
+      | palm | 閴?| peace | 閴佸矉绗?|
+      | peace_inverted | 棣冩暰閴佸矉绗?| rock | 棣冾樈 |
+      | stop | 棣冩磧 | stop_inverted | 棣冩暰棣冩磧 |
+      | three | 3閿斿繆鍎?| three2 | 棣冾檮 |
+      | two_up | 閴佸矉绗嶉埥婵撶瑣 | two_up_inverted | 棣冩暰閴佸矉绗嶉埥婵撶瑣 |
+
+14. **Phase 23 - Face Detection** 閴?**Completed**
+    - [x] `face_detected` - Face visibility sensor
+
+15. **Phase 24 - System Diagnostics** 閴?**Completed**
+    - [x] `sys_cpu_percent` - CPU usage percentage (Sensor, diagnostic)
+    - [x] `sys_cpu_temperature` - CPU temperature in Celsius (Sensor, diagnostic)
+    - [x] `sys_memory_percent` - Memory usage percentage (Sensor, diagnostic)
+    - [x] `sys_memory_used` - Used memory in GB (Sensor, diagnostic)
+    - [x] `sys_disk_percent` - Disk usage percentage (Sensor, diagnostic)
+    - [x] `sys_disk_free` - Free disk space in GB (Sensor, diagnostic)
+    - [x] `sys_uptime` - System uptime in hours (Sensor, diagnostic)
+    - [x] `sys_process_cpu` - This process CPU usage (Sensor, diagnostic)
+    - [x] `sys_process_memory` - This process memory in MB (Sensor, diagnostic)
+
+---
+
+## 棣冨竴 Current Runtime Entity Coverage
+
+**Total Completed: See runtime registry (count evolves with releases)**
+- Phase 1: 10 entities (status, zero-config runtime switches, volume)
+- Phase 2: runtime state entities only (`services_suspended`; sleep entities removed)
+- Phase 3: 9 entities (Pose control)
+- Phase 4: 3 entities (Gaze control)
+- Phase 5: 3 entities (DOA sensors and tracking switch)
+- Phase 6: 7 entities (Diagnostic information)
+- Phase 7: 7 entities (IMU sensors)
+- Phase 8: 1 entity (Emotion control)
+- Phase 10: 1 entity (Camera)
+- Phase 11: 0 entities (LED control - Disabled)
+- Phase 13: 1 entity (Sendspin toggle)
+- Phase 21: 1 entity (Continuous conversation)
+- Phase 22: 2 entities (Gesture detection)
+- Phase 23: 1 entity (Face detection)
+- Phase 24: 9 entities (System diagnostics)
+
+
+---
+
+## 棣冩畬 Voice Assistant Enhancement Features Implementation Status
+
+### Phase 14 - Emotion and Motion Feedback 閴?
+**Current Status**: Manual emotion playback and non-blocking motion feedback are implemented. Automatic keyword-based emotion triggering is currently disabled in the runtime.
+
+**Implemented Features**:
+- 閴?Phase 8 Emotion Selector entity (`emotion`)
+- 閴?`_play_emotion()` queues emotion moves through `MovementManager`
+- 閴?Wake/listen/think/speak/idle motion transitions are non-blocking
+- 閴?Timer-finished motion feedback is implemented
+- 閴?Gesture detection publishes recognized gesture label and confidence to Home Assistant entities
+- 閴?Voice phases and HA state reactions share one built-in behavior dispatcher
+
+**Current Behavior**:
+
+| Voice Assistant Event | Actual Action | Implementation Status |
+|----------------------|---------------|----------------------|
+| Wake word detected | Turn toward sound source + listening pose | 閴?Implemented |
+| Listening | Attentive listening state | 閴?Implemented |
+| Thinking | Thinking state animation | 閴?Implemented |
+| Speaking | Speech-reactive motion | 閴?Implemented |
+| Timer completed | Alert shake motion | 閴?Implemented |
+| Manual emotion trigger | Play via ESPHome `emotion` entity | 閴?Implemented |
+
+**Deliberately Not Active In Runtime**:
+- Automatic emotion keyword detection from assistant text
+- Blocking full-action choreography during conversation
+- Dance/personalization layers that require user configuration
+
+**Manual Emotion Trigger Example**:
+```yaml
+# Home Assistant automation example - Manual emotion trigger
+automation:
+  - alias: "Reachy Good Morning Greeting"
+    trigger:
+      - platform: time
+        at: "07:00:00"
+    action:
+      - service: select.select_option
+        target:
+          entity_id: select.reachy_mini_emotion
+        data:
+          option: "Happy"
+```
+
+### Phase 15 - Face Tracking (Complements DOA Turn-to-Sound) 閴?**Completed**
+
+**Goal**: Implement natural face tracking so robot looks at speaker during conversation.
+
+**Design Decision**:
+- 閴?DOA (Direction of Arrival): Used once at wakeup to turn toward sound source
+- 閴?YOLO face detection: Takes over after initial turn for continuous tracking
+- 閴?Body follows head rotation: Body yaw automatically syncs with head yaw for natural tracking
+- Reason: DOA provides quick initial orientation, face tracking provides accurate continuous tracking, body following enables natural whole-body tracking similar to human behavior
+
+**Wakeup Turn-to-Sound Flow**:
+1. Wake word detected 閳?Read DOA angle once (avoid daemon pressure)
+2. If DOA angle > 10鎺? Turn head toward sound source (80% of angle, conservative)
+3. Face tracking takes over for continuous tracking during conversation
+
+**Implemented Features**:
+
+| Feature | Description | Implementation Location | Status |
+|---------|-------------|------------------------|--------|
+| DOA turn-to-sound | Turn toward speaker at wakeup | `protocol/satellite.py:_turn_to_sound_source()` | 閴?Implemented |
+| YOLO face detection | Uses `AdamCodd/YOLOv11n-face-detection` model | `vision/head_tracker.py` | 閴?Implemented |
+| Adaptive frame rate tracking | 15fps during conversation, 2fps when idle without face | `camera_server.py` | 閴?Implemented |
+| look_at_image() | Calculate target pose from face position | `camera_server.py` | 閴?Implemented |
+| Smooth return to neutral | Smooth return within 1 second after face lost | `camera_server.py` | 閴?Implemented |
+| face_tracking_offsets | As secondary pose overlay to motion control | `movement_manager.py` | 閴?Implemented |
+| Body follows head rotation | Body yaw syncs with head yaw extracted from final pose matrix | `motion/movement_manager.py:_compose_final_pose()` | 閴?Implemented (v0.8.3) |
+| DOA entities | `doa_angle` and `speech_detected` exposed to Home Assistant | `entity_registry.py` | 閴?Implemented |
+| face_detected entity | Binary sensor for face detection state | `entity_registry.py` | 閴?Implemented |
+| Model download retry | 3 retries, 5 second interval | `head_tracker.py` | 閴?Implemented |
+| Conversation mode integration | Auto-switch tracking frequency on voice assistant state change | `satellite.py` | 閴?Implemented |
+
+**Resource Optimization (v0.5.1, updated v0.6.2)**:
+- During conversation (listening/thinking/speaking): High-frequency tracking 15fps
+- Idle with face detected: High-frequency tracking 15fps
+- Idle without face for 5s: Low-power mode 2fps
+- Idle without face for 30s: Ultra-low power mode 0.5fps (every 2 seconds)
+- Gesture detection is switch-controlled and can run independently of face tracking
+- Immediately restore high-frequency tracking when face detected
+
+**Code Locations**:
+- `protocol/satellite.py:_turn_to_sound_source()` - DOA turn-to-sound at wakeup
+- `vision/head_tracker.py` - YOLO face detector (`HeadTracker` class)
+- `vision/camera_server.py:_capture_frames()` - Adaptive frame rate face tracking
+- `vision/camera_server.py:set_conversation_mode()` - Conversation mode switch API
+- `protocol/satellite.py:_set_conversation_mode()` - Voice assistant state integration
+- `motion/movement_manager.py:set_face_tracking_offsets()` - Face tracking offset API
+- `motion/movement_manager.py:_compose_final_pose()` - Body yaw follows head yaw (v0.8.3)
+
+**Technical Details**:
+```python
+# vision/camera_server.py - Adaptive frame rate face tracking
+class MJPEGCameraServer:
+    def __init__(self):
+        self._fps_high = 15  # During conversation/face detected
+        self._fps_low = 2    # Idle without face (5-30s)
+        self._fps_idle = 0.5 # Ultra-low power (>30s without face)
+        self._low_power_threshold = 5.0   # 5s without face switches to low power
+        self._idle_threshold = 30.0       # 30s without face switches to idle mode
+
+    def _should_run_ai_inference(self, current_time):
+        # Conversation mode: Always high-frequency tracking
+        if self._in_conversation:
+            return True
+        # High-frequency mode: Track every frame
+        if self._current_fps == self._fps_high:
+            return True
+        # Low/idle power mode: Periodic detection
+        return time.since_last_check >= 1/self._current_fps
+
+# protocol/satellite.py - Voice assistant state integration
+def _reachy_on_listening(self):
+    self._set_conversation_mode(True)  # Start conversation, high-frequency tracking
+
+def _reachy_on_idle(self):
+    self._set_conversation_mode(False)  # End conversation, adaptive tracking
+
+# motion/movement_manager.py - Body follows head rotation (v0.8.3)
+# This enables natural body rotation when tracking faces, similar to how
+# the reference project's sweep_look tool synchronizes body_yaw with head_yaw.
+def _compose_final_pose(self) -> Tuple[np.ndarray, Tuple[float, float], float]:
+    # ... compose head pose from all motion sources ...
+
+    # Extract yaw from final head pose rotation matrix
+    # The rotation matrix uses xyz euler convention
+    final_rotation = R.from_matrix(final_head[:3, :3])
+    _, _, final_head_yaw = final_rotation.as_euler('xyz')
+
+    # Body follows head yaw directly
+    # SDK's automatic_body_yaw (inverse_kinematics_safe) only handles collision
+    # prevention by clamping relative angle to max 65鎺? not active following
+    body_yaw = final_head_yaw
+
+    return final_head, (antenna_right, antenna_left), body_yaw
+```
+
+**Body Following Head Rotation (v0.8.3)**:
+- SDK's `automatic_body_yaw` is only **collision protection**, not active body following
+- The `inverse_kinematics_safe` function with `max_relative_yaw=65鎺砢 only prevents head-body collision
+- To enable natural body following, `body_yaw` must be explicitly set to match `head_yaw`
+- Body yaw is extracted from final head pose matrix using scipy's `R.from_matrix().as_euler('xyz')`
+- This matches the reference project's `sweep_look.py` behavior where `target_body_yaw = head_yaw`
+
+
+### Phase 16 - Cartoon Style Motion Mode (Partial) 棣冪厸
+
+**Goal**: Use SDK interpolation techniques for more expressive robot movements.
+
+**SDK Support**: `InterpolationTechnique` enum
+- `LINEAR` - Linear, mechanical feel
+- `MIN_JERK` - Minimum jerk, natural and smooth (default)
+- `EASE_IN_OUT` - Ease in-out, elegant
+- `CARTOON` - Cartoon style, with bounce effect, lively and cute
+
+**Implemented Features**:
+- 閴?50Hz unified control loop (`motion/movement_manager.py`) - Current stable frequency
+- 閴?JSON-driven animation system (`AnimationPlayer`) - Inspired by SimpleDances project
+- 閴?Conversation state animations (idle/listening/thinking/speaking)
+- 閴?Pose change detection - Only send commands on significant changes (threshold 0.005)
+- 閴?State query caching - 2s TTL, reduces daemon load
+- 閴?Smooth interpolation (ease in-out curve)
+- 閴?Command queue mode - Thread-safe external API
+- 閴?Error throttling - Prevents log explosion
+- 閴?Connection health monitoring - Auto-detect and recover from connection loss
+
+**Animation System (v0.5.13)**:
+- `AnimationPlayer` class loads animations from `conversation_animations.json`
+- Each animation defines: pitch/yaw/roll amplitudes, position offsets, antenna movements, frequency
+- Smooth transitions between animations (configurable duration)
+- State-to-animation mapping: idle閳姕dle, listening閳姡istening, thinking閳姲hinking, speaking閳姱peaking
+
+**Not Implemented**:
+- 閴?Dynamic interpolation technique switching (CARTOON/EASE_IN_OUT etc.)
+- 閴?Exaggerated cartoon bounce effects
+
+**Code Locations**:
+- `motion/animation_player.py` - AnimationPlayer class
+- `animations/conversation_animations.json` - Animation definitions
+- `motion/movement_manager.py` - 50Hz control loop with animation integration
+
+**Scene Implementation Status**:
+
+| Scene | Recommended Interpolation | Effect | Status |
+|-------|--------------------------|--------|--------|
+| Wake nod | `CARTOON` | Lively bounce effect | 閴?Not implemented |
+| Thinking head up | `EASE_IN_OUT` | Elegant transition | 閴?Implemented (smooth interpolation) |
+| Speaking micro-movements | `MIN_JERK` | Natural and fluid | 閴?Implemented (SpeechSway) |
+| Error head shake | `CARTOON` | Exaggerated denial | 閴?Not implemented |
+| Return to neutral | `MIN_JERK` | Smooth return | 閴?Implemented |
+| Idle breathing | - | Subtle sense of life | 閴?Implemented (BreathingAnimation) |
+
+### Phase 17 - Antenna Sync Animation During Speech (Completed) 閴?
+**Goal**: Antennas sway with audio rhythm during TTS playback, simulating "speaking" effect.
+
+**Implemented Features**:
+- 閴?JSON-driven animation system with antenna movements
+- 閴?Different antenna patterns: "both" (sync), "wiggle" (opposite phase)
+- 閴?State-specific antenna animations (listening/thinking/speaking)
+- 閴?Smooth transitions between animation states
+- 閴?v1.0.0 idle refinement: idle antenna sway disabled while conversation-state antenna behaviors are retained
+- 閴?v1.0.0 hardware refinement: antenna torque disabled in `IDLE` to reduce idle chatter/noise
+
+**Code Locations**:
+- `motion/animation_player.py` - AnimationPlayer with antenna offset calculation
+- `animations/conversation_animations.json` - Antenna amplitude and pattern definitions
+- `motion/movement_manager.py` - Antenna offset composition in final pose
+
+### Phase 18 - Visual Gaze Interaction (Single-face only) 閴?
+**Goal**: Use camera to detect faces for eye contact.
+
+**SDK Support**:
+- `look_at_image(u, v)` - Look at point in image
+- `look_at_world(x, y, z)` - Look at world coordinate point
+- `media.get_frame()` - Get camera frame (閴?Already implemented in `vision/camera_server.py:146`)
+
+**Current Status**:
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| Face detection | YOLO-based face detection (`AdamCodd/YOLOv11n-face-detection`) | 閴?Implemented |
+| Eye tracking | Robot tracks detected face during conversation/active mode | 閴?Implemented |
+| Idle scanning | Random look-around in idle cycles (switch-controlled) | 閴?Implemented |
+
+> Scope note: Current implementation is intentionally single-face tracking for stability and device performance.
+
+### Phase 19 - Gravity Compensation Interactive Mode (Historical / Not Current Target)
+
+This was an exploration direction for manual teaching workflows.
+
+**Current Runtime Position**:
+- The zero-config runtime does not depend on a teaching flow
+- No user-facing teaching interaction is exposed as a core feature
+- If gravity-compensation support is revisited, it should remain optional and not become a required setup path
+
+### Phase 20 - Environment Awareness Response (Partial) 棣冪厸
+
+**Goal**: Use IMU sensors to sense environment changes and respond.
+
+**SDK Support**:
+- 閴?`mini.imu["accelerometer"]` - Accelerometer (Phase 7 implemented as entity)
+- 閴?`mini.imu["gyroscope"]` - Gyroscope (Phase 7 implemented as entity)
+
+**Implemented Features**:
+
+| Feature | Description | Status |
+|---------|-------------|--------|
+| Continuous conversation | Controlled via Home Assistant switch | 閴?Implemented |
+| IMU sensor entities | Accelerometer and gyroscope exposed to HA | 閴?Implemented |
+
+> **Note**: Tap-to-wake feature was removed in v0.5.16 due to false triggers from robot movement. Continuous conversation is now controlled via Home Assistant switch.
+
+**Not Implemented**:
+
+| Detection Event | Response Action | Status |
+|-----------------|-----------------|--------|
+| Being shaken | Play dizzy action + voice "Don't shake me~" | 閴?Not implemented |
+| Tilted/fallen | Play help action + voice "I fell, help me" | 閴?Not implemented |
+| Long idle | Enter sleep animation | 閴?Not implemented |
+
+### Phase 21 - Home Assistant Orchestration Scope
+
+The current runtime already exposes the main zero-config controls needed by Home Assistant:
+
+- `services_suspended`
+- `idle_behavior_enabled`
+- `continuous_conversation`
+- `emotion`
+- gesture / face / diagnostic sensors
+
+More elaborate scene orchestration remains intentionally outside the core runtime scope unless it can be delivered without introducing user configuration burden.
+
+
+---
+
+## 棣冩惓 Feature Implementation Summary
+
+### 閴?Completed Features
+
+#### Core Voice Assistant (Phase 1-12)
+- **ESPHome entities** - Core phases implemented (Phase 11 LED intentionally disabled); exact count evolves by release
+- **Basic voice interaction** - Wake word detection (microWakeWord/openWakeWord), STT/TTS integration
+- **Motion feedback** - Nod, shake, gaze and other basic actions
+- **Audio path** - local wake word / stop word detection plus HA-managed STT/TTS
+- **Camera stream** - MJPEG live preview with ESPHome Camera entity
+
+#### Extended Features (Phase 13-22)
+- **Phase 13** 閴?- Sendspin multi-room audio support
+- **Phase 14** 閴?- Manual emotion playback + non-blocking motion feedback
+- **Phase 15** 閴?- Face tracking with body following (DOA + YOLO + body_yaw sync)
+- **Phase 16** 閴?- JSON-driven animation system (50Hz control loop)
+- **Phase 17** 閴?- Antenna sync animation during speech
+- **Phase 22** 閴?- Gesture detection (HaGRID ONNX, 18 gestures)
+
+### 棣冪厸 Partially Implemented Features
+
+- **Phase 20** - IMU sensor entities are exposed; higher-level trigger logic is intentionally minimal
+
+### 閴?Not Implemented Features
+
+- Zero-config scene orchestration beyond the provided runtime switches and blueprint defaults
+
+---
+
+## Feature Priority Summary (Updated v1.0.6)
+
+### Completed 鉁?
+- 鉁?**Phase 1-12**: Core ESPHome entities and voice assistant
+- 鉁?**Phase 13**: Sendspin audio playback
+- 鉁?**Phase 14**: Emotion playback and motion feedback
+- 鉁?**Phase 15**: Face tracking with body following
+- 鉁?**Phase 16**: JSON-driven animation system
+- 鉁?**Phase 17**: Antenna sync animation + v1.0.0 idle antenna behavior refinements
+- 鉁?**Phase 21**: Continuous conversation switch
+- 鉁?**Phase 22**: Gesture detection
+- 鉁?**Phase 23**: Face detection sensor
+- 鉁?**Phase 24**: System diagnostics entities
+
+### Partial 棣冪厸
+- 棣冪厸 **Phase 20**: Environment awareness (IMU entities done, triggers pending)
+
+### Not Implemented 閴?- 閴?Zero-config scene orchestration layer beyond current runtime behavior
+
+---
+
+## 棣冩惐 Completion Statistics
+
+| Phase | Status | Completion | Notes |
+|-------|--------|------------|-------|
+| Phase 1-12 | 閴?Complete | 100% | Core ESPHome entities implemented (Phase 11 LED intentionally disabled) |
+| Phase 13 | 閴?Complete | 100% | Sendspin audio playback support |
+| Phase 14 | 閴?Complete | 100% | Manual emotion playback and non-blocking motion feedback |
+| Phase 15 | 閴?Complete | 100% | Face tracking with DOA, YOLO detection, body follows head |
+| Phase 16 | 閴?Complete | 100% | JSON-driven animation system (50Hz control loop) |
+| Phase 17 | 閴?Complete | 100% | Antenna sync animation during speech |
+| Phase 18 | 閴?Complete | 100% | Single-face visual gaze interaction with idle scanning |
+| Phase 19 | Not a current runtime target | - | Historical planning item, not part of the zero-config runtime model |
+| Phase 20 | 馃煛 Partial | 30% | IMU sensors exposed, missing trigger logic |
+| Phase 21 | 鉁?Complete | 100% | Continuous conversation switch implemented |
+| Phase 22 | 鉁?Complete | 100% | Gesture detection with HaGRID ONNX models |
+| Phase 23 | 鉁?Complete | 100% | Face detection sensor exposed |
+| Phase 24 | 鉁?Complete | 100% | System diagnostics entities (9 sensors) |
+| **v0.9.5** | 鉁?Complete | 100% | Modular architecture refactoring |
+| **v1.0.0** | 鉁?Complete | 100% | Runtime toggles/persistence (Sendspin, face, gesture, confidence) + idle and gesture stability updates |
+
+**Overall Completion**: current zero-config runtime path is functionally complete; remaining gaps are optional orchestration ideas rather than missing core runtime features.
+
+
+---
+
+## 棣冩暋 Daemon Crash Fix (2025-01-05)
+
+### Problem Description
+During long-term operation, `reachy_mini daemon` would crash, causing robot to become unresponsive.
+
+### Root Cause
+1. **50Hz control loop** - Current stable frequency for motion control
+2. **Frequent state queries** - Every entity state read calls `get_status()`, `get_current_head_pose()` etc.
+3. **Missing change detection** - Even when pose hasn't changed, continues sending same commands
+4. **Zenoh message queue blocking** - Accumulated 150+ messages per second, daemon cannot process in time
+
+### Fix Solution
+
+#### 1. Control loop frequency (motion/movement_manager.py)
+```python
+# Evolution: 100Hz -> 20Hz -> 10Hz -> 50Hz (current)
+# Current stable frequency for production use
+CONTROL_LOOP_FREQUENCY_HZ = 50  # Current stable frequency
+```
+
+#### 2. Add pose change detection (movement_manager.py)
+```python
+# Only send commands on significant pose changes
+if self._last_sent_pose is not None:
+    max_diff = max(abs(pose[k] - self._last_sent_pose.get(k, 0.0)) for k in pose.keys())
+    if max_diff < 0.001:  # Threshold: 0.001 rad or 0.001 m
+        return  # Skip sending
+```
+
+#### 3. State query caching (reachy_controller.py)
+```python
+# Cache daemon status query results
+self._cache_ttl = 0.1  # 100ms TTL
+self._last_status_query = 0.0
+
+def _get_cached_status(self):
+    now = time.time()
+    if now - self._last_status_query < self._cache_ttl:
+        return self._state_cache.get('status')  # Use cache
+    # ... query and update cache
+```
+
+#### 4. Head pose query caching (reachy_controller.py)
+```python
+# Cache get_current_head_pose() and get_current_joint_positions() results
+def _get_cached_head_pose(self):
+    # Reuse cached results within 100ms
+```
+
+### Fix Results
+
+| Metric | Before Fix | After Fix | Improvement |
+|--------|------------|-----------|-------------|
+| Control message frequency | ~100 msg/s | ~20 msg/s | 閳?80% |
+| State query frequency | ~50 msg/s | ~5 msg/s | 閳?90% |
+| Total Zenoh messages | ~150 msg/s | ~25 msg/s | 閳?83% |
+| Daemon CPU load | Sustained high load | Normal load | Significantly reduced |
+| Expected stability | Crash within hours | Stable for days | Major improvement |
+
+### Related Files
+- `DAEMON_CRASH_FIX_PLAN.md` - Detailed fix plan and test plan
+- `movement_manager.py` - Control loop optimization
+- `reachy_controller.py` - State query caching
+
+### Future Optimization Suggestions
+1. 鈴?Dynamic frequency adjustment - 50Hz during motion, 5Hz when idle
+2. 鈴?Batch state queries - Get all states at once
+3. 鈴?Further runtime efficiency tuning after real usage profiling
+
+---
+
+## 棣冩暋 Daemon Crash Deep Fix (2026-01-07)
+
+> **Update (2026-01-30)**: Current implementation uses 50Hz control loop for stability and performance. The control loop frequency aligns with daemon backend processing capacity. The pose change threshold (0.005) and state cache TTL (2s) optimizations remain in place to reduce unnecessary Zenoh messages.
+
+### Problem Description
+During long-term operation, `reachy_mini daemon` still crashes, previous fix not thorough enough.
+
+### Root Cause Analysis
+
+Through deep analysis of SDK source code:
+
+1. **Each `set_target()` sends 3 Zenoh messages**
+   - `set_target_head_pose()` - 1 message
+   - `set_target_antenna_joint_positions()` - 1 message  
+   - `set_target_body_yaw()` - 1 message
+
+2. **Daemon control loop is 50Hz**
+   - See `reachy_mini/daemon/backend/robot/backend.py`: `control_loop_frequency = 50.0`
+   - If message send frequency exceeds 50Hz, daemon may not process in time
+
+3. **Previous 20Hz control loop still too high**
+   - 20Hz 鑴?3 messages = 60 messages/second
+   - Already exceeds daemon's 50Hz processing capacity
+
+4. **Pose change threshold too small (0.002)**
+   - Breathing animation, speech sway, face tracking continuously produce tiny changes
+   - Almost every loop triggers `set_target()`
+
+### Fix Solution
+
+#### 1. Control loop frequency history (motion/movement_manager.py)
+```python
+# Evolution: 100Hz -> 20Hz -> 10Hz -> 50Hz (current)
+# Current stable frequency for production use
+CONTROL_LOOP_FREQUENCY_HZ = 50  # Current (2026-01-30)
+```
+
+#### 2. Increase pose change threshold (movement_manager.py)
+```python
+# Increased from 0.002 to 0.005
+# 0.005 rad 閳?0.29 degrees, still smooth enough
+self._pose_change_threshold = 0.005
+```
+
+#### 3. Reduce camera/face tracking frequency (camera_server.py)
+```python
+# Reduced from 15fps to 10fps
+fps: int = 10
+```
+
+#### 4. Increase state cache TTL (reachy_controller.py)
+```python
+# Increased from 1 second to 2 seconds
+self._cache_ttl = 2.0
+```
+
+### Fix Results
+
+> **Note**: Current implementation uses 50Hz control loop as of 2026-01-30. The table below shows historical evolution.
+
+| Metric | Before (20Hz) | After (10Hz) | Current (50Hz) |
+|--------|---------------|--------------|-----------------|
+| Control loop frequency | 20 Hz | 10 Hz | 50 Hz (current) |
+| Max Zenoh messages | 60 msg/s | 30 msg/s | ~50 msg/s (optimized) |
+| Actual messages (with change detection) | ~40 msg/s | ~15 msg/s | ~30 msg/s |
+| Face tracking frequency | 15 Hz | 10 Hz | Adaptive (2-15 Hz) |
+| State cache TTL | 1 second | 2 seconds | 2 seconds |
+| Expected stability | Crash within hours | Stable operation | Stable (daemon updated) |
+
+### Key Finding
+
+Current implementation uses 50Hz control loop for stability and performance. The control loop frequency aligns with daemon backend processing capacity.
+
+### Related Files
+- `motion/movement_manager.py` - Control loop frequency and pose threshold
+- `vision/camera_server.py` - Face tracking frequency
+- `reachy_controller.py` - State cache TTL
+
+
+---
+
+## 棣冩暋 Microphone Sensitivity Optimization (2026-01-07)
+
+> Historical background only. These notes describe earlier low-level microphone tuning experiments and should not be read as current Home Assistant entity capabilities.
+
+### Problem
+Low microphone sensitivity - Need to be very close for voice recognition.
+
+### Solution
+Comprehensive ReSpeaker XVF3800 microphone optimization:
+
+| Parameter | Default | Optimized | Notes |
+|-----------|---------|-----------|-------|
+| AGC | Off | On | Auto volume normalization |
+| AGC max gain | ~15dB | 30dB | Better distant speech pickup |
+| AGC target level | -25dB | -18dB | Stronger output signal |
+| Microphone gain | 1.0x | 2.0x | Base gain doubled |
+| Noise suppression | ~0.5 | 0.15 | Reduced speech mis-suppression |
+
+### Result
+Microphone sensitivity improved from ~30cm to ~2-3m effective range.
+
+---
+
+## 棣冩暋 v0.5.1 Bug Fixes (2026-01-08)
+
+### Issue 1: Music Not Resuming After Voice Conversation
+
+**Fix**: Sendspin now connects to `music_player` instead of `tts_player`
+
+### Issue 2: Audio Conflict During Voice Assistant Wakeup
+
+**Fix**: Added `pause_sendspin()` and `resume_sendspin()` methods to `audio/audio_player.py`
+
+### Issue 3: Sendspin Sample Rate Optimization
+
+**Fix**: Prioritize 16kHz in Sendspin supported formats (hardware limitation)
+
+---
+
+## 棣冩暋 v0.5.15 Updates (2026-01-11)
+
+### Feature 1: Audio Settings Persistence
+
+Historical note: older audio processing preferences were once persisted here. The current app no longer exposes AGC or noise suppression entities.
+
+### Feature 2: Sendspin Discovery Refactoring
+
+Moved mDNS discovery to `zeroconf.py` for better separation of concerns.
+
+
+---
+
+### SDK Data Structure Reference
+
+```python
+# Motor control mode
+class MotorControlMode(str, Enum):
+    Enabled = "enabled"              # Torque on, position control
+    Disabled = "disabled"            # Torque off
+    GravityCompensation = "gravity_compensation"  # Gravity compensation mode
+
+# Daemon state
+class DaemonState(Enum):
+    NOT_INITIALIZED = "not_initialized"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    ERROR = "error"
+
+# Full state
+class FullState:
+    control_mode: MotorControlMode
+    head_pose: XYZRPYPose  # x, y, z (m), roll, pitch, yaw (rad)
+    head_joints: list[float]  # 7 joint angles
+    body_yaw: float
+    antennas_position: list[float]  # [right, left]
+    doa: DoAInfo  # angle (rad), speech_detected (bool)
+
+# IMU data (wireless version only)
+imu_data = {
+    "accelerometer": [x, y, z],  # m/s铏?
+    "gyroscope": [x, y, z],      # rad/s
+    "quaternion": [w, x, y, z],  # Attitude quaternion
+    "temperature": float         # 鎺矯
+}
+
+# Safety limits
+HEAD_PITCH_ROLL_LIMIT = [-40鎺? +40鎺砞
+HEAD_YAW_LIMIT = [-180鎺? +180鎺砞
+BODY_YAW_LIMIT = [-160鎺? +160鎺砞
+YAW_DELTA_MAX = 65鎺? # Max difference between head and body yaw
+```
+
+### ESPHome Protocol Implementation Notes
+
+ESPHome protocol communicates with Home Assistant via protobuf messages. The runtime primarily uses switch/number/select/sensor/binary_sensor/text_sensor/camera entities; button-only wake/sleep flows are historical and no longer the main control model.
+
+```python
+from aioesphomeapi.api_pb2 import (
+    # Number entity (volume/angle/confidence control)
+    ListEntitiesNumberResponse,
+    NumberStateResponse,
+    NumberCommandRequest,
+
+    # Select entity (emotion)
+    ListEntitiesSelectResponse,
+    SelectStateResponse,
+    SelectCommandRequest,
+
+    # Switch entity (sleep/runtime toggles)
+    ListEntitiesSwitchResponse,
+    SwitchStateResponse,
+    SwitchCommandRequest,
+
+    # Sensor entity (numeric sensors)
+    ListEntitiesSensorResponse,
+    SensorStateResponse,
+
+    # Binary Sensor entity (boolean sensors)
+    ListEntitiesBinarySensorResponse,
+    BinarySensorStateResponse,
+
+    # Text Sensor entity (text sensors)
+    ListEntitiesTextSensorResponse,
+    TextSensorStateResponse,
+)
+```
+
+## Reference Projects
+
+- [OHF-Voice/linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant)
+- [pollen-robotics/reachy_mini](https://github.com/pollen-robotics/reachy_mini)
+- [reachy_mini_conversation_app](https://github.com/pollen-robotics/reachy_mini_conversation_app)
+- [sendspin-cli](https://github.com/Sendspin/sendspin-cli)
+- [home-assistant-voice](https://github.com/esphome/home-assistant-voice-pe/blob/dev/home-assistant-voice.yaml)
+
+---
+
+## 棣冩暋 Code Refactoring & Improvement Plan (v0.9.5)
+
+> Comprehensive improvement plan based on code analysis
+> Target Platform: Raspberry Pi CM4 (4GB RAM, 4-core CPU)
+
+### Code Size Statistics (Updated 2026-01-19)
+
+| File | Original | Current | Status |
+|------|----------|---------|--------|
+| `movement_manager.py` | 1205 | 1260 | 閳跨媴绗?Modularized but still large |
+| `voice_assistant.py` | 1097 | 1270 | 閴?Enhanced with new features |
+| `satellite.py` | 1003 | 1022 | 閴?Optimized (-2%) |
+| `camera_server.py` | 1070 | 1009 | 閴?Optimized (-6%) |
+| `reachy_controller.py` | 878 | 961 | 閴?Enhanced |
+| `entity_registry.py` | 1129 | 844 | 閴?Optimized (-25%) |
+| `audio_player.py` | 599 | 679 | 閴?Acceptable |
+| `core/service_base.py` | - | 552 | 棣冨晭 New module |
+| `entities/entity_factory.py` | - | 440 | 棣冨晭 New module |
+
+> **Optimization Notes**:
+> - `entity_registry.py`: Factory pattern refactoring reduced 285 lines
+> - `camera_server.py`: Using `FaceTrackingInterpolator` module reduced 61 lines
+> - `protocol/satellite.py`: Runtime paths are now centered on voice state handling and HA event reactions
+> - New modular architecture with 6 sub-packages: `core/`, `motion/`, `vision/`, `audio/`, `entities/`, `protocol/`
+
+### New Module List (Updated 2026-01-19)
+
+| Directory | Module | Lines | Description |
+|-----------|--------|-------|-------------|
+| `core/` | `config.py` | 454 | Centralized nested configuration |
+| `core/` | `service_base.py` | 552 | Suspend/resume service helpers + RobustOperationMixin |
+| `core/` | `system_diagnostics.py` | 250 | System diagnostics |
+| `core/` | `exceptions.py` | 68 | Custom exception classes |
+| `core/` | `util.py` | 28 | Utility functions |
+| `motion/` | `antenna.py` | - | Antenna freeze/unfreeze control |
+| `motion/` | `pose_composer.py` | - | Pose composition utilities |
+| `motion/` | `command_runtime.py` | - | Command queue handling / state transitions |
+| `motion/` | `control_runtime.py` | - | Control-loop runtime helpers |
+| `motion/` | `idle_runtime.py` | - | Idle behavior / idle rest handling |
+| `motion/` | `state_machine.py` | - | State machine definitions |
+| `motion/` | `smoothing.py` | - | Smoothing/transition algorithms |
+| `motion/` | `animation_player.py` | - | Animation player |
+| `motion/` | `emotion_moves.py` | - | Emotion moves |
+| `motion/` | `speech_sway.py` | 338 | Speech-driven head micro-movements |
+| `motion/` | `reachy_motion.py` | - | Reachy motion API |
+| `vision/` | `frame_processor.py` | 227 | Adaptive frame rate management |
+| `vision/` | `face_tracking_interpolator.py` | 253 | Face lost interpolation |
+| `vision/` | `gesture_smoother.py` | 80 | Historical gesture smoothing module; current runtime no longer depends on it |
+| `vision/` | `gesture_detector.py` | 285 | HaGRID gesture detection |
+| `vision/` | `head_tracker.py` | 367 | YOLO face detector |
+| `vision/` | `camera_server.py` | 1009 | MJPEG camera stream server facade |
+| `audio/` | `doa_tracker.py` | 206 | Direction of Arrival tracking |
+| `audio/` | `microphone.py` | 219 | Hardware audio helper / legacy tuning code |
+| `audio/` | `audio_player.py` | facade | AudioPlayer facade (split into playback/sendspin/local streaming modules) |
+| `entities/` | `entity.py` | 402 | ESPHome base entity |
+| `entities/` | `entity_factory.py` | 440 | Entity factory pattern |
+| `entities/` | `entity_keys.py` | 155 | Entity key constants |
+| `entities/` | `entity_extensions.py` | 258 | Extended entity types |
+| `entities/` | `event_emotion_mapper.py` | 351 | HA event to emotion mapping |
+| `protocol/` | `satellite.py` | 1022 | ESPHome protocol handler |
+| `protocol/` | `api_server.py` | 172 | HTTP API server |
+| `protocol/` | `zeroconf.py` | - | mDNS discovery |
+
+### Improvement Plan Status
+
+#### Phase 1: Runtime Suspend/Resume Foundation 鉁?Complete
+
+- [x] Create `core/service_base.py` - runtime suspend/resume service helpers
+- [x] All required services implement `suspend()` / `resume()` methods where needed
+- [x] Historical app-managed sleep/wake flow was later removed to align with the current SDK
+
+#### Phase 2: Code Modularization 閴?Complete
+
+- [x] Create new directory structure (`core/`, `motion/`, `audio/`, `vision/`, `entities/`)
+- [x] Extract from `movement_manager.py` 閳?`motion/antenna.py`, `motion/pose_composer.py`
+- [x] Extract from `camera_server.py` 閳?`vision/frame_processor.py`, `vision/face_tracking_interpolator.py`
+- [x] Extract from `entity_registry.py` 閳?`entities/entity_factory.py`, `entities/entity_keys.py`
+- [x] Create `core/config.py` for centralized configuration
+- [x] Ensure no circular dependencies
+
+#### Phase 3: Stability & Performance 閴?Complete
+
+- [x] Create `core/exceptions.py` - Custom exception classes
+- [x] Implement `RobustOperationMixin` - Unified error handling
+- [x] `CameraServer` implements Context Manager pattern
+- [x] Improve `CameraServer` resource cleanup
+- [x] Fix MJPEG client tracking (proper register/unregister)
+- [x] Historical health/memory monitor modules were added during earlier SDK instability periods
+- [x] Health/memory monitor modules were later removed after runtime simplification
+- [ ] Long-running stability test (24h+)
+
+#### Phase 4: Feature Enhancements 閴?Complete
+
+- [x] Historical gesture-action runtime path explored
+- [x] Gesture runtime later simplified to publish recognition results only
+- [x] Create `audio/doa_tracker.py` - DOATracker
+- [x] Implement sound source tracking with motion control integration
+- [x] Create `entities/event_emotion_mapper.py` - EventEmotionMapper
+- [x] Fold HA event behavior config into `animations/conversation_animations.json`
+- [x] Add DOA tracking toggle HA entity
+
+### SDK Compatibility Verification 閴?Passed
+
+| API Call | Status | Notes |
+|----------|--------|-------|
+| `set_target(head, antennas, body_yaw)` | 閴?| Correct usage |
+| `goto_target()` | 閴?| Correct usage |
+| `look_at_image(u: int, v: int)` | 閴?| Fixed float閳姕nt |
+| `create_head_pose(degrees=False)` | 閴?| Using radians |
+| `compose_world_offset()` | 閴?| SDK function correctly called |
+| `linear_pose_interpolation()` | 閴?| Has fallback implementation |
+| Body yaw range | 閴?| Clamped to 鍗?60鎺?|
+
+---
+
+## 棣冩暋 v0.9.5 Updates (2026-01-19)
+
+### Major Changes: Modular Architecture Refactoring
+
+The codebase has been restructured into a modular architecture with 5 sub-packages:
+
+| Package | Purpose | Key Modules |
+|---------|---------|-------------|
+| `core/` | Core infrastructure | `config.py`, `service_base.py`, `system_diagnostics.py` |
+| `motion/` | Motion control | `antenna.py`, `pose_composer.py`, `command_runtime.py`, `control_runtime.py`, `idle_runtime.py`, `smoothing.py` |
+| `vision/` | Vision processing | `frame_processor.py`, `face_tracking_interpolator.py` |
+| `audio/` | Audio processing | `microphone.py`, `doa_tracker.py` |
+| `entities/` | HA entity management | `entity_factory.py`, `entity_keys.py`, `event_emotion_mapper.py` |
+
+### New Features
+
+1. **Historical note**
+   - Earlier versions explored direct sleep/wake callbacks and polling-based state handling
+   - Current runtime no longer uses app-managed sleep/wake callbacks
+
+2. **Camera runtime evolution**
+   - Camera lifecycle was later split into dedicated runtime/processing/http helpers
+   - Current runtime can fully stop camera service when `Idle Behavior` is disabled
+
+### Audio Optimizations
+
+| Parameter | Before | After | Improvement |
+|-----------|--------|-------|-------------|
+| Audio chunk size | 1024 samples | 512 samples | 64ms 鈫?32ms latency with lower CPU load |
+| Audio loop delay | 10ms | 1ms | Faster VAD response |
+| Stereo閳墷ono | Mean of channels | First channel | Cleaner signal |
+
+### Code Quality Improvements
+
+- Removed all legacy/compatibility code
+- Centralized configuration in nested dataclasses
+- NaN/Inf cleaning in audio pipeline
+- Rotation clamping in face tracking to prevent IK collisions

README.md

@@ -0,0 +1,15 @@
+---
+title: Reachy Mini for Home Assistant
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: static
+pinned: false
+short_description: Deep integration of Reachy Mini robot with Home Assistant
+tags:
+  - reachy_mini
+  - reachy_mini_python_app
+  - reachy_mini_home_assistant
+  - home_assistant
+  - homeassistant
+---

changelog.json

@@ -0,0 +1,666 @@
+[  {
+    "version": "1.0.7",
+    "date": "2026-05-05",
+    "changes": [
+      "Build: Bump package version to 1.0.7",
+      "Change: Align audio runtime with current SDK patterns by splitting local TTS playback from Sendspin-capable music playback and moving wakeword/stopword loading into shared helpers",
+      "Change: Raise the Reachy Mini SDK baseline to reachy-mini>=1.7.1",
+      "Fix: Keep wakeup and TTS playback on the local player path while binding both local and Sendspin players to shared speech sway helpers",
+      "Fix: Synchronize Idle Behavior shutdown with ESPHome face and gesture switches plus runtime state updates",
+      "Fix: Remove obsolete runtime monitor modules that are no longer needed with the current SDK behavior",
+      "Optimize: Tighten Sendspin buffering with proactive backpressure and cleaner local queue handling"
+    ]
+  },
+  {
+    "version": "1.0.6",
+    "date": "2026-05-01",
+    "changes": [
+      "Build: Bump package version to 1.0.6",
+      "Change: Align pyproject.toml with the current Reachy Mini SDK baseline (reachy-mini>=1.7.0, Python>=3.12, zeroconf>=0.131,<1, aiohttp, websockets>=12,<16, and gstreamer-bundle==1.28.1 on non-Linux)",
+      "Change: Align Sendspin dependency with the current upstream client line via aiosendspin>=5.1,<6.0",
+      "Fix: Fetch camera snapshot frames on demand when the MJPEG cache is empty so Home Assistant camera proxy requests keep working with the Reachy Mini SDK 1.7.0 media pull model",
+      "Optimize: Stop the camera server entirely when Idle Behavior is disabled instead of only unloading vision models"
+    ]
+  },
+  {
+    "version": "1.0.5",
+    "date": "2026-04-12",
+    "changes": [
+      "Build: Bump package version to 1.0.5",
+      "Change: Remove app-managed robot sleep/wake handling because the current Reachy Mini SDK no longer allows mini apps to stay active while the robot enters sleep",
+      "Change: Limit resource suspend/resume to ESPHome-driven runtime toggles such as Home Assistant disconnect, mute, camera disable, and service recovery",
+      "Change: Align pyproject.toml runtime constraints with the current Reachy Mini reference SDK package (reachy-mini>=1.6.3, websockets>=12,<16, Python baseline >=3.10, and uv gstreamer metadata)",
+      "Remove: Delete SleepManager integration and app-side sleep/wake callback flow from the voice assistant runtime",
+      "Remove: Delete Home Assistant sleep control entities and internal robot sleep state tracking from the mini app"
+    ]
+  },
+  {
+    "version": "1.0.4",
+    "date": "2026-03-19",
+    "changes": [
+      "Build: Bump package version to 1.0.4",
+      "Fix: Align Reachy Mini integration with current SDK assumptions by removing legacy compatibility paths and private client health checks",
+      "Fix: Replace direct SDK private _respeaker access with audio_control_utils-based ReSpeaker initialization",
+      "Fix: Tighten camera and pose composition to require current SDK media/utils APIs and valid look_at_image inputs",
+      "Improve: Unify idle behavior into a single persisted Home Assistant entity and remove old idle compatibility aliases",
+      "Improve: Replace separate wake/sleep buttons with a single sleep control entity",
+      "Improve: Update Sendspin integration for current aiosendspin lifecycle, stream handling, listener cleanup, and synchronized buffering",
+      "Improve: Standardize daemon URL usage on shared config across controller, sleep manager, and daemon monitor"
+    ]
+  },
+  {
+    "version": "1.0.3",
+    "date": "2026-03-07",
+    "changes": [
+      "Build: Bump package version to 1.0.3",
+      "New: Add Idle Random Actions switch in Home Assistant with preferences persistence and startup restore",
+      "New: Add configurable idle_random_actions action presets in conversation_animations.json for centralized idle motion tuning",
+      "Fix: Remove duplicate idle_random_actions fields/methods and complete runtime control wiring in controller/entity registry/movement manager",
+      "Improve: Increase idle breathing and antenna sway cadence to 0.24Hz with wiggle antenna profile for more natural standby motion",
+      "Optimize: Remove set_target global rate limiting and unchanged-pose skip gating to continuously stream motion commands each control tick",
+      "Optimize: Remove idle antenna slew-rate limiter so antenna motion follows animation waveforms directly for reference-like smoothness"
+    ]
+  },
+  {
+    "version": "1.0.2",
+    "date": "2026-03-06",
+    "changes": [
+      "Build: Bump package version to 1.0.2",
+      "Fix: Restore idle antenna sway animation and tune idle breathing parameters to reduce perceived stiffness",
+      "Fix: Reintroduce idle anti-chatter smoothing/deadband for antenna and body updates to reduce mechanical jitter/noise",
+      "Fix: Switch sleep/wake control to daemon API (start/stop with wake_up/goto_sleep) so /api/daemon/status reflects real sleep state on SDK 1.5",
+      "Fix: Normalize daemon status parsing for SDK 1.5 object-based status responses",
+      "Fix: Remove all app-side antenna power on/off operations to avoid SDK instability and external-control conflicts",
+      "Change: Keep idle antenna behavior as animation-only control (no torque coupling)",
+      "Change: Tighten preference loading to current schema (no legacy config fallback filtering)",
+      "Fix: Sync Idle Motion toggle with Idle Antenna Motion toggle for expected behavior in ESPHome",
+      "Fix: Remove legacy app-managed audio routing hooks and rely on native SDK/system audio selection",
+      "New: Add Home Assistant blueprint for Reachy presence companion automation",
+      "Improve: Blueprint supports device-first auto-binding and richer usage instructions",
+      "Docs: Refresh landing page (index.html) with current version, GitHub source link, and new Blueprint/Auto Release capability cards",
+      "New: Add GitHub workflow to auto-create releases when pyproject/changelog version updates produce a new tag",
+      "Chore: Ignore local wiki workspace artifacts (local/) from repository tracking"
+    ]
+  },
+  {
+    "version": "1.0.1",
+    "date": "2026-03-05",
+    "changes": [
+      "Build: Bump package version to 1.0.1",
+      "Deps: Update runtime dependency baseline to reachy-mini>=1.5.0",
+      "Fix: Remove legacy Zenoh 7447 startup precheck for SDK v1.5 compatibility",
+      "Fix: Remove legacy ZError string matching from connection error handling",
+      "Fix: Adapt daemon status handling to SDK v1.5 DaemonStatus object (prevents AttributeError on status.get)",
+      "Fix: Harden stop-word handling with runtime activation/deactivation and mute-aware trigger gating",
+      "Fix: Align wakeup stream start timing with reference behavior (start microphone stream after wakeup sound)",
+      "Fix: Improve TTS streaming robustness and reduce cutoffs with retry-based audio push",
+      "Optimize: Support single-request streaming with in-memory fallback cache for one-time TTS URLs (no temp file dependency)",
+      "Optimize: Lower streaming fetch chunk size and apply unthrottled preroll for faster first audio"
+    ]
+  },
+  {
+    "version": "1.0.0",
+    "date": "2026-03-04",
+    "changes": [
+      "Build: Bump package version to 1.0.0",
+      "Deps: Require reachy-mini[gstreamer]>=1.4.1",
+      "Fix: Improve gesture responsiveness and stability (faster smoothing, min processing cadence, no-gesture alignment)",
+      "Fix: Auto-match ONNX gesture input size from model shape to prevent INVALID_ARGUMENT dimension errors",
+      "New: Add Sendspin switch in ESPHome (default OFF, persistent, runtime enable/disable)",
+      "New: Add Face Tracking and Gesture Detection switches in ESPHome (both default OFF, persistent)",
+      "New: Add Face Confidence number entity (0.0-1.0, persistent)",
+      "Optimize: Unload/reload face and gesture models when toggled off/on to save resources",
+      "Optimize: Idle behavior updated to breathing + look-around alternation, idle antenna sway disabled",
+      "Optimize: Adjust idle breathing to human-like cadence",
+      "Fix: Disable antenna torque in idle mode and re-enable outside idle to reduce chatter/noise",
+      "Fix: Harden startup against import-time failures (lazy emotion library loading and graceful Sendspin disable)",
+      "Fix: Enforce deterministic audio startup path and fail fast when microphone capture is not ready",
+      "Optimize: Make MJPEG streaming viewer-aware (skip continuous JPEG encode/push when no stream clients)",
+      "Optimize: Keep face/gesture AI processing active even when stream viewers are absent",
+      "Fix: Add on-demand /snapshot JPEG generation when no cached stream frame is available",
+      "Change: Use camera backend default FPS/resolution for stream path instead of forcing fixed 1080p/25fps"
+    ]
+  },
+  {
+    "version": "0.9.9",
+    "date": "2026-01-28",
+    "changes": [
+      "Fix: Audio buffer overflow - require Reachy Mini hardware, use only Reachy microphone with 50ms sleep",
+      "Optimize: Gesture detection sensitivity - remove all confidence filtering, return all detections to Home Assistant",
+      "Optimize: Gesture detection now runs at 1 frame interval for maximum responsiveness",
+      "Refactor: Simplify GestureSmoother to frequency-based confirmation (1 frame)",
+      "Refactor: Remove unused parameters (confidence_threshold, detection_threshold, GestureConfig)",
+      "Fix: Remove duplicate empty check in gesture detection",
+      "Optimize: SDK integration - add MediaBackend detection and proper resource cleanup",
+      "Document: ReSpeaker private attribute access risk with TODO comments"
+    ]
+  },
+  {
+    "version": "0.9.8",
+    "date": "2026-01-27",
+    "changes": [
+      "New: Mute switch and Disable Camera entities for granular control",
+      "Fix: Camera disable logic and daemon crash prevention",
+      "New: Home Assistant connection-driven feature loading with auto suspend/resume",
+      "Optimize: Reduce log output by 30-40%",
+      "Fix: Code quality improvements",
+      "Fix: SDK crash during idle - optimize audio processing and add GStreamer threading lock",
+      "Optimize: Bundle face tracking model, use SDK Zenoh for daemon monitoring",
+      "Simplify: Device ID reads /etc/machine-id directly",
+      "Clean up: Remove unused config items"
+    ]
+  },
+  {
+    "version": "0.9.7",
+    "date": "2026-01-20",
+    "changes": [
+      "Fix: Device ID file path corrected after util.py moved to core/ subdirectory (prevents HA seeing device as new)",
+      "Fix: Animation file path corrected (was looking in wrong directory)",
+      "Fix: Remove hey_jarvis from required wake words (it's optional in openWakeWord/)"
+    ]
+  },
+  {
+    "version": "0.9.6",
+    "date": "2026-01-20",
+    "changes": [
+      "New: Add ruff linter/formatter and mypy type checker configuration",
+      "New: Add pre-commit hooks for automated code quality checks",
+      "Fix: Remove duplicate resume() method in audio_player.py",
+      "Fix: Remove duplicate connection_lost() method in satellite.py",
+      "Fix: Store asyncio task reference in sleep_manager.py to prevent garbage collection",
+      "Optimize: Use dict.items() for efficient iteration in smoothing.py"
+    ]
+  },
+  {
+    "version": "0.9.5",
+    "date": "2026-01-19",
+    "changes": [
+      "Refactor: Modularize codebase - new core/motion/vision/audio/entities module structure",
+      "New: Direct callbacks for HA sleep/wake buttons to suspend/resume services",
+      "Optimize: Audio processing latency - reduced chunk size from 1024 to 256 samples (64ms -> 16ms)",
+      "Optimize: Audio loop delay reduced from 10ms to 1ms for faster VAD response",
+      "Optimize: Stereo to mono conversion uses first channel instead of mean for cleaner signal",
+      "Improve: Camera resume_from_suspend now synchronous for reliable wake from sleep",
+      "Improve: Rotation clamping in face tracking to prevent IK collisions"
+    ]
+  },
+  {
+    "version": "0.9.0",
+    "date": "2026-01-18",
+    "changes": [
+      "New: Robot state monitor for proper sleep mode handling - services pause when robot disconnects and resume on reconnect",
+      "New: System diagnostics entities (CPU, memory, disk, uptime) exposed as Home Assistant diagnostic sensors",
+      "New: Phase 24 with 9 diagnostic sensors (cpu_percent, cpu_temperature, memory_percent, memory_used_gb, disk_percent, disk_free_gb, uptime_hours, process_cpu_percent, process_memory_mb)",
+      "Fix: Voice assistant and movement manager now properly pause during robot sleep mode instead of generating error spam",
+      "Improve: Graceful service lifecycle management with RobotStateMonitor callbacks"
+    ]
+  },
+  {
+    "version": "0.8.7",
+    "date": "2026-01-18",
+    "changes": [
+      "Fix: Clamp body_yaw to safe range to prevent IK collision warnings during emotion playback",
+      "Fix: Emotion moves and face tracking now respect SDK safety limits",
+      "Improve: Face tracking smoothness - removed EMA smoothing (matches reference project)",
+      "Improve: Face tracking timing updated to match reference (2s delay, 1s interpolation)"
+    ]
+  },
+  {
+    "version": "0.8.6",
+    "date": "2026-01-18",
+    "changes": [
+      "Fix: Audio buffer memory leak - added size limit to prevent unbounded growth",
+      "Fix: Temp file leak - downloaded audio files now cleaned up after playback",
+      "Fix: Camera thread termination timeout increased for clean shutdown",
+      "Fix: Thread-safe draining flag using threading.Event",
+      "Fix: Silent failures now logged for debugging"
+    ]
+  },
+  {
+    "version": "0.8.5",
+    "date": "2026-01-18",
+    "changes": [
+      "Fix: DOA turn-to-sound direction inverted - now turns correctly toward sound source",
+      "Fix: Graceful shutdown prevents daemon crash on app stop"
+    ]
+  },
+  {
+    "version": "0.8.4",
+    "date": "2026-01-18",
+    "changes": [
+      "Improve: Smooth idle animation with interpolation phase (matches reference BreathingMove)",
+      "Improve: Two-phase animation - interpolates to neutral before oscillation",
+      "Fix: Antenna frequency updated to 0.5Hz (was 0.15Hz) for more natural sway"
+    ]
+  },
+  {
+    "version": "0.8.3",
+    "date": "2026-01-18",
+    "changes": [
+      "Fix: Body now properly follows head rotation during face tracking",
+      "Fix: body_yaw extracted from final head pose matrix and synced with head_yaw",
+      "Fix: Matches reference project sweep_look behavior for natural body movement"
+    ]
+  },
+  {
+    "version": "0.8.2",
+    "date": "2026-01-18",
+    "changes": [
+      "Fix: Body now follows head rotation during face tracking - body_yaw syncs with head_yaw",
+      "Fix: Matches reference project sweep_look behavior for natural body movement"
+    ]
+  },
+  {
+    "version": "0.8.1",
+    "date": "2026-01-18",
+    "changes": [
+      "Fix: face_detected entity now pushes state updates to Home Assistant in real-time",
+      "Fix: Body yaw simplified to match reference project - SDK automatic_body_yaw handles collision prevention",
+      "Fix: Idle animation now starts immediately on app launch",
+      "Fix: Smooth antenna animation - removed pose change threshold for continuous motion"
+    ]
+  },
+  {
+    "version": "0.8.0",
+    "date": "2026-01-17",
+    "changes": [
+      "New: Comprehensive emotion keyword mapping with 280+ Chinese and English keywords",
+      "New: 35 emotion categories mapped to robot expressions",
+      "New: Auto-trigger expressions from conversation text patterns"
+    ]
+  },
+  {
+    "version": "0.7.3",
+    "date": "2026-01-12",
+    "changes": [
+      "Fix: Revert to reference project pattern - use refractory period instead of state flags",
+      "Fix: Remove broken _in_pipeline and _tts_playing state management",
+      "Fix: Restore correct RUN_END event handling from linux-voice-assistant"
+    ]
+  },
+  {
+    "version": "0.7.2",
+    "date": "2026-01-12",
+    "changes": [
+      "Fix: Remove premature _tts_played reset in RUN_END event",
+      "Fix: Ensure _in_pipeline stays True until TTS playback completes"
+    ]
+  },
+  {
+    "version": "0.7.1",
+    "date": "2026-01-12",
+    "changes": [
+      "Fix: Prevent wake word detection during TTS playback",
+      "Fix: Add _tts_playing flag to track TTS audio state precisely"
+    ]
+  },
+  {
+    "version": "0.7.0",
+    "date": "2026-01-12",
+    "changes": [
+      "New: Gesture detection using HaGRID ONNX models (18 gesture classes)",
+      "New: gesture_detected and gesture_confidence entities in Home Assistant",
+      "Fix: Gesture state now properly pushed to Home Assistant in real-time",
+      "Optimize: Aggressive power saving - 0.5fps idle mode after 30s without face",
+      "Optimize: Gesture detection only runs when face detected (saves CPU)"
+    ]
+  },
+  {
+    "version": "0.6.1",
+    "date": "2026-01-12",
+    "changes": [
+      "Fix: Prioritize MicroWakeWord over OpenWakeWord for same-name wake words",
+      "Fix: OpenWakeWord wake words now visible in Home Assistant selection",
+      "Fix: Stop word detection now works correctly",
+      "Fix: STT/LLM response time improved with fixed audio chunk size"
+    ]
+  },
+  {
+    "version": "0.6.0",
+    "date": "2026-01-11",
+    "changes": [
+      "New: Real-time audio-driven speech animation (SwayRollRT algorithm)",
+      "New: JSON-driven animation system - all animations configurable",
+      "Refactor: Remove hardcoded actions, use animation offsets only",
+      "Fix: TTS audio analysis now works with local playback"
+    ]
+  },
+  {
+    "version": "0.5.16",
+    "date": "2026-01-11",
+    "changes": [
+      "Remove: Tap-to-wake feature (too many false triggers)",
+      "New: Continuous Conversation switch in Home Assistant",
+      "Refactor: Simplified satellite.py and voice_assistant.py"
+    ]
+  },
+  {
+    "version": "0.5.15",
+    "date": "2026-01-11",
+    "changes": [
+      "New: Audio settings persistence (AGC, Noise Suppression, Tap Sensitivity)",
+      "Refactor: Move Sendspin mDNS discovery to zeroconf.py",
+      "Fix: Tap detection not re-enabled during emotion playback in conversation"
+    ]
+  },
+  {
+    "version": "0.5.14",
+    "date": "2026-01-11",
+    "changes": [
+      "Fix: Skip ALL wake word processing when pipeline is active",
+      "Fix: Eliminate race condition in pipeline state during continuous conversation",
+      "Improve: Control loop increased to 100Hz (daemon updated)"
+    ]
+  },
+  {
+    "version": "0.5.13",
+    "date": "2026-01-10",
+    "changes": [
+      "New: JSON-driven animation system for conversation states",
+      "New: AnimationPlayer class inspired by SimpleDances project",
+      "Refactor: Replace SpeechSwayGenerator and BreathingAnimation with unified animation system"
+    ]
+  },
+  {
+    "version": "0.5.12",
+    "date": "2026-01-10",
+    "changes": [
+      "Remove: Deleted broken hey_reachy wake word model",
+      "Revert: Default wake word back to \"Okay Nabu\""
+    ]
+  },
+  {
+    "version": "0.5.11",
+    "date": "2026-01-10",
+    "changes": [
+      "Fix: Reset feature extractors when switching wake words",
+      "Fix: Add refractory period after wake word switch"
+    ]
+  },
+  {
+    "version": "0.5.10",
+    "date": "2026-01-10",
+    "changes": [
+      "Fix: Wake word models now have 'id' attribute set correctly",
+      "Fix: Wake word switching from Home Assistant now works"
+    ]
+  },
+  {
+    "version": "0.5.9",
+    "date": "2026-01-10",
+    "changes": [
+      "New: Default wake word changed to hey_reachy",
+      "Fix: Wake word switching bug"
+    ]
+  },
+  {
+    "version": "0.5.8",
+    "date": "2026-01-09",
+    "changes": [
+      "Fix: Tap detection waits for emotion playback to complete",
+      "Fix: Poll daemon API for move completion"
+    ]
+  },
+  {
+    "version": "0.5.7",
+    "date": "2026-01-09",
+    "changes": [
+      "New: DOA turn-to-sound at wakeup",
+      "Fix: Show raw DOA angle in Home Assistant (0-180)",
+      "Fix: Invert DOA yaw direction"
+    ]
+  },
+  {
+    "version": "0.5.6",
+    "date": "2026-01-08",
+    "changes": [
+      "Fix: Better pipeline state tracking to prevent duplicate audio"
+    ]
+  },
+  {
+    "version": "0.5.5",
+    "date": "2026-01-08",
+    "changes": [
+      "Fix: Prevent concurrent pipelines",
+      "New: Add prompt sound for continuous conversation"
+    ]
+  },
+  {
+    "version": "0.5.4",
+    "date": "2026-01-08",
+    "changes": [
+      "Fix: Wait for RUN_END before starting new conversation"
+    ]
+  },
+  {
+    "version": "0.5.3",
+    "date": "2026-01-08",
+    "changes": [
+      "Fix: Improve continuous conversation with conversation_id tracking"
+    ]
+  },
+  {
+    "version": "0.5.2",
+    "date": "2026-01-08",
+    "changes": [
+      "Fix: Enable HA control of robot pose",
+      "Fix: Continuous conversation improvements"
+    ]
+  },
+  {
+    "version": "0.5.1",
+    "date": "2026-01-08",
+    "changes": [
+      "Fix: Sendspin connects to music_player instead of tts_player",
+      "Fix: Persist tap_sensitivity settings",
+      "Fix: Pause Sendspin during voice assistant wakeup",
+      "Fix: Sendspin prioritize 16kHz sample rate"
+    ]
+  },
+  {
+    "version": "0.5.0",
+    "date": "2026-01-07",
+    "changes": [
+      "New: Face tracking with adaptive frequency",
+      "New: Sendspin multi-room audio integration",
+      "Optimize: Shutdown mechanism improvements"
+    ]
+  },
+  {
+    "version": "0.4.0",
+    "date": "2026-01-07",
+    "changes": [
+      "Fix: Daemon stability fixes",
+      "New: Face tracking enabled by default",
+      "Optimize: Microphone settings for better sensitivity"
+    ]
+  },
+  {
+    "version": "0.3.0",
+    "date": "2026-01-06",
+    "changes": [
+      "New: Tap sensitivity slider entity",
+      "Fix: Music Assistant compatibility",
+      "Optimize: Face tracking and tap detection"
+    ]
+  },
+  {
+    "version": "0.2.21",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: Daemon crash - reduce control loop to 2Hz",
+      "Fix: Pause control loop during audio playback"
+    ]
+  },
+  {
+    "version": "0.2.20",
+    "date": "2026-01-06",
+    "changes": [
+      "Revert: Audio/satellite/voice_assistant to v0.2.9 working state"
+    ]
+  },
+  {
+    "version": "0.2.19",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: Force localhost connection mode to prevent WebRTC errors"
+    ]
+  },
+  {
+    "version": "0.2.18",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: Audio playback - restore wakeup sound",
+      "Fix: Use push_audio_sample for TTS"
+    ]
+  },
+  {
+    "version": "0.2.17",
+    "date": "2026-01-06",
+    "changes": [
+      "Remove: head_joints/passive_joints entities",
+      "Move: error_message to diagnostic category"
+    ]
+  },
+  {
+    "version": "0.2.16",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: TTS playback - pause recording during playback"
+    ]
+  },
+  {
+    "version": "0.2.15",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: Use play_sound() instead of push_audio_sample() for TTS"
+    ]
+  },
+  {
+    "version": "0.2.14",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: Pause audio recording during TTS playback"
+    ]
+  },
+  {
+    "version": "0.2.13",
+    "date": "2026-01-06",
+    "changes": [
+      "Fix: Don't manually start/stop media - let SDK/daemon manage it"
+    ]
+  },
+  {
+    "version": "0.2.12",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Disable breathing animation to prevent serial port overflow"
+    ]
+  },
+  {
+    "version": "0.2.11",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Disable wakeup sound to prevent daemon crash",
+      "Add: Debug logging for troubleshooting"
+    ]
+  },
+  {
+    "version": "0.2.10",
+    "date": "2026-01-05",
+    "changes": [
+      "Add: Debug logging for motion init",
+      "Fix: Audio fallback samplerate"
+    ]
+  },
+  {
+    "version": "0.2.9",
+    "date": "2026-01-05",
+    "changes": [
+      "Remove: DOA/speech detection - replaced by face tracking"
+    ]
+  },
+  {
+    "version": "0.2.8",
+    "date": "2026-01-05",
+    "changes": [
+      "New: Replace DOA with YOLO face tracking"
+    ]
+  },
+  {
+    "version": "0.2.7",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Add DOA caching to prevent ReSpeaker query overload"
+    ]
+  },
+  {
+    "version": "0.2.6",
+    "date": "2026-01-05",
+    "changes": [
+      "New: Thread-safe ReSpeaker USB access to prevent daemon deadlock"
+    ]
+  },
+  {
+    "version": "0.2.4",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Microphone volume control via daemon HTTP API"
+    ]
+  },
+  {
+    "version": "0.2.3",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Daemon crash caused by conflicting pose commands",
+      "Disable: Pose setter methods in ReachyController"
+    ]
+  },
+  {
+    "version": "0.2.2",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Second conversation motion failure",
+      "Reduce: Control loop from 20Hz to 10Hz",
+      "Improve: Connection recovery (faster reconnect)"
+    ]
+  },
+  {
+    "version": "0.2.1",
+    "date": "2026-01-05",
+    "changes": [
+      "Fix: Daemon crash issue",
+      "Optimize: Code structure"
+    ]
+  },
+  {
+    "version": "0.2.0",
+    "date": "2026-01-05",
+    "changes": [
+      "New: Automatic facial expressions during conversation",
+      "New: Emotion playback integration",
+      "Refactor: Integrate emotion playback into MovementManager"
+    ]
+  },
+  {
+    "version": "0.1.5",
+    "date": "2026-01-04",
+    "changes": [
+      "Optimize: Code splitting and organization",
+      "Fix: Program crash issues"
+    ]
+  },
+  {
+    "version": "0.1.0",
+    "date": "2026-01-01",
+    "changes": [
+      "Initial release",
+      "ESPHome protocol server implementation",
+      "mDNS auto-discovery for Home Assistant",
+      "Local wake word detection (microWakeWord)",
+      "Voice assistant pipeline integration",
+      "Basic motion feedback (nod, shake)"
+    ]
+  }
+]
+

docs/USER_MANUAL_CN.md

@@ -0,0 +1,244 @@
+# Reachy Mini 语音助手 - 用户手册
+
+## 系统要求
+
+### 硬件
+- Reachy Mini 机器人（带 ReSpeaker XVF3800 麦克风）
+- WiFi 网络连接
+
+### 软件
+- Home Assistant（2024.1 或更高版本）
+- Home Assistant 中已启用 ESPHome 集成
+
+---
+
+## 安装步骤
+
+### 第一步：安装应用
+从 Reachy Mini 应用商店安装 `reachy_mini_home_assistant`。
+
+### 第二步：启动应用
+应用将自动：
+- 在端口 6053 启动 ESPHome 服务器
+- 加载预打包的唤醒词模型
+- 通过 mDNS 注册以便自动发现
+- 如果网络上有 Sendspin 服务器则自动连接
+
+### 第三步：连接 Home Assistant
+**自动连接（推荐）：**
+Home Assistant 会通过 mDNS 自动发现 Reachy Mini。
+
+**手动连接：**
+1. 进入 设置 → 设备与服务
+2. 点击"添加集成"
+3. 选择"ESPHome"
+4. 输入机器人的 IP 地址和端口 6053
+
+---
+
+## 功能介绍
+
+### 语音助手
+- **唤醒词检测**：说 "Okay Nabu" 激活（本地处理）
+- **停止词**：说 "Stop" 结束对话
+- **连续对话模式**：无需重复唤醒词即可持续对话
+- **语音识别/合成**：使用 Home Assistant 配置的语音引擎
+
+**支持的唤醒词：**
+- Okay Nabu（默认）
+- Hey Jarvis
+- Alexa
+- Hey Luna
+
+### 人脸追踪
+- 基于 YOLO 的人脸检测
+- 头部跟随检测到的人脸
+- 头部转动时身体随之旋转
+- 自适应帧率：活跃时 15fps，空闲时 2fps
+- 可在 Home Assistant 中运行时开关
+
+### 手势检测
+检测到的手势会作为实体状态同步到 Home Assistant。
+当前默认运行时不会直接用手势触发机器人动作。
+
+| 输出 | 说明 |
+|------|------|
+| `gesture_detected` | 当前识别到的手势标签 |
+| `gesture_confidence` | 手势识别置信度 |
+
+### 情绪响应
+机器人可播放 35 种不同情绪：
+- 基础：开心、难过、愤怒、恐惧、惊讶、厌恶
+- 扩展：大笑、爱慕、骄傲、感激、热情、好奇、惊叹、害羞、困惑、沉思、焦虑、害怕、沮丧、烦躁、狂怒、轻蔑、无聊、疲倦、精疲力竭、孤独、沮丧、顺从、不确定、不舒服
+
+### 音频功能
+- 扬声器音量控制（0-100%）
+- 静音开关，可暂停/恢复语音链路
+- 支持唤醒提示音与计时器完成提示音
+- STT/TTS 由 Home Assistant 负责
+
+### Sendspin 多房间音频
+- 通过 mDNS 自动发现 Sendspin 服务器
+- 同步多房间音频播放
+- Reachy Mini 作为 PLAYER 接收音频流
+- 语音对话时自动暂停
+- 无需用户配置
+
+### DOA 声源追踪
+- 声源方向检测
+- 唤醒时机器人转向声源
+- 可通过开关启用/禁用
+
+---
+
+## Home Assistant 实体
+
+### 阶段 1：基础状态
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Daemon State | 文本传感器 | 机器人守护进程状态 |
+| Backend Ready | 二进制传感器 | 后端连接状态 |
+| Mute | 开关 | 暂停/恢复语音链路 |
+| Speaker Volume | 数值 (0-100%) | 扬声器音量控制 |
+| Disable Camera | 开关 | 暂停/恢复摄像头服务 |
+| Idle Behavior | 开关 | 统一空闲行为：头部、天线、微动作 |
+| Sendspin | 开关 | 启用/禁用 Sendspin 发现与播放 |
+| Face Tracking | 开关 | 启用/禁用人脸跟踪 |
+| Gesture Detection | 开关 | 启用/禁用手势检测 |
+| Face Confidence | 数值 (0-1) | 人脸跟踪置信度阈值 |
+
+### 阶段 2：睡眠与运行状态
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Sleep Control | 开关 | 打开表示进入睡眠，关闭表示唤醒 |
+| Sleep Mode | 二进制传感器 | 运行中表示唤醒，非运行表示睡眠 |
+| Services Suspended | 二进制传感器 | 运行中表示服务活跃 |
+
+### 阶段 3：姿态控制
+| 实体 | 类型 | 范围 |
+|------|------|------|
+| Head X/Y/Z | 数值 | ±50mm |
+| Head Roll/Pitch/Yaw | 数值 | ±40° |
+| Body Yaw | 数值 | ±160° |
+| Antenna Left/Right | 数值 | ±90° |
+
+### 阶段 4：注视控制
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Look At X/Y/Z | 数值 | 注视目标的世界坐标 |
+
+### 阶段 5：DOA（声源定位）
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| DOA Angle | 传感器 (°) | 声源方向 |
+| Speech Detected | 二进制传感器 | 语音活动检测 |
+| DOA Sound Tracking | 开关 | 启用/禁用 DOA 追踪 |
+
+### 阶段 6：诊断信息
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Control Loop Frequency | 传感器 (Hz) | 运动控制循环频率 |
+| SDK Version | 文本传感器 | Reachy Mini SDK 版本 |
+| Robot Name | 文本传感器 | 设备名称 |
+| Wireless Version | 二进制传感器 | 无线版本标志 |
+| Simulation Mode | 二进制传感器 | 仿真模式标志 |
+| WLAN IP | 文本传感器 | WiFi IP 地址 |
+| Error Message | 文本传感器 | 当前错误 |
+
+### 阶段 7：IMU 传感器（仅无线版本）
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| IMU Accel X/Y/Z | 传感器 (m/s²) | 加速度计 |
+| IMU Gyro X/Y/Z | 传感器 (rad/s) | ���螺仪 |
+| IMU Temperature | 传感器 (°C) | IMU 温度 |
+
+### 阶段 8：情绪控制
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Emotion | 选择器 | 选择要播放的情绪（35 个选项）|
+
+### 阶段 10：摄像头
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Camera | 摄像头 | 实时 MJPEG 流 |
+
+### 3D 可视化卡片
+可在 Home Assistant 中安装自定义 Lovelace 卡片，实时 3D 可视化 Reachy Mini 机器人。
+
+安装地址：[ha-reachy-mini](https://github.com/Desmond-Dong/ha-reachy-mini)
+
+功能：
+- 实时 3D 机器人可视化
+- 交互式机器人状态视图
+- 连接机器人守护进程获取实时更新
+
+### 阶段 21：对话
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Continuous Conversation | 开关 | 多轮对话模式 |
+
+### 阶段 22：手势检测
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Gesture Detected | 文本传感器 | 当前手势名称 |
+| Gesture Confidence | 传感器 (%) | 检测置信度 |
+
+### 阶段 23：人脸检测
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| Face Detected | 二进制传感器 | 视野中是否有人脸 |
+
+### 阶段 24：系统诊断
+| 实体 | 类型 | 说明 |
+|------|------|------|
+| CPU Percent | 传感器 (%) | CPU 使用率 |
+| CPU Temperature | 传感器 (°C) | CPU 温度 |
+| Memory Percent | 传感器 (%) | 内存使用率 |
+| Memory Used | 传感器 (GB) | 已用内存 |
+| Disk Percent | 传感器 (%) | 磁盘使用率 |
+| Disk Free | 传感器 (GB) | 磁盘可用空间 |
+| Uptime | 传感器 (hours) | 系统运行时间 |
+| Process CPU | 传感器 (%) | 应用 CPU 使用率 |
+| Process Memory | 传感器 (MB) | 应用内存使用 |
+
+---
+
+## 睡眠模式
+
+运行时反应是零配置的：语音阶段、计时器提醒和 HA 状态触发情绪，共用同一套内建行为模型。
+
+### 进入睡眠
+- 在 Home Assistant 中打开 `Sleep Control` 开关
+- 机器人放松电机、停止摄像头、暂停语音检测
+
+### 唤醒
+- 在 Home Assistant 中关闭 `Sleep Control` 开关
+- 或说唤醒词
+- 机器人恢复所有功能
+
+---
+
+## 故障排除
+
+| 问题 | 解决方案 |
+|------|----------|
+| 不响应唤醒词 | 检查 Mute 是否关闭，减少背景噪音，并确认已连接 Home Assistant |
+| 人脸追踪不工作 | 确保光线充足，检查 Face Detected 传感器 |
+| 没有音频输出 | 检查 Speaker Volume，验证 HA 中的 TTS 引擎 |
+| 无法连接 HA | 确认在同一网络，检查端口 6053 |
+| 手势检测不到 | 确保光线充足，正对摄像头 |
+
+---
+
+## 快速参考
+
+```
+唤醒词：       "Okay Nabu"
+停止词：       "Stop"
+ESPHome 端口： 6053
+摄像头端口：   8081 (MJPEG)
+```
+
+---
+
+*Reachy Mini 语音助手 v1.0.4*

docs/USER_MANUAL_EN.md

@@ -0,0 +1,244 @@
+# Reachy Mini Voice Assistant - User Manual
+
+## Requirements
+
+### Hardware
+- Reachy Mini robot (with ReSpeaker XVF3800 microphone)
+- WiFi network connection
+
+### Software
+- Home Assistant (2024.1 or later)
+- ESPHome integration enabled in Home Assistant
+
+---
+
+## Installation
+
+### Step 1: Install the App
+Install `reachy_mini_home_assistant` from the Reachy Mini App Store.
+
+### Step 2: Start the App
+The app will automatically:
+- Start the ESPHome server on port 6053
+- Load pre-packaged wake word models
+- Register with mDNS for auto-discovery
+- Connect to Sendspin server if available on network
+
+### Step 3: Connect to Home Assistant
+**Automatic (Recommended):**
+Home Assistant will auto-discover Reachy Mini via mDNS.
+
+**Manual:**
+1. Go to Settings → Devices & Services
+2. Click "Add Integration"
+3. Select "ESPHome"
+4. Enter the robot's IP address and port 6053
+
+---
+
+## Features
+
+### Voice Assistant
+- **Wake Word Detection**: Say "Okay Nabu" to activate (local processing)
+- **Stop Word**: Say "Stop" to end conversation
+- **Continuous Conversation Mode**: Keep talking without repeating wake word
+- **STT/TTS**: Uses Home Assistant's configured speech engines
+
+**Supported Wake Words:**
+- Okay Nabu (default)
+- Hey Jarvis
+- Alexa
+- Hey Luna
+
+### Face Tracking
+- YOLO-based face detection
+- Head follows detected face
+- Body follows head when turned far
+- Adaptive frame rate: 15fps active, 2fps idle
+- Runtime switchable from Home Assistant
+
+### Gesture Detection
+Detected gestures are published to Home Assistant as entity state updates.
+The default runtime does not trigger built-in robot actions from gestures.
+
+| Output | Description |
+|--------|-------------|
+| `gesture_detected` | Current gesture label |
+| `gesture_confidence` | Detection confidence |
+
+### Emotion Responses
+The robot can play 35 different emotions:
+- Basic: Happy, Sad, Angry, Fear, Surprise, Disgust
+- Extended: Laughing, Loving, Proud, Grateful, Enthusiastic, Curious, Amazed, Shy, Confused, Thoughtful, Anxious, Scared, Frustrated, Irritated, Furious, Contempt, Bored, Tired, Exhausted, Lonely, Downcast, Resigned, Uncertain, Uncomfortable
+
+### Audio Features
+- Speaker volume control (0-100%)
+- Mute switch for voice pipeline pause/resume
+- Wake sound and timer-finished sound playback
+- Home Assistant handles STT/TTS engines
+
+### Sendspin Multi-Room Audio
+- Automatic discovery of Sendspin servers via mDNS
+- Synchronized multi-room audio playback
+- Reachy Mini acts as a PLAYER to receive audio streams
+- Auto-pause during voice conversations
+- No user configuration required
+
+### DOA Sound Tracking
+- Direction of Arrival detection
+- Robot turns toward sound source on wake word
+- Can be enabled/disabled via switch
+
+---
+
+## Home Assistant Entities
+
+### Phase 1: Basic Status
+| Entity | Type | Description |
+|--------|------|-------------|
+| Daemon State | Text Sensor | Robot daemon status |
+| Backend Ready | Binary Sensor | Backend connection status |
+| Mute | Switch | Suspend/resume voice pipeline |
+| Speaker Volume | Number (0-100%) | Speaker volume control |
+| Disable Camera | Switch | Suspend/resume camera service |
+| Idle Behavior | Switch | Unified idle motion + idle antenna + idle micro-actions |
+| Sendspin | Switch | Enable/disable Sendspin discovery and playback |
+| Face Tracking | Switch | Enable/disable face tracking |
+| Gesture Detection | Switch | Enable/disable gesture detection |
+| Face Confidence | Number (0-1) | Face tracking confidence threshold |
+
+### Phase 2: Sleep and Runtime State
+| Entity | Type | Description |
+|--------|------|-------------|
+| Sleep Control | Switch | Turn on to sleep, turn off to wake |
+| Sleep Mode | Binary Sensor | Running when awake, not running when sleeping |
+| Services Suspended | Binary Sensor | Running when services are active |
+
+### Phase 3: Pose Control
+| Entity | Type | Range |
+|--------|------|-------|
+| Head X/Y/Z | Number | ±50mm |
+| Head Roll/Pitch/Yaw | Number | ±40° |
+| Body Yaw | Number | ±160° |
+| Antenna Left/Right | Number | ±90° |
+
+### Phase 4: Look At Control
+| Entity | Type | Description |
+|--------|------|-------------|
+| Look At X/Y/Z | Number | World coordinates for gaze target |
+
+### Phase 5: DOA (Direction of Arrival)
+| Entity | Type | Description |
+|--------|------|-------------|
+| DOA Angle | Sensor (°) | Sound source direction |
+| Speech Detected | Binary Sensor | Voice activity detection |
+| DOA Sound Tracking | Switch | Enable/disable DOA tracking |
+
+### Phase 6: Diagnostics
+| Entity | Type | Description |
+|--------|------|-------------|
+| Control Loop Frequency | Sensor (Hz) | Motion control loop rate |
+| SDK Version | Text Sensor | Reachy Mini SDK version |
+| Robot Name | Text Sensor | Device name |
+| Wireless Version | Binary Sensor | Wireless model flag |
+| Simulation Mode | Binary Sensor | Simulation flag |
+| WLAN IP | Text Sensor | WiFi IP address |
+| Error Message | Text Sensor | Current error |
+
+### Phase 7: IMU Sensors (Wireless version only)
+| Entity | Type | Description |
+|--------|------|-------------|
+| IMU Accel X/Y/Z | Sensor (m/s²) | Accelerometer |
+| IMU Gyro X/Y/Z | Sensor (rad/s) | Gyroscope |
+| IMU Temperature | Sensor (°C) | IMU temperature |
+
+### Phase 8: Emotion Control
+| Entity | Type | Description |
+|--------|------|-------------|
+| Emotion | Select | Choose emotion to play (35 options) |
+
+### Phase 10: Camera
+| Entity | Type | Description |
+|--------|------|-------------|
+| Camera | Camera | Live MJPEG stream |
+
+### 3D Visualization Card
+A custom Lovelace card is available for real-time 3D visualization of the Reachy Mini robot in Home Assistant.
+
+Install from: [ha-reachy-mini](https://github.com/Desmond-Dong/ha-reachy-mini)
+
+Features:
+- Real-time 3D robot visualization
+- Interactive view of robot state
+- Connects to robot daemon for live updates
+
+### Phase 21: Conversation
+| Entity | Type | Description |
+|--------|------|-------------|
+| Continuous Conversation | Switch | Multi-turn conversation mode |
+
+### Phase 22: Gesture Detection
+| Entity | Type | Description |
+|--------|------|-------------|
+| Gesture Detected | Text Sensor | Current gesture name |
+| Gesture Confidence | Sensor (%) | Detection confidence |
+
+### Phase 23: Face Detection
+| Entity | Type | Description |
+|--------|------|-------------|
+| Face Detected | Binary Sensor | Face in view |
+
+### Phase 24: System Diagnostics
+| Entity | Type | Description |
+|--------|------|-------------|
+| CPU Percent | Sensor (%) | CPU usage |
+| CPU Temperature | Sensor (°C) | CPU temperature |
+| Memory Percent | Sensor (%) | RAM usage |
+| Memory Used | Sensor (GB) | RAM used |
+| Disk Percent | Sensor (%) | Disk usage |
+| Disk Free | Sensor (GB) | Disk free space |
+| Uptime | Sensor (hours) | System uptime |
+| Process CPU | Sensor (%) | App CPU usage |
+| Process Memory | Sensor (MB) | App memory usage |
+
+---
+
+## Sleep Mode
+
+Runtime reactions are zero-config: voice phases, timer alerts, and HA state-triggered emotions use the same built-in behavior model.
+
+### Enter Sleep
+- Turn on the `Sleep Control` switch in Home Assistant
+- Robot relaxes motors, stops camera, pauses voice detection
+
+### Wake Up
+- Turn off the `Sleep Control` switch in Home Assistant
+- Or say the wake word
+- Robot resumes all functions
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Not responding to wake word | Check Mute is off, reduce background noise, verify Home Assistant is connected |
+| Face tracking not working | Ensure adequate lighting, check Face Detected sensor |
+| No audio output | Check Speaker Volume, verify TTS engine in HA |
+| Can't connect to HA | Verify same network, check port 6053 |
+| Gestures not detected | Ensure good lighting, face the camera directly |
+
+---
+
+## Quick Reference
+
+```
+Wake Word:     "Okay Nabu"
+Stop Word:     "Stop"
+ESPHome Port:  6053
+Camera Port:   8081 (MJPEG)
+```
+
+---
+
+*Reachy Mini Voice Assistant v1.0.4*

home_assistant_blueprints/reachy_mini_presence_companion.yaml

@@ -0,0 +1,246 @@
+blueprint:
+  name: Reachy Mini Presence Companion
+  description: >-
+    Presence-driven automation for Reachy Mini in Home Assistant.
+
+    How to use:
+    1) Select Home occupancy entity (person/group/binary_sensor).
+    2) Select Reachy ESPHome device (recommended).
+    3) Leave optional fallback entity inputs empty unless auto-binding fails.
+    4) Set away delay and day/night volume.
+
+    What this automation does:
+    - Occupied: Wake Reachy, enable unified idle behavior, set day volume.
+    - Empty (after delay): Disable unified idle behavior, send Reachy to sleep.
+    - Quiet hours start/end: Apply night/day volume while occupied.
+
+    Auto-binding rules (when Reachy device is selected):
+    - Sleep switch suffix: sleep_control
+    - Idle behavior switch suffix: idle_behavior_enabled
+    - Volume number suffix: speaker_volume
+
+    If your entities use different names, fill optional fallback entity inputs manually.
+  domain: automation
+  input:
+    occupancy_entity:
+      name: Home occupancy entity
+      description: Person, group, or binary sensor representing home presence.
+      selector:
+        entity: {}
+
+    reachy_device:
+      name: Reachy device (recommended)
+      description: Select your Reachy ESPHome device for automatic entity binding.
+      default: ""
+      selector:
+        device:
+          filter:
+            - integration: esphome
+
+    reachy_sleep_switch:
+      name: Sleep Control switch (optional fallback)
+      description: Leave empty to auto-bind from Reachy device.
+      default: ""
+      selector:
+        entity:
+          domain: switch
+
+    idle_behavior_switch:
+      name: Idle Behavior switch (optional fallback)
+      description: Leave empty to auto-bind from Reachy device.
+      default: ""
+      selector:
+        entity:
+          domain: switch
+
+    reachy_volume_number:
+      name: Speaker Volume number (optional fallback)
+      description: Leave empty to auto-bind from Reachy device.
+      default: ""
+      selector:
+        entity:
+          domain: number
+
+    away_delay_minutes:
+      name: Away delay (minutes)
+      description: Wait before sleeping after everyone leaves.
+      default: 20
+      selector:
+        number:
+          min: 1
+          max: 180
+          mode: box
+          unit_of_measurement: min
+
+    day_volume:
+      name: Day volume
+      default: 80
+      selector:
+        number:
+          min: 0
+          max: 100
+          step: 1
+          mode: slider
+
+    night_volume:
+      name: Night volume
+      default: 35
+      selector:
+        number:
+          min: 0
+          max: 100
+          step: 1
+          mode: slider
+
+    quiet_start:
+      name: Quiet hours start
+      default: "22:30:00"
+      selector:
+        time: {}
+
+    quiet_end:
+      name: Quiet hours end
+      default: "07:30:00"
+      selector:
+        time: {}
+
+mode: restart
+
+variables:
+  occupancy_entity: !input occupancy_entity
+  reachy_device: !input reachy_device
+  manual_sleep_switch: !input reachy_sleep_switch
+  manual_idle_behavior_switch: !input idle_behavior_switch
+  manual_volume_number: !input reachy_volume_number
+  day_volume: !input day_volume
+  night_volume: !input night_volume
+
+  device_entities_list: >-
+    {{ device_entities(reachy_device) if reachy_device else [] }}
+
+  sleep_switch_auto: >-
+    {{ (device_entities_list | select('match', '^switch\..*sleep_control$') | list | first) or '' }}
+  idle_behavior_switch_auto: >-
+    {{ (device_entities_list | select('match', '^switch\..*idle_behavior_enabled$') | list | first) or '' }}
+  volume_number_auto: >-
+    {{ (device_entities_list | select('match', '^number\..*speaker_volume$') | list | first) or '' }}
+
+  sleep_switch: >-
+    {{ manual_sleep_switch if manual_sleep_switch else sleep_switch_auto }}
+  idle_behavior_switch: >-
+    {{ manual_idle_behavior_switch if manual_idle_behavior_switch else idle_behavior_switch_auto }}
+  volume_number: >-
+    {{ manual_volume_number if manual_volume_number else volume_number_auto }}
+
+  is_occupied: >-
+    {{ states(occupancy_entity) in ['home', 'on'] }}
+
+trigger:
+  - platform: state
+    id: occupied_home
+    entity_id: !input occupancy_entity
+    to: "home"
+
+  - platform: state
+    id: occupied_on
+    entity_id: !input occupancy_entity
+    to: "on"
+
+  - platform: state
+    id: empty_not_home
+    entity_id: !input occupancy_entity
+    to: "not_home"
+    for:
+      minutes: !input away_delay_minutes
+
+  - platform: state
+    id: empty_off
+    entity_id: !input occupancy_entity
+    to: "off"
+    for:
+      minutes: !input away_delay_minutes
+
+  - platform: time
+    id: quiet_start
+    at: !input quiet_start
+
+  - platform: time
+    id: quiet_end
+    at: !input quiet_end
+
+action:
+  - choose:
+      - conditions:
+          - condition: template
+            value_template: "{{ trigger.id in ['occupied_home', 'occupied_on'] }}"
+        sequence:
+          - if:
+              - condition: template
+                value_template: "{{ sleep_switch != '' }}"
+            then:
+              - service: switch.turn_off
+                target:
+                  entity_id: "{{ sleep_switch }}"
+          - if:
+              - condition: template
+                value_template: "{{ idle_behavior_switch != '' }}"
+            then:
+              - service: switch.turn_on
+                target:
+                  entity_id: "{{ idle_behavior_switch }}"
+          - if:
+              - condition: template
+                value_template: "{{ volume_number != '' }}"
+            then:
+              - service: number.set_value
+                target:
+                  entity_id: "{{ volume_number }}"
+                data:
+                  value: "{{ day_volume }}"
+
+      - conditions:
+          - condition: template
+            value_template: "{{ trigger.id in ['empty_not_home', 'empty_off'] }}"
+        sequence:
+          - if:
+              - condition: template
+                value_template: "{{ idle_behavior_switch != '' }}"
+            then:
+              - service: switch.turn_off
+                target:
+                  entity_id: "{{ idle_behavior_switch }}"
+          - if:
+              - condition: template
+                value_template: "{{ sleep_switch != '' }}"
+            then:
+              - service: switch.turn_on
+                target:
+                  entity_id: "{{ sleep_switch }}"
+
+      - conditions:
+          - condition: template
+            value_template: "{{ trigger.id == 'quiet_start' and is_occupied }}"
+        sequence:
+          - if:
+              - condition: template
+                value_template: "{{ volume_number != '' }}"
+            then:
+              - service: number.set_value
+                target:
+                  entity_id: "{{ volume_number }}"
+                data:
+                  value: "{{ night_volume }}"
+
+      - conditions:
+          - condition: template
+            value_template: "{{ trigger.id == 'quiet_end' and is_occupied }}"
+        sequence:
+          - if:
+              - condition: template
+                value_template: "{{ volume_number != '' }}"
+            then:
+              - service: number.set_value
+                target:
+                  entity_id: "{{ volume_number }}"
+                data:
+                  value: "{{ day_volume }}"

index.html

@@ -0,0 +1,301 @@
+<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width, initial-scale=1" />
+	<title>Reachy Mini for Home Assistant</title>
+	<meta name="description" content="Voice assistant integration for Reachy Mini robot with Home Assistant. Control your smart home with voice commands and expressive robot movements.">
+	<link rel="preconnect" href="https://fonts.googleapis.com">
+	<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+	<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Manrope:wght@400;500;600&display=swap" rel="stylesheet">
+	<link rel="stylesheet" href="style.css" />
+</head>
+<body>
+	<header class="hero">
+		<div class="topline">
+			<div class="brand">
+				<span class="logo">🤖</span>
+				<span class="brand-name">Reachy Mini for Home Assistant</span>
+			</div>
+			<div class="pill">Voice · Gestures · Smart Home</div>
+			<div class="version-pill" id="version-pill">v1.0.4</div>
+		</div>
+		<div class="hero-grid">
+			<div class="hero-copy">
+				<p class="eyebrow">Reachy Mini App</p>
+				<h1>Your robot meets your Home Assistant.</h1>
+				<p class="lede">
+					Transform Reachy Mini Wi-Fi into a voice-controlled smart home hub. Natural conversations, expressive movements, gesture recognition — all seamlessly connected to Home Assistant.
+				</p>
+				<div class="hero-actions">
+					<a class="btn primary" href="#requirements">Requirements</a>
+					<a class="btn ghost" href="#install">Quick Start</a>
+					<a class="btn ghost" href="#features">Features</a>
+				</div>
+				<div class="hero-badges">
+					<span>🎤 Wake Word</span>
+					<span>👀 Face Tracking</span>
+					<span>🔄 Body Following</span>
+					<span>🤚 18 Gestures</span>
+					<span>🔊 Multi-room Audio</span>
+					<span>⚡ Zero Config</span>
+					<span>🃏 Dashboard Card</span>
+				</div>
+			</div>
+			<div class="hero-visual">
+				<div class="video-container">
+					<iframe src="https://www.youtube.com/embed/OuhTSTKB25o" title="Reachy Mini for Home Assistant Demo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+				</div>
+			</div>
+		</div>
+	</header>
+
+	<section id="requirements" class="section">
+		<div class="section-header">
+			<p class="eyebrow">Before You Start</p>
+			<h2>Requirements</h2>
+			<p class="intro">Make sure you have everything ready for a smooth setup.</p>
+		</div>
+		<div class="requirements-grid">
+			<div class="requirement-card">
+				<span class="icon">🤖</span>
+				<h3>Reachy Mini Wi-Fi</h3>
+				<p>This app requires the <strong>Wi-Fi version</strong> of Reachy Mini. The USB version has not been validated</p>
+			</div>
+			<div class="requirement-card">
+				<span class="icon">🏠</span>
+				<h3>Home Assistant</h3>
+				<p>A running Home Assistant instance </p>
+			</div>
+			<div class="requirement-card">
+				<span class="icon">📶</span>
+				<h3>Same Network</h3>
+				<p>Both Reachy Mini and Home Assistant must be on the <strong>same local network</strong>.</p>
+			</div>
+			<div class="requirement-card">
+				<span class="icon">🎙️</span>
+				<h3>Voice Pipeline</h3>
+				<p>Configure a <strong>Voice Assistant pipeline</strong> in Home Assistant (STT + TTS + LLM).</p>
+			</div>
+		</div>
+	</section>
+
+	<section id="install" class="section story">
+		<div class="section-header">
+			<p class="eyebrow">Getting Started</p>
+			<h2>Quick Start</h2>
+			<p class="intro">Install and connect in under a minute. No configuration needed.</p>
+		</div>
+		<div class="story-grid">
+			<div class="story-card">
+				<p class="eyebrow">Installation</p>
+				<h3>Up and running in 1 minute</h3>
+				<ul class="story-list">
+					<li><span>1️⃣</span> Open Reachy Mini Dashboard → Applications</li>
+					<li><span>2️⃣</span> Enable "Show community apps"</li>
+					<li><span>3️⃣</span> Install "Reachy Mini for Home Assistant"</li>
+					<li><span>4️⃣</span> Home Assistant discovers automatically</li>
+				</ul>
+			</div>
+			<div class="story-card secondary">
+				<p class="eyebrow">How it works</p>
+				<h3>Seamless integration</h3>
+				<p class="story-text">
+					This Reachy Mini app uses ESPHome protocol to communicate with Home Assistant — no ESPHome device needed. Home Assistant discovers it via mDNS and adds the robot entities automatically. Voice commands are processed by your Home Assistant instance — STT, intent recognition, and TTS all happen there.
+				</p>
+				<div class="chips">
+					<span class="chip">ESPHome Protocol</span>
+					<span class="chip">mDNS Discovery</span>
+					<span class="chip">Robot Entities</span>
+					<span class="chip">Zero Config</span>
+				</div>
+			</div>
+		</div>
+	</section>
+
+	<section id="features" class="section features">
+		<div class="section-header">
+			<p class="eyebrow">Capabilities</p>
+			<h2>Everything you need for smart home control</h2>
+			<p class="intro">Zero-configuration robot entities, built-in reactions, and auto-discovery via mDNS.</p>
+		</div>
+		<div class="feature-grid">
+			<div class="feature-card">
+				<span class="icon">🎤</span>
+				<h3>Voice Wake</h3>
+				<p>Local wake word detection with MicroWakeWord and OpenWakeWord. Say "Okay Nabu" or "Hey Reachy" to activate.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🏠</span>
+				<h3>Smart Home Control</h3>
+				<p>Full Home Assistant integration. Control lights, switches, climate, media — anything in your Home Assistant.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">👀</span>
+				<h3>Face Tracking</h3>
+				<p>YOLO-based face detection with body following. Head and body move together naturally to track you during conversations.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🤚</span>
+				<h3>Gesture Detection</h3>
+				<p>HaGRID ONNX models recognize hand gestures and publish the detected gesture label and confidence to Home Assistant entities.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">😊</span>
+				<h3>Expressive Motion</h3>
+				<p>Built-in listening, thinking, speaking, timer, and emotion reactions with natural head sway and non-blocking motion during conversations.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">📹</span>
+				<h3>Camera Stream</h3>
+				<p>MJPEG video stream as ESPHome Camera entity. Real-time monitoring in Home Assistant dashboard.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🔊</span>
+				<h3>Multi-room Audio</h3>
+				<p>Sendspin protocol support. Sync audio playback with other speakers throughout your home.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">⚡</span>
+				<h3>Zero Configuration</h3>
+				<p>Install and go. mDNS auto-discovery and built-in HA reactions mean the default experience works without extra setup.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🃏</span>
+				<h3>Dashboard Card</h3>
+				<p>Custom Lovelace card for Home Assistant. Real-time 3D visualization of robot pose and status.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🧩</span>
+				<h3>HA Blueprint</h3>
+				<p>Device-first Home Assistant blueprint for presence automations using the current zero-config model: sleep control, idle behavior, and speaker volume.</p>
+			</div>
+			<div class="feature-card">
+				<span class="icon">🚀</span>
+				<h3>Auto Release</h3>
+				<p>Version-driven GitHub release workflow. Update pyproject/changelog, then release is created automatically.</p>
+			</div>
+		</div>
+	</section>
+
+	<section id="changelog" class="section">
+		<div class="section-header">
+			<p class="eyebrow">Updates</p>
+			<h2>Changelog</h2>
+		</div>
+		<div id="changelog-grid" class="changelog-grid"></div>
+		<div class="changelog-more">
+			<details id="changelog-details">
+				<summary>View older versions</summary>
+				<div id="changelog-older" class="changelog-grid older"></div>
+			</details>
+		</div>
+	</section>
+
+	<script>
+		const VISIBLE_COUNT = 6;
+		fetch('changelog.json')
+			.then(res => res.json())
+			.then(data => {
+				// Update version pill with latest version
+				if (data.length > 0) {
+					const versionPill = document.getElementById('version-pill');
+					if (versionPill) {
+						versionPill.textContent = `v${data[0].version}`;
+					}
+				}
+
+				// Populate changelog grid
+				const mainGrid = document.getElementById('changelog-grid');
+				const olderGrid = document.getElementById('changelog-older');
+				data.forEach((item, index) => {
+					const card = document.createElement('div');
+					card.className = 'changelog-card';
+					card.innerHTML = `
+						<div class="version-badge">v${item.version}</div>
+						<span class="date">${item.date}</span>
+						<ul>${item.changes.map(c => `<li>${c}</li>`).join('')}</ul>
+					`;
+					(index < VISIBLE_COUNT ? mainGrid : olderGrid).appendChild(card);
+				});
+				if (data.length <= VISIBLE_COUNT) {
+					document.getElementById('changelog-details').style.display = 'none';
+				}
+			})
+			.catch(err => console.error('Failed to load changelog:', err));
+	</script>
+
+	<section class="section links">
+		<div class="section-header">
+			<p class="eyebrow">Resources</p>
+			<h2>Links & References</h2>
+		</div>
+		<div class="links-grid">
+			<a href="https://github.com/Desmond-Dong/ha-reachy-mini" target="_blank" class="link-card">
+				<span class="icon">🃏</span>
+				<h3>HA Dashboard Card</h3>
+				<p>Lovelace Card for HA</p>
+			</a>
+			<a href="https://github.com/ha-china/Reachy_Mini_For_Home_Assistant" target="_blank" class="link-card">
+				<span class="icon">📦</span>
+				<h3>Source Code</h3>
+				<p>GitHub Repository</p>
+			</a>
+			<a href="home_assistant_blueprints/reachy_mini_presence_companion.yaml" target="_blank" class="link-card">
+				<span class="icon">🧩</span>
+				<h3>HA Blueprint</h3>
+				<p>Presence Companion YAML</p>
+			</a>
+			<a href="https://www.pollen-robotics.com/" target="_blank" class="link-card">
+				<span class="icon">🤖</span>
+				<h3>Pollen Robotics</h3>
+				<p>Reachy Mini Creator</p>
+			</a>
+			<a href="https://www.home-assistant.io/" target="_blank" class="link-card">
+				<span class="icon">🏠</span>
+				<h3>Home Assistant</h3>
+				<p>Smart Home Platform</p>
+			</a>
+			<a href="https://esphome.io/" target="_blank" class="link-card">
+				<span class="icon">⚡</span>
+				<h3>ESPHome Protocol</h3>
+				<p>Communication Protocol</p>
+			</a>
+			<a href="https://github.com/OHF-Voice/linux-voice-assistant" target="_blank" class="link-card">
+				<span class="icon">🎤</span>
+				<h3>linux-voice-assistant</h3>
+				<p>Voice Assistant Base</p>
+			</a>
+			<a href="https://github.com/kahrendt/microWakeWord" target="_blank" class="link-card">
+				<span class="icon">👂</span>
+				<h3>microWakeWord</h3>
+				<p>Wake Word Detection</p>
+			</a>
+			<a href="https://huggingface.co/AdamCodd/YOLOv11n-face-detection" target="_blank" class="link-card">
+				<span class="icon">👀</span>
+				<h3>YOLOv11n-face</h3>
+				<p>Face Detection Model</p>
+			</a>
+			<a href="https://github.com/ai-forever/dynamic_gestures" target="_blank" class="link-card">
+				<span class="icon">✋</span>
+				<h3>Dynamic Gestures</h3>
+				<p>Reference Project</p>
+			</a>
+			<a href="https://github.com/Sendspin/sendspin-cli" target="_blank" class="link-card">
+				<span class="icon">🔊</span>
+				<h3>Sendspin</h3>
+				<p>Multi-room Audio</p>
+			</a>
+			<a href="https://huggingface.co/spaces/pollen-robotics/reachy-mini-landing-page#apps" target="_blank" class="link-card">
+				<span class="icon">🛒</span>
+				<h3>Reachy Mini App Store</h3>
+				<p>More Apps</p>
+			</a>
+		</div>
+	</section>
+
+	<footer class="footer">
+		<p>Built by <a href="https://github.com/Desmond-Dong" target="_blank">Desmond</a></p>
+	</footer>
+</body>
+</html>

pyproject.toml

@@ -0,0 +1,179 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reachy_mini_home_assistant"
+version = "1.0.7"
+description = "Deep integration of Reachy Mini robot with Home Assistant"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "Apache-2.0"}
+dependencies = [
+    # Reachy Mini SDK with gstreamer support (for camera streaming)
+    "reachy-mini>=1.7.1",
+
+    # Audio processing (for audio file analysis)
+    "soundfile>=0.13.0",
+    "numpy>=2.2.5,<=2.2.5",
+
+    # Camera streaming
+    "opencv-python>=4.12.0.88",
+
+    # Wake word detection (local)
+    # STT/TTS is handled by Home Assistant, not locally
+    "pymicro-wakeword>=2.0.0,<3.0.0",
+    "pyopen-wakeword>=1.0.0,<2.0.0",
+
+    # ESPHome protocol (communication with Home Assistant)
+    "aioesphomeapi>=43.10.1",
+    "zeroconf>=0.131,<1",
+    "websockets>=12,<16",
+    "aiohttp",
+
+    # Motion control (head movements)
+    "scipy>=1.15.3,<2.0.0",
+
+    # Face tracking (YOLO-based head detection)
+    "ultralytics",
+    "supervision",
+
+    # Sendspin synchronized audio (optional, for multi-room playback)
+    "aiosendspin>=5.1,<6.0",
+
+    # Gesture detection (ONNX runtime for HaGRID models)
+    "onnxruntime>=1.18.0",
+
+    # PyTorch (for vision models)
+    "torch==2.5.1",
+    "torchvision==0.20.1",
+
+    # Compatibility with system packages (gradio, etc.)
+    "pillow<12.0",
+    "pydantic<=2.12.5",
+    "requests>=2.33.0",
+]
+keywords = ["reachy-mini-app", "reachy-mini", "home-assistant", "voice-assistant"]
+
+[project.entry-points."reachy_mini_apps"]
+reachy_mini_home_assistant = "reachy_mini_home_assistant.main:ReachyMiniHaVoice"
+
+[tool.setuptools]
+package-dir = { "" = "." }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+
+[tool.setuptools.package-data]
+"*" = ["*.json", "*.flac", "*.md", "*.tflite", "*.onnx", "*.pt"]
+
+# ============================================================================
+# Ruff - Fast Python linter and formatter
+# ============================================================================
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["reachy_mini_home_assistant"]
+
+# Exclude reference code and generated files
+exclude = [
+    "reference/",
+    "__pycache__",
+    ".git",
+    "*.egg-info",
+]
+
+[dependency-groups]
+dev = [
+    "ruff==0.15.4",
+    "mypy==1.20.0",
+]
+
+[tool.uv]
+dependency-metadata = [
+    { name = "gstreamer-libs", version = "1.28.1", requires-dist = ["gstreamer-msvc-runtime; sys_platform == 'win32'", "setuptools"] },
+]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort (import sorting)
+    "B",      # flake8-bugbear (common bugs)
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade (modern Python syntax)
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking (TYPE_CHECKING optimization)
+    "RUF",    # Ruff-specific rules
+    "PTH",    # flake8-use-pathlib
+    "PL",     # Pylint
+]
+ignore = [
+    "E501",     # line too long (handled by formatter)
+    "PLR0913",  # too many arguments (common in robot control)
+    "PLR2004",  # magic value comparison (many thresholds in motion code)
+    "PLR0912",  # too many branches
+    "PLR0915",  # too many statements
+    "PLR0911",  # too many return statements
+    "SIM108",   # use ternary operator (sometimes less readable)
+    "B008",     # function call in default argument (used for field factories)
+    # The following are intentional patterns in this codebase:
+    "PLC0415",  # import-outside-top-level (lazy imports for optional deps)
+    "PLW0603",  # global-statement (used for singletons)
+    "SIM102",   # collapsible-if (sometimes more readable expanded)
+    "SIM105",   # suppressible-exception (explicit try/except is clearer)
+    "PTH123",   # builtin-open (pathlib not always better)
+    "PTH108",   # os-unlink (pathlib not always better)
+    "RUF013",   # implicit-optional (legacy code)
+    "TC002",    # third-party import (numpy is required at runtime)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]  # unused imports in __init__ are intentional
+
+[tool.ruff.lint.isort]
+known-first-party = ["reachy_mini_home_assistant"]
+
+# ============================================================================
+# Mypy - Static type checker
+# ============================================================================
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = false  # Too noisy for mixed typed/untyped codebase
+warn_unused_ignores = true
+disallow_untyped_defs = false  # Start lenient, can tighten later
+check_untyped_defs = false  # Too strict for initial setup
+ignore_missing_imports = true  # Many robot SDK libs lack type stubs
+no_implicit_optional = false  # Allow implicit Optional for now
+# Disable some checks that are too strict for this codebase
+disable_error_code = [
+    "union-attr",  # Too many Optional accesses without None checks
+    "no-redef",    # Class redefinitions for SDK compatibility
+    "attr-defined",  # Some dynamic attributes from SDK
+    "assignment",  # Variable type changes (common in Python)
+    "arg-type",    # Argument type mismatches (often SDK issues)
+    "unused-ignore",  # Type ignore comments from before config
+    "return-value",  # Return type mismatches (often fine)
+    "no-untyped-def",  # Missing type annotations (too strict initially)
+    "valid-type",  # Type validity (some edge cases)
+    "has-type",    # Cannot determine type
+    "call-arg",    # Too few/many arguments
+    "import-untyped",  # Missing stubs for third-party libs
+    "misc",        # Miscellaneous errors
+]
+exclude = [
+    "reference/",
+    "tests/",
+]
+
+# Stricter checking for core modules (can enable gradually)
+[[tool.mypy.overrides]]
+module = [
+    "reachy_mini_home_assistant.core.*",
+    "reachy_mini_home_assistant.motion.smoothing",
+    "reachy_mini_home_assistant.motion.pose_composer",
+]
+disallow_untyped_defs = true
+warn_unreachable = true

reachy_mini_home_assistant/__init__.py

@@ -0,0 +1,29 @@
+"""
+Reachy Mini for Home Assistant
+
+A deep integration app combining Reachy Mini robot with Home Assistant,
+enabling voice control, smart home automation, and expressive robot interactions.
+
+Key features:
+- Local wake word detection (microWakeWord/openWakeWord)
+- ESPHome protocol for seamless Home Assistant communication
+- STT/TTS powered by Home Assistant voice pipeline
+- Reachy Mini motion control with expressive animations
+- Camera streaming and gesture detection
+- Smart home entity control through natural voice commands
+"""
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("reachy_mini_home_assistant")
+except Exception:
+    __version__ = "0.0.0"  # Fallback for development
+__author__ = "Desmond Dong"
+
+# Don't import main module here to avoid runpy warning
+# The app is loaded via entry point: reachy_mini_home_assistant.main:ReachyMiniHaVoiceApp
+
+__all__ = [
+    "__version__",
+]

reachy_mini_home_assistant/__main__.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Main entry point for Reachy Mini for Home Assistant.
+
+This module provides a command-line interface for running the voice assistant
+without the ReachyMini App framework.
+"""
+
+import argparse
+import asyncio
+import logging
+import threading
+
+from .protocol.zeroconf import get_default_friendly_name
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def main() -> None:
+    parser = argparse.ArgumentParser(description="Reachy Mini for Home Assistant")
+    parser.add_argument(
+        "--name",
+        default=get_default_friendly_name(),
+        help="Name of the voice assistant (default: auto-generated from MAC)",
+    )
+    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(
+        "--wake-model",
+        default="okay_nabu",
+        help="Id of active wake model (default: okay_nabu)",
+    )
+    parser.add_argument(
+        "--camera-port",
+        type=int,
+        default=8081,
+        help="Port for camera server (default: 8081)",
+    )
+    parser.add_argument(
+        "--no-camera",
+        action="store_true",
+        help="Disable camera server",
+    )
+    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",
+    )
+
+    # Initialize Reachy Mini (required)
+    from reachy_mini import ReachyMini
+
+    with ReachyMini() as reachy_mini:
+        _LOGGER.info("Reachy Mini connected")
+
+        # Import and create VoiceAssistantService
+        from .voice_assistant import VoiceAssistantService
+
+        service = VoiceAssistantService(
+            reachy_mini=reachy_mini,
+            name=args.name,
+            host=args.host,
+            port=args.port,
+            wake_model=args.wake_model,
+            camera_port=args.camera_port,
+            camera_enabled=not args.no_camera,
+        )
+
+        # Create stop event for graceful shutdown
+        stop_event = threading.Event()
+
+        try:
+            await service.start()
+
+            _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("Camera Server: %s:%s", args.host, args.camera_port)
+            _LOGGER.info("Motion control: enabled")
+            _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>:%s", args.port)
+            _LOGGER.info("=" * 50)
+
+            # Wait for stop signal
+            while not stop_event.is_set():
+                await asyncio.sleep(0.5)
+
+        except KeyboardInterrupt:
+            _LOGGER.info("Shutting down...")
+        finally:
+            await service.stop()
+            _LOGGER.info("Voice assistant stopped")
+
+
+def run():
+    """Entry point for the application."""
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run()

reachy_mini_home_assistant/animations/animation_config.py

@@ -0,0 +1,100 @@
+"""Shared loading and minimal validation for unified animation config."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class AnimationConfigError(ValueError):
+    """Raised when the unified animation configuration is structurally invalid."""
+
+
+_REQUIRED_TOP_LEVEL_TYPES: dict[str, type] = {
+    "animations": dict,
+    "emotions": dict,
+    "settings": dict,
+}
+
+_OPTIONAL_TOP_LEVEL_TYPES: dict[str, type] = {
+    "ha_event_behaviors": dict,
+    "emotion_keywords": dict,
+    "idle_random_actions": dict,
+    "idle_rest_pose": dict,
+}
+
+
+def load_animation_config(config_path: Path) -> dict[str, Any]:
+    """Load and minimally validate the unified animation config file."""
+    if not config_path.exists():
+        raise AnimationConfigError(f"Animation config file not found: {config_path}")
+
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception as e:
+        raise AnimationConfigError(f"Failed to read animation config: {e}") from e
+
+    if not isinstance(data, dict):
+        raise AnimationConfigError("Animation config root must be an object")
+
+    for key, expected_type in _REQUIRED_TOP_LEVEL_TYPES.items():
+        value = data.get(key)
+        if not isinstance(value, expected_type):
+            raise AnimationConfigError(f"Animation config section '{key}' must be a {expected_type.__name__}")
+
+    for key, expected_type in _OPTIONAL_TOP_LEVEL_TYPES.items():
+        value = data.get(key)
+        if value is not None and not isinstance(value, expected_type):
+            raise AnimationConfigError(f"Animation config section '{key}' must be a {expected_type.__name__}")
+
+    _validate_ha_event_behaviors(data.get("ha_event_behaviors"))
+    _validate_emotion_keywords(data.get("emotion_keywords"))
+    _validate_idle_random_actions(data.get("idle_random_actions"))
+
+    return data
+
+
+def get_animation_config_section(config_path: Path, section_name: str) -> dict[str, Any]:
+    """Load one validated section from the unified animation config."""
+    data = load_animation_config(config_path)
+    section = data.get(section_name)
+    if section is None:
+        return {}
+    if not isinstance(section, dict):
+        raise AnimationConfigError(f"Animation config section '{section_name}' must be a dict")
+    return section
+
+
+def _validate_ha_event_behaviors(section: Any) -> None:
+    if section is None:
+        return
+    mappings = section.get("mappings", {})
+    if not isinstance(mappings, dict):
+        raise AnimationConfigError("ha_event_behaviors.mappings must be a dict")
+    settings = section.get("settings", {})
+    if not isinstance(settings, dict):
+        raise AnimationConfigError("ha_event_behaviors.settings must be a dict")
+
+
+def _validate_emotion_keywords(section: Any) -> None:
+    if section is None:
+        return
+    keywords = section.get("keywords", {})
+    if not isinstance(keywords, dict):
+        raise AnimationConfigError("emotion_keywords.keywords must be a dict")
+    settings = section.get("settings", {})
+    if not isinstance(settings, dict):
+        raise AnimationConfigError("emotion_keywords.settings must be a dict")
+
+
+def _validate_idle_random_actions(section: Any) -> None:
+    if section is None:
+        return
+    actions = section.get("actions", [])
+    if not isinstance(actions, list):
+        raise AnimationConfigError("idle_random_actions.actions must be a list")

reachy_mini_home_assistant/audio/__init__.py

@@ -0,0 +1,15 @@
+"""Audio module for Reachy Mini.
+
+This module handles all audio-related functionality:
+- AudioPlayer: Audio playback with Sendspin support
+- DOATracker: Direction of Arrival sound localization
+"""
+
+from .audio_player import AudioPlayer
+from .doa_tracker import DOAConfig, DOATracker
+
+__all__ = [
+    "AudioPlayer",
+    "DOAConfig",
+    "DOATracker",
+]

reachy_mini_home_assistant/audio/audio_player.py

@@ -0,0 +1,79 @@
+"""Audio player facade for Reachy Mini audio playback."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections import deque
+from typing import TYPE_CHECKING
+
+from .audio_player_playback import AudioPlayerPlaybackMixin
+from .audio_player_sendspin import AudioFormat, AudioPlayerSendspinMixin, ClientListener, SendspinClient
+from .audio_player_shared import get_stable_client_id
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ..protocol.zeroconf import SendspinDiscovery
+
+
+class AudioPlayer(AudioPlayerSendspinMixin, AudioPlayerPlaybackMixin):
+    """Audio player using Reachy Mini's media system with automatic Sendspin support."""
+
+    def __init__(self, reachy_mini=None, gstreamer_lock=None) -> None:
+        self.reachy_mini = reachy_mini
+        self._gstreamer_lock = gstreamer_lock if gstreamer_lock is not None else threading.Lock()
+        self.is_playing = False
+        self._playlist: list[str] = []
+        self._done_callback: Callable[[], None] | 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()
+        self._playback_thread: threading.Thread | None = None
+        self._sway_callback: Callable[[dict], None] | None = None
+
+        self._sendspin_client_id = get_stable_client_id()
+        self._sendspin_client: SendspinClient | None = None
+        self._sendspin_listener: ClientListener | None = None
+        self._sendspin_enabled = False
+        self._sendspin_url: str | None = None
+        self._sendspin_discovery: SendspinDiscovery | None = None
+        self._sendspin_unsubscribers: list[Callable] = []
+        self._sendspin_connect_lock: asyncio.Lock | None = None
+        self._sendspin_audio_format: AudioFormat | None = None
+        self._sendspin_playback_started = False
+        self._sendspin_stream_active = False
+        self._sendspin_paused = False
+        self._sendspin_remote_volume = 100
+        self._sendspin_muted = False
+        self._sendspin_queue = deque()
+        self._sendspin_queue_bytes = 0
+        self._sendspin_sway_queue = deque()
+        self._sendspin_queue_lock = threading.Lock()
+        self._sendspin_queue_event = threading.Event()
+        self._sendspin_queue_stop = threading.Event()
+        self._sendspin_queue_thread: threading.Thread | None = None
+        self._sendspin_sway_state: dict | None = None
+        self._logged_resample = False
+        self._last_sendspin_overflow_log = 0.0
+        self._http_host_override: str | None = None
+
+    def set_sway_callback(self, callback: Callable[[dict], None] | None) -> None:
+        self._sway_callback = callback
+
+    def set_reachy_mini(self, reachy_mini) -> None:
+        self.reachy_mini = reachy_mini
+
+    def set_http_host_override(self, host: str | None) -> None:
+        self._http_host_override = host
+
+    def __del__(self) -> None:
+        try:
+            self._remove_sendspin_listeners()
+            self._clear_sendspin_queue()
+            self._stop_sendspin_worker()
+            self._sendspin_client = None
+        except Exception:
+            pass

reachy_mini_home_assistant/audio/audio_player_local.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import time
+
+from .audio_player_shared import MOVEMENT_LATENCY_S, STREAM_FETCH_CHUNK_SIZE, _LOGGER, sniff_audio_content_type
+
+
+class AudioPlayerLocalMixin:
+    def _play_cached_audio(self, audio_bytes: bytes | bytearray, content_type: str, source_url: str = "") -> bool:
+        if not audio_bytes:
+            return False
+        audio_data = bytes(audio_bytes)
+        if (not content_type) or (content_type == "application/octet-stream"):
+            sniffed = sniff_audio_content_type(audio_data[: min(len(audio_data), 64)])
+            if sniffed:
+                content_type = sniffed
+        mem_iter = (
+            audio_data[i : i + STREAM_FETCH_CHUNK_SIZE] for i in range(0, len(audio_data), STREAM_FETCH_CHUNK_SIZE)
+        )
+        adapted_response = self._iterator_response_adapter(mem_iter)
+        if self._is_pcm_content_type(content_type):
+            return self._stream_pcm_response(adapted_response, content_type)
+        if self._stream_decoded_response(adapted_response, source_url or "memory-cache", content_type):
+            return True
+        return self._play_cached_audio_via_tempfile(audio_data, content_type, source_url)
+
+    def _play_cached_audio_via_tempfile(self, audio_data: bytes, content_type: str, source_url: str) -> bool:
+        import os
+        import tempfile
+
+        temp_path = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                delete=False, suffix=self._guess_audio_suffix(content_type, source_url)
+            ) as tmp:
+                tmp.write(audio_data)
+                temp_path = tmp.name
+            self._play_local_file(temp_path)
+            return True
+        except Exception as e:
+            _LOGGER.debug("Tempfile fallback playback failed: %s", e)
+            return False
+        finally:
+            if temp_path:
+                try:
+                    os.unlink(temp_path)
+                except Exception:
+                    pass
+
+    def _guess_audio_suffix(self, content_type: str, source_url: str) -> str:
+        from urllib.parse import urlparse
+
+        ct = (content_type or "").split(";", 1)[0].strip().lower()
+        mapping = {
+            "audio/mpeg": ".mp3",
+            "audio/mp3": ".mp3",
+            "audio/aac": ".aac",
+            "audio/mp4": ".m4a",
+            "audio/ogg": ".ogg",
+            "application/ogg": ".ogg",
+            "audio/opus": ".opus",
+            "audio/webm": ".webm",
+            "audio/wav": ".wav",
+            "audio/wave": ".wav",
+            "audio/x-wav": ".wav",
+            "audio/flac": ".flac",
+            "audio/x-flac": ".flac",
+        }
+        if ct in mapping:
+            return mapping[ct]
+        try:
+            path = urlparse(source_url).path
+            if "." in path:
+                suffix = "." + path.rsplit(".", 1)[1]
+                if len(suffix) <= 8:
+                    return suffix
+        except Exception:
+            pass
+        return ".bin"
+
+    def _play_local_file(self, file_path: str) -> None:
+        try:
+            duration: float | None = None
+            sway_frames: list[dict] = []
+            try:
+                import soundfile as sf
+
+                info = sf.info(file_path)
+                if info.samplerate > 0 and info.frames > 0:
+                    duration = float(info.frames) / float(info.samplerate)
+            except Exception:
+                duration = None
+            if self._sway_callback is not None:
+                try:
+                    import soundfile as sf
+
+                    data, sample_rate = sf.read(file_path)
+                    if duration is None and sample_rate > 0:
+                        duration = len(data) / sample_rate
+                    sway = self._new_sway_analyzer()
+                    sway_frames = self._compute_sway_frames(sway, data, sample_rate)
+                except Exception:
+                    sway_frames = []
+            self.reachy_mini.media.play_sound(file_path)
+            start_time = time.monotonic()
+            frame_duration = 0.05
+            frame_idx = 0
+            has_duration = (duration is not None) and (duration > 0)
+            duration_s = duration if has_duration and duration is not None else 0.0
+            max_duration = (duration_s * 1.5) if has_duration else 60.0
+            playback_timeout = start_time + max_duration
+            sway_base_ts = start_time + MOVEMENT_LATENCY_S
+            while True:
+                now = time.monotonic()
+                if now > playback_timeout:
+                    _LOGGER.warning("Audio playback timeout (%.1fs), stopping", max_duration)
+                    self.reachy_mini.media.stop_playing()
+                    break
+                if self._stop_flag.is_set():
+                    self.reachy_mini.media.stop_playing()
+                    break
+                if has_duration:
+                    if (now - start_time) >= duration_s:
+                        break
+                else:
+                    try:
+                        if not bool(self.reachy_mini.media.is_playing()):
+                            break
+                    except Exception:
+                        pass
+                if self._sway_callback and frame_idx < len(sway_frames):
+                    target_frame = frame_idx
+                    while target_frame < len(sway_frames) and now >= (sway_base_ts + target_frame * frame_duration):
+                        target_frame += 1
+                    while frame_idx < target_frame and frame_idx < len(sway_frames):
+                        self._sway_callback(sway_frames[frame_idx])
+                        frame_idx += 1
+                next_sleep = 0.02
+                if self._sway_callback and frame_idx < len(sway_frames):
+                    next_sway_ts = sway_base_ts + frame_idx * frame_duration
+                    next_sleep = min(next_sleep, max(0.0, next_sway_ts - now))
+                time.sleep(next_sleep)
+        finally:
+            self._reset_sway_output()

reachy_mini_home_assistant/audio/audio_player_playback.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+import requests
+
+from .audio_player_local import AudioPlayerLocalMixin
+from .audio_player_shared import STREAM_FETCH_CHUNK_SIZE, _LOGGER, rewrite_local_service_url, sniff_audio_content_type
+from .audio_player_stream_decoded import AudioPlayerStreamDecodedMixin
+from .audio_player_stream_pcm import AudioPlayerStreamPCMMixin
+from .audio_player_wobble import AudioPlayerWobbleMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class AudioPlayerPlaybackMixin(
+    AudioPlayerLocalMixin,
+    AudioPlayerStreamDecodedMixin,
+    AudioPlayerStreamPCMMixin,
+    AudioPlayerWobbleMixin,
+):
+    def play(
+        self, url: str | list[str], done_callback: Callable[[], None] | None = None, stop_first: bool = True
+    ) -> None:
+        if stop_first:
+            self.stop()
+        self._playlist = [url] if isinstance(url, str) else list(url)
+        self._done_callback = done_callback
+        self._stop_flag.clear()
+        if self._playback_thread and self._playback_thread.is_alive():
+            _LOGGER.warning("Previous playback still active, stopping it")
+            self.stop()
+        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
+        self._playback_thread = threading.Thread(target=self._play_file, args=(next_url,), daemon=True)
+        self._playback_thread.start()
+
+    def _play_file(self, file_path: str) -> None:
+        try:
+            if file_path.startswith(("http://", "https://")):
+                source_url = rewrite_local_service_url(file_path, getattr(self, "_http_host_override", None))
+                streamed = False
+                cached_audio = bytearray()
+                content_type = ""
+                try:
+                    request_kwargs = {"stream": True, "timeout": (5.0, 30.0)}
+                    try:
+                        response_ctx = requests.get(source_url, **request_kwargs)
+                    except requests.exceptions.SSLError:
+                        request_kwargs["verify"] = False
+                        response_ctx = requests.get(source_url, **request_kwargs)
+
+                    with response_ctx as response:
+                        response.raise_for_status()
+                        content_type = (response.headers.get("Content-Type") or "").lower()
+                        stream_iter = response.iter_content(chunk_size=STREAM_FETCH_CHUNK_SIZE)
+
+                        first_chunk = b""
+                        for chunk in stream_iter:
+                            if chunk:
+                                first_chunk = chunk
+                                cached_audio.extend(chunk)
+                                break
+
+                        if (not content_type) or (content_type == "application/octet-stream"):
+                            sniffed = sniff_audio_content_type(first_chunk)
+                            if sniffed:
+                                content_type = sniffed
+
+                        def caching_iter_content(chunk_size: int = STREAM_FETCH_CHUNK_SIZE):
+                            del chunk_size
+                            if first_chunk:
+                                yield first_chunk
+                            for chunk in stream_iter:
+                                if chunk:
+                                    if chunk is not first_chunk:
+                                        cached_audio.extend(chunk)
+                                    yield chunk
+
+                        adapted_response = self._iterator_response_adapter(caching_iter_content())
+                        if self._is_pcm_content_type(content_type):
+                            _LOGGER.info("TTS playback mode: streaming_pcm")
+                            streamed = self._stream_pcm_response(adapted_response, content_type)
+                        else:
+                            _LOGGER.info("TTS playback mode: streaming_decoded")
+                            streamed = self._stream_decoded_response(adapted_response, source_url, content_type)
+                        if not streamed:
+                            for chunk in stream_iter:
+                                if chunk:
+                                    cached_audio.extend(chunk)
+                except Exception as e:
+                    _LOGGER.debug("Streaming TTS failed, fallback to memory playback: %s", e)
+                if streamed:
+                    return
+                _LOGGER.info("TTS playback mode: fallback_memory")
+                played = self._play_cached_audio(cached_audio, content_type, source_url=source_url)
+                if played:
+                    return
+                _LOGGER.error("Failed to play cached TTS audio from memory")
+                return
+            if self._stop_flag.is_set():
+                return
+            self._play_local_file(file_path)
+        except Exception as e:
+            _LOGGER.error("Error playing audio: %s", e)
+        finally:
+            self.is_playing = False
+            if self._playlist and not self._stop_flag.is_set():
+                self._play_next()
+            else:
+                self._on_playback_finished()
+
+    @staticmethod
+    def _iterator_response_adapter(iterator):
+        class _ResponseAdapter:
+            def __init__(self, iter_obj) -> None:
+                self._iter_obj = iter_obj
+
+            def iter_content(self, chunk_size: int = 8192):
+                del chunk_size
+                return self._iter_obj
+
+        return _ResponseAdapter(iterator)
+
+    def _on_playback_finished(self) -> None:
+        self.is_playing = False
+        todo_callback: Callable[[], None] | 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:
+        self._stop_flag.set()
+        try:
+            self.reachy_mini.media.stop_playing()
+        except Exception:
+            pass
+        self.is_playing = False
+
+    def resume_playback(self) -> None:
+        self._stop_flag.clear()
+        if self._playlist:
+            self._play_next()
+
+    def stop(self) -> None:
+        self._stop_flag.set()
+        try:
+            self.reachy_mini.media.stop_playing()
+        except Exception:
+            pass
+        if self._playback_thread and self._playback_thread.is_alive():
+            try:
+                self._playback_thread.join(timeout=2.0)
+                if self._playback_thread.is_alive():
+                    _LOGGER.warning("Playback thread did not stop in time")
+            except Exception:
+                pass
+            self._playback_thread = None
+        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
+
+    def suspend(self) -> None:
+        _LOGGER.info("Suspending AudioPlayer resources...")
+        self.stop()
+        self._sway_callback = None
+        _LOGGER.info("AudioPlayer resources suspended")
+
+    def resume(self) -> None:
+        _LOGGER.info("Resuming AudioPlayer resources...")
+        self._stop_flag.clear()
+        _LOGGER.info("AudioPlayer resources resumed")

reachy_mini_home_assistant/audio/audio_player_sendspin.py

@@ -0,0 +1,643 @@
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .audio_player_shared import (
+    AudioPlayerSwayMixin,
+    MOVEMENT_LATENCY_S,
+    SENDSPIN_HIGH_WATERMARK_BYTES,
+    SENDSPIN_LATE_DROP_GRACE_US,
+    SENDSPIN_LOCAL_BUFFER_CAPACITY_BYTES,
+    SENDSPIN_SCHEDULE_AHEAD_LIMIT_US,
+    SWAY_FRAME_DT_S,
+    _LOGGER,
+)
+
+if TYPE_CHECKING:
+    from aiosendspin.models.core import StreamStartMessage
+
+try:
+    from aiosendspin.client import SendspinClient
+    from aiosendspin.client.client import AudioFormat, PCMFormat
+    from aiosendspin.models.core import DeviceInfo
+    from aiosendspin.models.player import ClientHelloPlayerSupport, SupportedAudioFormat
+    from aiosendspin.models.types import AudioCodec, PlayerCommand, Roles
+
+    SENDSPIN_AVAILABLE = True
+except Exception as e:
+    SENDSPIN_AVAILABLE = False
+    _LOGGER.warning("Sendspin unavailable, disabling integration: %s", e)
+    PCMFormat = None  # type: ignore[assignment]
+    AudioFormat = None  # type: ignore[assignment]
+    SendspinClient = None  # type: ignore[assignment]
+    ClientHelloPlayerSupport = None  # type: ignore[assignment]
+    DeviceInfo = None  # type: ignore[assignment]
+    SupportedAudioFormat = None  # type: ignore[assignment]
+    AudioCodec = None  # type: ignore[assignment]
+    PlayerCommand = None  # type: ignore[assignment]
+    Roles = None  # type: ignore[assignment]
+
+try:
+    from aiosendspin.client.listener import DEFAULT_PORT as SENDSPIN_DEFAULT_PORT
+    from aiosendspin.client.listener import ClientListener
+except Exception:
+    ClientListener = None  # type: ignore[assignment]
+    SENDSPIN_DEFAULT_PORT = 8928  # type: ignore[assignment]
+
+
+@dataclass(slots=True)
+class _QueuedSendspinChunk:
+    play_time_us: int
+    audio_float: np.ndarray
+    byte_count: int
+
+
+@dataclass(slots=True)
+class _QueuedSendspinSwayFrame:
+    target_time_us: int
+    sway: dict[str, float]
+
+
+class AudioPlayerSendspinMixin(AudioPlayerSwayMixin):
+    @property
+    def sendspin_available(self) -> bool:
+        return SENDSPIN_AVAILABLE
+
+    @property
+    def sendspin_enabled(self) -> bool:
+        return self._sendspin_enabled and self._sendspin_client is not None
+
+    @property
+    def sendspin_url(self) -> str | None:
+        return self._sendspin_url
+
+    def _get_sendspin_connect_lock(self) -> asyncio.Lock:
+        if self._sendspin_connect_lock is None:
+            self._sendspin_connect_lock = asyncio.Lock()
+        return self._sendspin_connect_lock
+
+    def _get_sendspin_effective_volume(self) -> float:
+        if self._sendspin_muted:
+            return 0.0
+        return self._current_volume * (self._sendspin_remote_volume / 100.0)
+
+    def _ensure_sendspin_worker(self) -> None:
+        if self._sendspin_queue_thread is not None and self._sendspin_queue_thread.is_alive():
+            return
+        self._sendspin_queue_stop.clear()
+        self._sendspin_queue_event.clear()
+        self._sendspin_queue_thread = threading.Thread(
+            target=self._sendspin_worker_loop, name="sendspin-playback", daemon=True
+        )
+        self._sendspin_queue_thread.start()
+
+    def _stop_sendspin_worker(self) -> None:
+        self._sendspin_queue_stop.set()
+        self._sendspin_queue_event.set()
+        if self._sendspin_queue_thread is not None:
+            try:
+                self._sendspin_queue_thread.join(timeout=1.0)
+            except Exception:
+                pass
+            self._sendspin_queue_thread = None
+        self._sendspin_queue_stop.clear()
+        self._sendspin_queue_event.clear()
+
+    def _sendspin_worker_loop(self) -> None:
+        while not self._sendspin_queue_stop.is_set():
+            if self._sendspin_paused:
+                self._sendspin_queue_event.wait(timeout=0.05)
+                self._sendspin_queue_event.clear()
+                continue
+            with self._sendspin_queue_lock:
+                chunk = self._sendspin_queue[0] if self._sendspin_queue else None
+                sway_frame = self._sendspin_sway_queue[0] if self._sendspin_sway_queue else None
+            if chunk is None and sway_frame is None:
+                self._sendspin_queue_event.wait(timeout=0.1)
+                self._sendspin_queue_event.clear()
+                continue
+            now_us = time.monotonic_ns() // 1000
+            next_audio_us = chunk.play_time_us if chunk is not None else None
+            next_sway_us = sway_frame.target_time_us if sway_frame is not None else None
+            next_event_us = min(ts for ts in (next_audio_us, next_sway_us) if ts is not None)
+            delay_us = next_event_us - now_us
+            if delay_us > 2_000:
+                self._sendspin_queue_event.wait(timeout=min(delay_us / 1_000_000.0, 0.05))
+                self._sendspin_queue_event.clear()
+                continue
+            handle_sway = False
+            with self._sendspin_queue_lock:
+                chunk = self._sendspin_queue[0] if self._sendspin_queue else None
+                sway_frame = self._sendspin_sway_queue[0] if self._sendspin_sway_queue else None
+                now_us = time.monotonic_ns() // 1000
+                next_audio_us = chunk.play_time_us if chunk is not None else None
+                next_sway_us = sway_frame.target_time_us if sway_frame is not None else None
+                if next_audio_us is None and next_sway_us is None:
+                    continue
+                if next_audio_us is None:
+                    handle_sway = True
+                elif next_sway_us is None:
+                    handle_sway = False
+                else:
+                    handle_sway = next_sway_us < next_audio_us
+                if handle_sway:
+                    sway_frame = self._sendspin_sway_queue.popleft()
+                else:
+                    chunk = self._sendspin_queue.popleft()
+                    self._sendspin_queue_bytes = max(0, self._sendspin_queue_bytes - chunk.byte_count)
+            if handle_sway:
+                self._apply_sendspin_sway_frame(sway_frame)
+                continue
+            late_by_us = now_us - chunk.play_time_us
+            if late_by_us > SENDSPIN_LATE_DROP_GRACE_US:
+                _LOGGER.debug("Dropping late Sendspin chunk (%d ms late)", late_by_us // 1000)
+                continue
+            self._push_sendspin_audio_sample(chunk.audio_float)
+
+    def _apply_sendspin_sway_frame(self, sway_frame: _QueuedSendspinSwayFrame) -> None:
+        if self._sway_callback is None or self._sendspin_paused:
+            return
+        try:
+            self._sway_callback(sway_frame.sway)
+        except Exception:
+            _LOGGER.debug("Failed to apply Sendspin sway frame", exc_info=True)
+
+    def _push_sendspin_audio_sample(self, audio_float: np.ndarray) -> None:
+        if self.reachy_mini is None:
+            return
+        if not self._sendspin_playback_started:
+            try:
+                self.reachy_mini.media.start_playing()
+                self._sendspin_playback_started = True
+            except Exception:
+                _LOGGER.exception("Failed to start media playback for Sendspin")
+                return
+        acquired = self._gstreamer_lock.acquire(timeout=0.05)
+        if not acquired:
+            _LOGGER.debug("GStreamer lock busy, dropping due Sendspin chunk")
+            return
+        try:
+            self.reachy_mini.media.push_audio_sample(audio_float)
+        except Exception:
+            _LOGGER.exception("Failed to push Sendspin audio chunk")
+        finally:
+            self._gstreamer_lock.release()
+
+    def _stop_sendspin_output(self) -> None:
+        if self.reachy_mini is None:
+            return
+        try:
+            self.reachy_mini.media.audio.clear_output_buffer()
+        except Exception:
+            _LOGGER.debug("Failed to clear output buffer", exc_info=True)
+        if self._sendspin_playback_started:
+            try:
+                self.reachy_mini.media.stop_playing()
+            except Exception:
+                _LOGGER.debug("Failed to stop Sendspin playback", exc_info=True)
+        self._sendspin_playback_started = False
+
+    def _clear_sendspin_queue(self) -> None:
+        with self._sendspin_queue_lock:
+            self._sendspin_queue.clear()
+            self._sendspin_queue_bytes = 0
+            self._sendspin_sway_queue.clear()
+        self._sendspin_queue_event.set()
+
+    def _reset_sendspin_sway_state(self, *, reset_output: bool) -> None:
+        self._sendspin_sway_state = None
+        if reset_output:
+            self._reset_sway_output()
+
+    def _reset_sendspin_stream_state(self, *, stop_output: bool) -> None:
+        self._clear_sendspin_queue()
+        self._reset_sendspin_sway_state(reset_output=True)
+        self._sendspin_audio_format = None
+        self._logged_resample = False
+        if stop_output:
+            self._stop_sendspin_output()
+
+    def _queue_sendspin_audio(self, play_time_us: int, audio_float: np.ndarray, byte_count: int) -> None:
+        with self._sendspin_queue_lock:
+            self._sendspin_queue.append(_QueuedSendspinChunk(play_time_us, audio_float, byte_count))
+            self._sendspin_queue_bytes += byte_count
+            while self._sendspin_queue_bytes > SENDSPIN_LOCAL_BUFFER_CAPACITY_BYTES and self._sendspin_queue:
+                dropped = self._sendspin_queue.popleft()
+                self._sendspin_queue_bytes = max(0, self._sendspin_queue_bytes - dropped.byte_count)
+                now = time.monotonic()
+                if now - getattr(self, "_last_sendspin_overflow_log", 0.0) >= 1.0:
+                    _LOGGER.warning("Sendspin buffer overflow, dropping oldest queued audio")
+                    self._last_sendspin_overflow_log = now
+        self._sendspin_queue_event.set()
+
+    def _should_backpressure_sendspin_chunk(self, play_time_us: int, byte_count: int) -> bool:
+        with self._sendspin_queue_lock:
+            queued_bytes = self._sendspin_queue_bytes
+        if queued_bytes + byte_count < SENDSPIN_HIGH_WATERMARK_BYTES:
+            return False
+
+        now_us = time.monotonic_ns() // 1000
+        queued_ahead_us = max(0, play_time_us - now_us)
+        if queued_ahead_us < 500_000:
+            return False
+
+        now = time.monotonic()
+        if now - getattr(self, "_last_sendspin_overflow_log", 0.0) >= 1.0:
+            _LOGGER.warning(
+                "Sendspin backpressure active, skipping queued audio (queued=%d bytes, ahead=%d ms)",
+                queued_bytes,
+                queued_ahead_us // 1000,
+            )
+            self._last_sendspin_overflow_log = now
+        return True
+
+    def _get_sendspin_sway_state(self) -> dict | None:
+        if self._sway_callback is None:
+            return None
+        if self._sendspin_sway_state is None:
+            analyzer = self._new_sway_analyzer()
+            if analyzer is None:
+                _LOGGER.debug("Failed to initialize Sendspin sway analyzer")
+                self._sendspin_sway_state = None
+            else:
+                self._sendspin_sway_state = {"sway": analyzer}
+        return self._sendspin_sway_state
+
+    def _queue_sendspin_sway(self, play_time_us: int, pcm: np.ndarray, sample_rate: int) -> None:
+        ctx = self._get_sendspin_sway_state()
+        if ctx is None:
+            return
+        try:
+            results = self._compute_sway_frames(ctx["sway"], pcm, sample_rate)
+            if not results:
+                return
+            latency_us = int(MOVEMENT_LATENCY_S * 1_000_000)
+            hop_us = int(SWAY_FRAME_DT_S * 1_000_000)
+            with self._sendspin_queue_lock:
+                for idx, item in enumerate(results):
+                    self._sendspin_sway_queue.append(
+                        _QueuedSendspinSwayFrame(target_time_us=play_time_us + latency_us + idx * hop_us, sway=item)
+                    )
+        except Exception:
+            _LOGGER.debug("Failed to queue Sendspin sway frames", exc_info=True)
+        self._sendspin_queue_event.set()
+
+    def _decode_pcm_bytes(self, audio_data: bytes, pcm_format: PCMFormat) -> np.ndarray:
+        if pcm_format.bit_depth == 16:
+            audio_int = np.frombuffer(audio_data, dtype="<i2")
+            audio_float = audio_int.astype(np.float32) / 32768.0
+        elif pcm_format.bit_depth == 24:
+            raw = np.frombuffer(audio_data, dtype=np.uint8)
+            frame_count = len(raw) // 3
+            raw = raw[: frame_count * 3].reshape(-1, 3)
+            audio_int = (
+                raw[:, 0].astype(np.int32) | (raw[:, 1].astype(np.int32) << 8) | (raw[:, 2].astype(np.int32) << 16)
+            )
+            sign_mask = 1 << 23
+            audio_int = (audio_int ^ sign_mask) - sign_mask
+            audio_float = audio_int.astype(np.float32) / 8388608.0
+        elif pcm_format.bit_depth == 32:
+            audio_int = np.frombuffer(audio_data, dtype="<i4")
+            audio_float = audio_int.astype(np.float32) / 2147483648.0
+        else:
+            raise ValueError(f"Unsupported PCM bit depth: {pcm_format.bit_depth}")
+        audio_float = np.clip(audio_float, -1.0, 1.0)
+        channels = max(1, int(pcm_format.channels))
+        frame_count = len(audio_float) // channels
+        if frame_count <= 0:
+            raise ValueError("Audio chunk does not contain a complete frame")
+        return audio_float[: frame_count * channels].reshape(frame_count, channels)
+
+    def _decode_sendspin_audio(self, audio_data: bytes, fmt: AudioFormat) -> np.ndarray:
+        if fmt.codec != AudioCodec.PCM:
+            raise ValueError(f"Unsupported Sendspin codec for Reachy playback: {fmt.codec.value}")
+        pcm_format = fmt.pcm_format
+        audio_float = self._decode_pcm_bytes(audio_data, pcm_format)
+        target_sample_rate = self.reachy_mini.media.get_output_audio_samplerate()
+        if pcm_format.sample_rate != target_sample_rate and target_sample_rate > 0:
+            import scipy.signal
+
+            new_length = int(len(audio_float) * target_sample_rate / pcm_format.sample_rate)
+            if new_length > 0:
+                audio_float = scipy.signal.resample(audio_float, new_length, axis=0)
+                if not self._logged_resample:
+                    _LOGGER.debug(
+                        "Resampling Sendspin audio: %d Hz -> %d Hz", pcm_format.sample_rate, target_sample_rate
+                    )
+                    self._logged_resample = True
+        return np.clip(audio_float * self._get_sendspin_effective_volume(), -1.0, 1.0).astype(np.float32, copy=False)
+
+    def _build_sendspin_client(self) -> SendspinClient:
+        player_support = ClientHelloPlayerSupport(
+            supported_formats=[
+                SupportedAudioFormat(codec=AudioCodec.PCM, channels=2, sample_rate=16000, bit_depth=16),
+                SupportedAudioFormat(codec=AudioCodec.PCM, channels=1, sample_rate=16000, bit_depth=16),
+                SupportedAudioFormat(codec=AudioCodec.PCM, channels=2, sample_rate=48000, bit_depth=16),
+                SupportedAudioFormat(codec=AudioCodec.PCM, channels=2, sample_rate=44100, bit_depth=16),
+                SupportedAudioFormat(codec=AudioCodec.PCM, channels=1, sample_rate=48000, bit_depth=16),
+                SupportedAudioFormat(codec=AudioCodec.PCM, channels=1, sample_rate=44100, bit_depth=16),
+            ],
+            buffer_capacity=32_000_000,
+            supported_commands=[PlayerCommand.VOLUME, PlayerCommand.MUTE],
+        )
+        return SendspinClient(
+            client_id=self._sendspin_client_id,
+            client_name="Reachy Mini",
+            roles=[Roles.PLAYER],
+            device_info=DeviceInfo(
+                product_name="Reachy Mini",
+                manufacturer="Pollen Robotics",
+            ),
+            player_support=player_support,
+            initial_volume=max(0, min(100, round(self._unduck_volume * 100.0))),
+            initial_muted=self._sendspin_muted,
+        )
+
+    def _remove_sendspin_listeners(self) -> None:
+        for unsub in self._sendspin_unsubscribers:
+            try:
+                unsub()
+            except Exception:
+                _LOGGER.debug("Error during Sendspin unsubscribe", exc_info=True)
+        self._sendspin_unsubscribers.clear()
+
+    def _register_sendspin_listeners(self, client: SendspinClient) -> None:
+        def _is_current() -> bool:
+            return self._sendspin_client is client
+
+        def _handle_audio_chunk(ts: int, audio_data: bytes, fmt: AudioFormat) -> None:
+            if _is_current():
+                self._on_sendspin_audio_chunk(client, ts, audio_data, fmt)
+
+        def _handle_stream_start(message: StreamStartMessage) -> None:
+            if _is_current():
+                self._on_sendspin_stream_start(client, message)
+
+        def _handle_stream_end(roles: list[str] | None) -> None:
+            if _is_current():
+                self._on_sendspin_stream_end(client, roles)
+
+        def _handle_stream_clear(roles: list[str] | None) -> None:
+            if _is_current():
+                self._on_sendspin_stream_clear(client, roles)
+
+        def _handle_disconnect() -> None:
+            if _is_current():
+                self._on_sendspin_disconnected(client)
+
+        def _handle_server_command(payload) -> None:
+            if _is_current():
+                self._on_sendspin_server_command(client, payload)
+
+        self._sendspin_unsubscribers = [
+            client.add_audio_chunk_listener(_handle_audio_chunk),
+            client.add_stream_start_listener(_handle_stream_start),
+            client.add_stream_end_listener(_handle_stream_end),
+            client.add_stream_clear_listener(_handle_stream_clear),
+            client.add_disconnect_listener(_handle_disconnect),
+            client.add_server_command_listener(_handle_server_command),
+        ]
+
+    def _activate_sendspin_client(self, client: SendspinClient, *, server_url: str | None) -> None:
+        self._remove_sendspin_listeners()
+        self._sendspin_client = client
+        self._sendspin_url = server_url
+        self._sendspin_enabled = True
+        self._sendspin_remote_volume = max(0, min(100, round(self._unduck_volume * 100.0)))
+        self._register_sendspin_listeners(client)
+        self._ensure_sendspin_worker()
+
+    def _on_sendspin_disconnected(self, client: SendspinClient) -> None:
+        if self._sendspin_client is not client:
+            return
+        _LOGGER.info("Sendspin disconnected")
+        self._remove_sendspin_listeners()
+        self._sendspin_enabled = False
+        self._sendspin_client = None
+        self._sendspin_url = None
+        self._sendspin_stream_active = False
+        self._reset_sendspin_stream_state(stop_output=True)
+
+    def pause_sendspin(self) -> None:
+        if self._sendspin_paused and not self._sendspin_stream_active:
+            return
+        self._sendspin_paused = True
+        self._reset_sendspin_stream_state(stop_output=True)
+        _LOGGER.debug("Sendspin audio paused (voice assistant active)")
+
+    def resume_sendspin(self) -> None:
+        if not self._sendspin_paused:
+            return
+        self._sendspin_paused = False
+        self._sendspin_queue_event.set()
+        _LOGGER.debug("Sendspin audio resumed")
+
+    async def _start_sendspin_listener(self) -> None:
+        if ClientListener is None:
+            return
+        if self._sendspin_listener is not None:
+            return
+        self._sendspin_listener = ClientListener(
+            client_id=self._sendspin_client_id,
+            client_name="Reachy Mini",
+            port=SENDSPIN_DEFAULT_PORT,
+            on_connection=self._handle_sendspin_listener_connection,
+        )
+        try:
+            await self._sendspin_listener.start()
+        except Exception:
+            self._sendspin_listener = None
+            raise
+        _LOGGER.info("Sendspin listener started on port %d", self._sendspin_listener.port)
+
+    async def _handle_sendspin_listener_connection(self, ws) -> None:
+        if not SENDSPIN_AVAILABLE:
+            await ws.close()
+            return
+        disconnect_event = asyncio.Event()
+        client = self._build_sendspin_client()
+        async with self._get_sendspin_connect_lock():
+            if self._sendspin_client is not None:
+                await self._disconnect_sendspin()
+            self._activate_sendspin_client(client, server_url=None)
+
+        def _on_disconnect() -> None:
+            disconnect_event.set()
+
+        disconnect_unsub = client.add_disconnect_listener(_on_disconnect)
+        try:
+            await client.attach_websocket(ws)
+            _LOGGER.info("Accepted incoming Sendspin connection")
+            await disconnect_event.wait()
+        except Exception:
+            _LOGGER.exception("Failed to attach incoming Sendspin websocket")
+            async with self._get_sendspin_connect_lock():
+                if self._sendspin_client is client:
+                    await self._disconnect_sendspin()
+            raise
+        finally:
+            try:
+                disconnect_unsub()
+            except Exception:
+                _LOGGER.debug("Failed to remove temporary Sendspin disconnect listener", exc_info=True)
+
+    async def start_sendspin_discovery(self) -> None:
+        if not SENDSPIN_AVAILABLE:
+            _LOGGER.debug("aiosendspin not installed, skipping Sendspin discovery")
+            return
+        if self._sendspin_discovery is not None and self._sendspin_discovery.is_running:
+            _LOGGER.debug("Sendspin discovery already running")
+            return
+        from ..protocol.zeroconf import SendspinDiscovery
+
+        _LOGGER.info("Starting Sendspin server discovery...")
+        self._sendspin_discovery = SendspinDiscovery(self._on_sendspin_server_found, self._on_sendspin_server_removed)
+        await self._sendspin_discovery.start()
+        self._ensure_sendspin_worker()
+        try:
+            await self._start_sendspin_listener()
+        except Exception:
+            _LOGGER.warning(
+                "Sendspin incoming listener unavailable; continuing with discovery/client mode", exc_info=True
+            )
+
+    async def _on_sendspin_server_found(self, server_url: str) -> None:
+        await self._connect_to_server(server_url)
+
+    async def _on_sendspin_server_removed(self, server_url: str) -> None:
+        if self._sendspin_url == server_url:
+            _LOGGER.info("Active Sendspin server disappeared: %s", server_url)
+            await self._disconnect_sendspin()
+
+    async def _connect_to_server(self, server_url: str) -> bool:
+        if not SENDSPIN_AVAILABLE:
+            return False
+        async with self._get_sendspin_connect_lock():
+            if self._sendspin_enabled and self._sendspin_url == server_url and self._sendspin_client is not None:
+                return True
+            if self._sendspin_client is not None:
+                await self._disconnect_sendspin()
+            client = self._build_sendspin_client()
+            try:
+                await client.connect(server_url)
+            except Exception:
+                _LOGGER.exception("Failed to connect to Sendspin server %s", server_url)
+                try:
+                    await client.disconnect()
+                except Exception:
+                    _LOGGER.debug("Failed to clean up Sendspin client after connect error", exc_info=True)
+                return False
+            self._activate_sendspin_client(client, server_url=server_url)
+            _LOGGER.info("Sendspin connected as PLAYER: %s (client_id=%s)", server_url, self._sendspin_client_id)
+            return True
+
+    def _on_sendspin_audio_chunk(
+        self, client: SendspinClient, server_timestamp_us: int, audio_data: bytes, fmt: AudioFormat
+    ) -> None:
+        if self._sendspin_client is not client or self._sendspin_paused or self.reachy_mini is None:
+            return
+        try:
+            play_time_us = int(client.compute_play_time(server_timestamp_us))
+            now_us = time.monotonic_ns() // 1000
+            play_time_us = min(play_time_us, now_us + SENDSPIN_SCHEDULE_AHEAD_LIMIT_US)
+            if self._should_backpressure_sendspin_chunk(play_time_us, len(audio_data)):
+                return
+
+            self._sendspin_audio_format = fmt
+            audio_float = self._decode_sendspin_audio(audio_data, fmt)
+            sway_sample_rate = self.reachy_mini.media.get_output_audio_samplerate()
+            if sway_sample_rate <= 0:
+                sway_sample_rate = fmt.pcm_format.sample_rate
+            self._queue_sendspin_audio(play_time_us, audio_float, len(audio_data))
+            self._queue_sendspin_sway(play_time_us, audio_float, sway_sample_rate)
+        except Exception:
+            _LOGGER.exception("Error handling Sendspin audio chunk")
+
+    def _on_sendspin_stream_start(self, client: SendspinClient, message: StreamStartMessage) -> None:
+        if self._sendspin_client is not client:
+            return
+        self._sendspin_stream_active = True
+        self._reset_sendspin_stream_state(stop_output=True)
+        player = getattr(message.payload, "player", None)
+        if player is None:
+            _LOGGER.debug("Sendspin stream started without player payload")
+            return
+        _LOGGER.info(
+            "Sendspin stream started: codec=%s sample_rate=%s channels=%s bit_depth=%s",
+            getattr(player.codec, "value", player.codec),
+            player.sample_rate,
+            player.channels,
+            player.bit_depth,
+        )
+
+    def _on_sendspin_stream_end(self, client: SendspinClient, roles: list[str] | None) -> None:
+        if self._sendspin_client is not client:
+            return
+        if roles is None or "player" in roles:
+            self._sendspin_stream_active = False
+            self._reset_sendspin_stream_state(stop_output=True)
+            _LOGGER.debug("Sendspin stream ended")
+
+    def _on_sendspin_stream_clear(self, client: SendspinClient, roles: list[str] | None) -> None:
+        if self._sendspin_client is not client:
+            return
+        if roles is None or "player" in roles:
+            _LOGGER.debug("Sendspin stream cleared")
+            self._reset_sendspin_stream_state(stop_output=True)
+
+    def _on_sendspin_server_command(self, client: SendspinClient, payload) -> None:
+        if self._sendspin_client is not client:
+            return
+        player_payload = getattr(payload, "player", None)
+        if player_payload is None:
+            return
+        try:
+            if player_payload.command == PlayerCommand.VOLUME and player_payload.volume is not None:
+                self._sendspin_remote_volume = max(0, min(100, int(player_payload.volume)))
+                _LOGGER.debug("Sendspin remote volume set to %d", self._sendspin_remote_volume)
+            elif player_payload.command == PlayerCommand.MUTE and player_payload.mute is not None:
+                self._sendspin_muted = bool(player_payload.mute)
+                if self._sendspin_muted:
+                    self._reset_sendspin_stream_state(stop_output=True)
+                _LOGGER.debug("Sendspin remote mute set to %s", self._sendspin_muted)
+        except Exception:
+            _LOGGER.exception("Failed to handle Sendspin server command")
+
+    async def _disconnect_sendspin(self) -> None:
+        client = self._sendspin_client
+        self._remove_sendspin_listeners()
+        if client is not None:
+            try:
+                await client.disconnect()
+            except Exception:
+                _LOGGER.debug("Error disconnecting from Sendspin", exc_info=True)
+        self._sendspin_client = None
+        self._sendspin_enabled = False
+        self._sendspin_url = None
+        self._sendspin_stream_active = False
+        self._reset_sendspin_stream_state(stop_output=True)
+
+    async def stop_sendspin(self) -> None:
+        if self._sendspin_discovery is not None:
+            await self._sendspin_discovery.stop()
+            self._sendspin_discovery = None
+        if self._sendspin_listener is not None:
+            await self._sendspin_listener.stop()
+            self._sendspin_listener = None
+        await self._disconnect_sendspin()
+        self._sendspin_client = None
+        self._sendspin_url = None
+        self._sendspin_audio_format = None
+        self._sendspin_enabled = False
+        self._sendspin_stream_active = False
+        self._sendspin_paused = False
+        self._sendspin_muted = False
+        self._sendspin_remote_volume = 100
+        self._stop_sendspin_worker()
+        _LOGGER.info("Sendspin stopped")

reachy_mini_home_assistant/audio/audio_player_shared.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import hashlib
+import logging
+import socket
+import time
+from urllib.parse import urlparse, urlunparse
+
+import numpy as np
+
+_LOGGER = logging.getLogger(__name__)
+
+MOVEMENT_LATENCY_S = 0.2
+SWAY_FRAME_DT_S = 0.05
+STREAM_FETCH_CHUNK_SIZE = 2048
+UNTHROTTLED_PREROLL_S = 0.35
+SENDSPIN_LOCAL_BUFFER_CAPACITY_BYTES = 32_000_000
+SENDSPIN_HIGH_WATERMARK_BYTES = 24_000_000
+SENDSPIN_LATE_DROP_GRACE_US = 150_000
+SENDSPIN_SCHEDULE_AHEAD_LIMIT_US = 2_000_000
+
+
+def sniff_audio_content_type(audio_bytes: bytes) -> str:
+    if len(audio_bytes) >= 12:
+        if audio_bytes.startswith(b"RIFF") and audio_bytes[8:12] == b"WAVE":
+            return "audio/wav"
+        if audio_bytes.startswith(b"fLaC"):
+            return "audio/flac"
+        if audio_bytes.startswith(b"OggS"):
+            return "audio/ogg"
+        if audio_bytes[:4] == b"ID3":
+            return "audio/mpeg"
+        if audio_bytes[:2] == b"\xff\xfb" or audio_bytes[:2] == b"\xff\xf3" or audio_bytes[:2] == b"\xff\xf2":
+            return "audio/mpeg"
+        if audio_bytes[:4] == b"ADIF" or (audio_bytes[0] == 0xFF and (audio_bytes[1] & 0xF0) == 0xF0):
+            return "audio/aac"
+        if audio_bytes[4:8] == b"ftyp":
+            return "audio/mp4"
+        if audio_bytes.startswith(b"\x1aE\xdf\xa3"):
+            return "audio/webm"
+    return ""
+
+
+def rewrite_local_service_url(url: str, host_override: str | None) -> str:
+    if not host_override:
+        return url
+    try:
+        parsed = urlparse(url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            return url
+        hostname = (parsed.hostname or "").lower()
+        if hostname not in {"localhost", "127.0.0.1", "::1", "homeassistant.local", "homeassistant"}:
+            return url
+        netloc = host_override
+        if parsed.port is not None:
+            netloc = f"{host_override}:{parsed.port}"
+        return urlunparse(parsed._replace(netloc=netloc))
+    except Exception:
+        return url
+
+
+class AudioPlayerSwayMixin:
+    def _new_sway_analyzer(self):
+        try:
+            from ..motion.speech_sway import SpeechSwayRT
+
+            return SpeechSwayRT()
+        except Exception:
+            return None
+
+    def _compute_sway_frames(self, analyzer, pcm: np.ndarray, sample_rate: int) -> list[dict]:
+        if analyzer is None:
+            return []
+        try:
+            return analyzer.feed(pcm, sample_rate) or []
+        except Exception:
+            return []
+
+    def _reset_sway_output(self) -> None:
+        if getattr(self, "_sway_callback", None) is None:
+            return
+        try:
+            self._sway_callback({"pitch_rad": 0.0, "yaw_rad": 0.0, "roll_rad": 0.0, "x_m": 0.0, "y_m": 0.0, "z_m": 0.0})
+        except Exception:
+            pass
+
+    def _init_stream_sway_context(self) -> dict | None:
+        if getattr(self, "_sway_callback", None) is None:
+            return None
+        analyzer = self._new_sway_analyzer()
+        if analyzer is None:
+            return None
+        return {"sway": analyzer, "base_ts": time.monotonic(), "frames_done": 0}
+
+    def _feed_stream_sway(self, ctx: dict | None, pcm: np.ndarray, sample_rate: int) -> None:
+        if ctx is None or getattr(self, "_sway_callback", None) is None:
+            return
+        try:
+            results = self._compute_sway_frames(ctx["sway"], pcm, sample_rate)
+            if not results:
+                return
+            base_ts = float(ctx["base_ts"])
+            for item in results:
+                target = base_ts + MOVEMENT_LATENCY_S + ctx["frames_done"] * SWAY_FRAME_DT_S
+                now = time.monotonic()
+                if target > now:
+                    time.sleep(min(0.02, target - now))
+                self._sway_callback(item)
+                ctx["frames_done"] += 1
+        except Exception:
+            pass
+
+    def _finalize_stream_sway(self, ctx: dict | None) -> None:
+        if ctx is None or getattr(self, "_sway_callback", None) is None:
+            return
+        self._reset_sway_output()
+
+
+def get_stable_client_id() -> str:
+    try:
+        hostname = socket.gethostname()
+        hash_input = f"reachy-mini-{hostname}"
+        return hashlib.sha256(hash_input.encode()).hexdigest()[:16]
+    except Exception:
+        return "reachy-mini-default"

reachy_mini_home_assistant/audio/audio_player_stream_decoded.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import threading
+import time
+
+import numpy as np
+
+from .audio_player_shared import STREAM_FETCH_CHUNK_SIZE, UNTHROTTLED_PREROLL_S, _LOGGER
+
+
+class AudioPlayerStreamDecodedMixin:
+    @staticmethod
+    def _guess_gst_input_caps(content_type: str) -> str | None:
+        ct = (content_type or "").split(";", 1)[0].strip().lower()
+        mapping = {
+            "audio/mpeg": "audio/mpeg,mpegversion=(int)1",
+            "audio/mp3": "audio/mpeg,mpegversion=(int)1",
+            "audio/aac": "audio/mpeg,mpegversion=(int)4,stream-format=(string)raw",
+            "audio/mp4": "audio/mpeg,mpegversion=(int)4,stream-format=(string)raw",
+            "audio/ogg": "application/ogg",
+            "application/ogg": "application/ogg",
+            "audio/opus": "audio/x-opus",
+            "audio/webm": "video/webm",
+            "audio/wav": "audio/x-wav",
+            "audio/wave": "audio/x-wav",
+            "audio/x-wav": "audio/x-wav",
+            "audio/flac": "audio/x-flac",
+            "audio/x-flac": "audio/x-flac",
+        }
+        return mapping.get(ct)
+
+    def _stream_decoded_response(self, response, source_url: str, content_type: str) -> bool:
+        try:
+            import gi
+
+            gi.require_version("Gst", "1.0")
+            from gi.repository import Gst
+        except Exception:
+            return False
+        try:
+            Gst.init(None)
+        except Exception:
+            pass
+        target_sr = self.reachy_mini.media.get_output_audio_samplerate()
+        if target_sr <= 0:
+            target_sr = 16000
+        target_channels = 1
+        if not self._ensure_media_playback_started():
+            return False
+        pipeline = Gst.Pipeline.new("tts_stream_decode")
+        appsrc = Gst.ElementFactory.make("appsrc", "src")
+        decodebin = Gst.ElementFactory.make("decodebin", "decode")
+        audioconvert = Gst.ElementFactory.make("audioconvert", "conv")
+        audioresample = Gst.ElementFactory.make("audioresample", "resample")
+        capsfilter = Gst.ElementFactory.make("capsfilter", "caps")
+        appsink = Gst.ElementFactory.make("appsink", "sink")
+        if not all((pipeline, appsrc, decodebin, audioconvert, audioresample, capsfilter, appsink)):
+            return False
+        target_caps = Gst.Caps.from_string(f"audio/x-raw,format=S16LE,channels={target_channels},rate={target_sr}")
+        capsfilter.set_property("caps", target_caps)
+        appsrc.set_property("is-live", True)
+        appsrc.set_property("format", Gst.Format.BYTES)
+        appsrc.set_property("block", False)
+        appsrc.set_property("do-timestamp", True)
+        src_caps = self._guess_gst_input_caps(content_type)
+        if src_caps:
+            try:
+                appsrc.set_property("caps", Gst.Caps.from_string(src_caps))
+            except Exception:
+                pass
+        try:
+            decodebin.set_property("caps", Gst.Caps.from_string("audio/x-raw"))
+        except Exception:
+            pass
+        appsink.set_property("emit-signals", False)
+        appsink.set_property("sync", False)
+        appsink.set_property("max-buffers", 0)
+        appsink.set_property("drop", False)
+        pipeline.add(appsrc)
+        pipeline.add(decodebin)
+        pipeline.add(audioconvert)
+        pipeline.add(audioresample)
+        pipeline.add(capsfilter)
+        pipeline.add(appsink)
+        if (
+            not appsrc.link(decodebin)
+            or not audioconvert.link(audioresample)
+            or not audioresample.link(capsfilter)
+            or not capsfilter.link(appsink)
+        ):
+            return False
+        audio_state = {"linked": False}
+
+        def on_pad_added(_decodebin, pad) -> None:
+            sink_pad = audioconvert.get_static_pad("sink")
+            if sink_pad is None or sink_pad.is_linked():
+                return
+            caps_obj = pad.get_current_caps() or pad.query_caps(None)
+            if caps_obj is None:
+                return
+            if caps_obj.to_string().startswith("audio/"):
+                try:
+                    result = pad.link(sink_pad)
+                    if result == Gst.PadLinkReturn.OK:
+                        audio_state["linked"] = True
+                except Exception:
+                    pass
+
+        decodebin.connect("pad-added", on_pad_added)
+        pushed_any = False
+        played_frames = 0
+        stream_start = time.monotonic()
+        sway_ctx = self._init_stream_sway_context()
+        bytes_per_frame = 2 * target_channels
+        feed_done = threading.Event()
+        decode_error = False
+
+        def writer() -> None:
+            try:
+                for chunk in response.iter_content(chunk_size=STREAM_FETCH_CHUNK_SIZE):
+                    if self._stop_flag.is_set():
+                        break
+                    if not chunk:
+                        continue
+                    gst_buffer = Gst.Buffer.new_allocate(None, len(chunk), None)
+                    if gst_buffer is None:
+                        continue
+                    gst_buffer.fill(0, chunk)
+                    ret = appsrc.emit("push-buffer", gst_buffer)
+                    if ret not in (Gst.FlowReturn.OK, Gst.FlowReturn.FLUSHING):
+                        _LOGGER.debug("appsrc push-buffer returned %s", ret)
+                        break
+            except Exception:
+                pass
+            finally:
+                feed_done.set()
+                try:
+                    appsrc.emit("end-of-stream")
+                except Exception:
+                    pass
+
+        try:
+            state_ret = pipeline.set_state(Gst.State.PLAYING)
+            if state_ret == Gst.StateChangeReturn.FAILURE:
+                _LOGGER.debug("Failed to set GStreamer decode pipeline PLAYING for URL=%s", source_url)
+                return False
+            writer_thread = threading.Thread(target=writer, daemon=True)
+            writer_thread.start()
+            remainder = b""
+            timeout_ns = 20_000_000
+            bus = pipeline.get_bus()
+            eos_seen = False
+            eos_drain_empty_polls = 0
+            while True:
+                sample = appsink.emit("try-pull-sample", timeout_ns)
+                if sample is not None:
+                    eos_drain_empty_polls = 0
+                    try:
+                        gst_buffer = sample.get_buffer()
+                        if gst_buffer is None:
+                            continue
+                        ok, map_info = gst_buffer.map(Gst.MapFlags.READ)
+                        if not ok:
+                            continue
+                        try:
+                            raw = bytes(map_info.data)
+                        finally:
+                            gst_buffer.unmap(map_info)
+                        data = remainder + raw
+                        usable_len = (len(data) // bytes_per_frame) * bytes_per_frame
+                        remainder = data[usable_len:]
+                        if usable_len == 0:
+                            continue
+                        pcm = np.frombuffer(data[:usable_len], dtype=np.int16).astype(np.float32) / 32768.0
+                        pcm = np.clip(pcm * self._current_volume, -1.0, 1.0).reshape(-1, target_channels)
+                        target_elapsed = played_frames / float(target_sr)
+                        actual_elapsed = time.monotonic() - stream_start
+                        if target_elapsed > UNTHROTTLED_PREROLL_S and target_elapsed > actual_elapsed:
+                            time.sleep(min(0.05, target_elapsed - actual_elapsed))
+                        if not self._push_audio_float(pcm):
+                            continue
+                        pushed_any = True
+                        played_frames += int(pcm.shape[0])
+                        self._feed_stream_sway(sway_ctx, pcm, target_sr)
+                    finally:
+                        sample = None
+                elif eos_seen and feed_done.is_set():
+                    eos_drain_empty_polls += 1
+                msg = bus.timed_pop_filtered(0, Gst.MessageType.ERROR | Gst.MessageType.EOS)
+                if msg is not None:
+                    if msg.type == Gst.MessageType.EOS:
+                        eos_seen = True
+                    elif msg.type == Gst.MessageType.ERROR:
+                        err, debug = msg.parse_error()
+                        err_text = str(err).lower()
+                        debug_text = str(debug).lower() if debug is not None else ""
+                        if audio_state["linked"] and (
+                            "not-linked" in err_text
+                            or "not-linked" in debug_text
+                            or "streaming stopped, reason not-linked" in debug_text
+                        ):
+                            continue
+                        decode_error = True
+                        _LOGGER.debug(
+                            "GStreamer decode error content-type=%s url=%s err=%s debug=%s",
+                            content_type or "unknown",
+                            source_url,
+                            err,
+                            debug,
+                        )
+                        break
+                if feed_done.is_set() and eos_seen:
+                    sink_eos = False
+                    try:
+                        sink_eos = bool(appsink.is_eos())
+                    except Exception:
+                        sink_eos = False
+                    if sink_eos and eos_drain_empty_polls >= 2:
+                        break
+                    if eos_drain_empty_polls >= 100:
+                        break
+                if self._stop_flag.is_set():
+                    break
+            writer_thread.join(timeout=1.0)
+            if self._stop_flag.is_set():
+                return True
+            if decode_error:
+                return False
+            if pushed_any:
+                return True
+            completed_cleanly = feed_done.is_set() and eos_seen
+            if not completed_cleanly:
+                return False
+        except Exception as e:
+            _LOGGER.debug("Error during GStreamer stream decode: %s", e)
+            pushed_any = False
+        finally:
+            self._finalize_stream_sway(sway_ctx)
+            try:
+                pipeline.set_state(Gst.State.NULL)
+            except Exception:
+                pass
+        return pushed_any

reachy_mini_home_assistant/audio/audio_player_stream_pcm.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import time
+
+import numpy as np
+
+from .audio_player_shared import STREAM_FETCH_CHUNK_SIZE, UNTHROTTLED_PREROLL_S
+
+
+class AudioPlayerStreamPCMMixin:
+    @staticmethod
+    def _is_pcm_content_type(content_type: str) -> bool:
+        return ("audio/l16" in content_type) or ("audio/pcm" in content_type) or ("audio/raw" in content_type)
+
+    @staticmethod
+    def _parse_pcm_format(content_type: str) -> tuple[int, int]:
+        channels = 1
+        sample_rate = 16000
+        if ";" in content_type:
+            for part in content_type.split(";"):
+                token = part.strip()
+                if token.startswith("channels="):
+                    try:
+                        channels = max(1, int(token.split("=", 1)[1]))
+                    except Exception:
+                        pass
+                elif token.startswith("rate="):
+                    try:
+                        sample_rate = max(8000, int(token.split("=", 1)[1]))
+                    except Exception:
+                        pass
+        return channels, sample_rate
+
+    def _ensure_media_playback_started(self) -> bool:
+        acquired = self._gstreamer_lock.acquire(timeout=0.3)
+        if not acquired:
+            return False
+        try:
+            self.reachy_mini.media.start_playing()
+            return True
+        except Exception:
+            return False
+        finally:
+            self._gstreamer_lock.release()
+
+    def _push_audio_float(self, audio_float: np.ndarray, max_wait_s: float = 1.0) -> bool:
+        deadline = time.monotonic() + max(0.05, max_wait_s)
+        while time.monotonic() < deadline:
+            if self._stop_flag.is_set():
+                return False
+            acquired = self._gstreamer_lock.acquire(timeout=0.1)
+            if not acquired:
+                continue
+            try:
+                self.reachy_mini.media.push_audio_sample(audio_float)
+                return True
+            finally:
+                self._gstreamer_lock.release()
+        return False
+
+    def _stream_pcm_response(self, response, content_type: str) -> bool:
+        channels, sample_rate = self._parse_pcm_format(content_type)
+        target_sr = self.reachy_mini.media.get_output_audio_samplerate()
+        if target_sr <= 0:
+            target_sr = 16000
+        if not self._ensure_media_playback_started():
+            return False
+        remainder = b""
+        pushed_any = False
+        played_frames = 0
+        stream_start = time.monotonic()
+        sway_ctx = self._init_stream_sway_context()
+        bytes_per_frame = 2 * channels
+        for chunk in response.iter_content(chunk_size=STREAM_FETCH_CHUNK_SIZE):
+            if self._stop_flag.is_set():
+                break
+            if not chunk:
+                continue
+            data = remainder + chunk
+            usable_len = (len(data) // bytes_per_frame) * bytes_per_frame
+            remainder = data[usable_len:]
+            if usable_len == 0:
+                continue
+            pcm = np.frombuffer(data[:usable_len], dtype=np.int16).astype(np.float32) / 32768.0
+            pcm = np.clip(pcm * self._current_volume, -1.0, 1.0).reshape(-1, channels)
+            if sample_rate != target_sr and target_sr > 0:
+                import scipy.signal
+
+                new_len = int(len(pcm) * target_sr / sample_rate)
+                if new_len > 0:
+                    pcm = scipy.signal.resample(pcm, new_len, axis=0).astype(np.float32, copy=False)
+            target_elapsed = played_frames / float(target_sr)
+            actual_elapsed = time.monotonic() - stream_start
+            if target_elapsed > UNTHROTTLED_PREROLL_S and target_elapsed > actual_elapsed:
+                time.sleep(min(0.05, target_elapsed - actual_elapsed))
+            if not self._push_audio_float(pcm):
+                continue
+            pushed_any = True
+            played_frames += int(pcm.shape[0])
+            self._feed_stream_sway(sway_ctx, pcm, target_sr)
+        self._finalize_stream_sway(sway_ctx)
+        return pushed_any

reachy_mini_home_assistant/audio/audio_player_wobble.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .audio_player_shared import AudioPlayerSwayMixin
+
+
+class AudioPlayerWobbleMixin(AudioPlayerSwayMixin):
+    pass

reachy_mini_home_assistant/audio/doa_tracker.py

@@ -0,0 +1,198 @@
+"""Direction of Arrival (DOA) sound localization tracker.
+
+This module implements sound source tracking using the microphone array's
+DOA (Direction of Arrival) data to make the robot turn towards sounds
+when idle.
+"""
+
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DOAConfig:
+    """Configuration for DOA tracking behavior."""
+
+    # Minimum energy threshold to consider a sound significant
+    energy_threshold: float = 0.3
+
+    # Minimum angle change (degrees) to trigger a turn
+    angle_threshold_deg: float = 15.0
+
+    # Cooldown time (seconds) before responding to same direction
+    direction_cooldown: float = 5.0
+
+    # Duration of turn animation (seconds)
+    turn_duration: float = 1.5
+
+    # Number of direction zones for cooldown tracking
+    num_zones: int = 8
+
+    # Maximum turn angle (degrees)
+    max_turn_angle_deg: float = 60.0
+
+    # Minimum time between any turns (seconds)
+    min_turn_interval: float = 2.0
+
+
+class DOATracker:
+    """Tracks sound direction and triggers head turns when idle.
+
+    This class monitors DOA (Direction of Arrival) data from the microphone
+    array and triggers smooth head turns towards sound sources when the
+    robot is idle and not tracking a face.
+
+    Usage:
+        tracker = DOATracker(movement_callback=robot.turn_to_angle)
+
+        # In audio processing loop:
+        tracker.update(doa_angle=45.0, energy=0.5)
+    """
+
+    def __init__(
+        self,
+        movement_callback: Callable[[float, float], None] | None = None,
+        config: DOAConfig | None = None,
+    ):
+        """Initialize the DOA tracker.
+
+        Args:
+            movement_callback: Function to call for turning.
+                               Signature: (yaw_degrees, duration) -> None
+            config: DOA tracking configuration
+        """
+        self._movement_callback = movement_callback
+        self._config = config or DOAConfig()
+
+        # State
+        self._enabled = True
+        self._face_detected = False
+        self._in_conversation = False
+        self._last_angle: float = 0.0
+        self._last_turn_time: float = 0.0
+
+        # Zone-based cooldown tracking
+        self._zone_cooldowns: dict[int, float] = {}
+
+        # Time function
+        self._now = time.monotonic
+
+    @property
+    def enabled(self) -> bool:
+        """Check if DOA tracking is enabled."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        """Enable or disable DOA tracking."""
+        self._enabled = value
+        if value:
+            logger.debug("DOA tracking enabled")
+        else:
+            logger.debug("DOA tracking disabled")
+
+    def set_face_detected(self, detected: bool) -> None:
+        """Update face detection state.
+
+        DOA tracking is suppressed when a face is detected.
+        """
+        self._face_detected = detected
+
+    def set_conversation_mode(self, in_conversation: bool) -> None:
+        """Update conversation mode state.
+
+        DOA tracking is suppressed during conversation.
+        """
+        self._in_conversation = in_conversation
+
+    def set_movement_callback(self, callback: Callable[[float, float], None]) -> None:
+        """Set the movement callback function.
+
+        Args:
+            callback: Function(yaw_degrees, duration) to call for turning
+        """
+        self._movement_callback = callback
+
+    def update(self, doa_angle: float, energy: float) -> bool:
+        """Process DOA data and trigger turn if appropriate.
+
+        Args:
+            doa_angle: Direction of arrival in degrees (-180 to 180)
+            energy: Sound energy level (0 to 1)
+
+        Returns:
+            True if a turn was triggered, False otherwise
+        """
+        # Check if tracking should be active
+        if not self._should_track():
+            return False
+
+        # Check energy threshold
+        if energy < self._config.energy_threshold:
+            return False
+
+        # Check angle change threshold
+        angle_diff = abs(doa_angle - self._last_angle)
+        if angle_diff < self._config.angle_threshold_deg:
+            return False
+
+        # Check minimum turn interval
+        now = self._now()
+        if now - self._last_turn_time < self._config.min_turn_interval:
+            return False
+
+        # Check zone cooldown
+        zone = self._get_zone(doa_angle)
+        zone_last_time = self._zone_cooldowns.get(zone, 0)
+        if now - zone_last_time < self._config.direction_cooldown:
+            logger.debug(f"DOA zone {zone} in cooldown")
+            return False
+
+        # Clamp angle
+        clamped_angle = max(-self._config.max_turn_angle_deg, min(self._config.max_turn_angle_deg, doa_angle))
+
+        # Trigger turn
+        if self._movement_callback:
+            logger.info(f"DOA turn triggered: {clamped_angle:.1f}° (energy={energy:.2f})")
+            self._movement_callback(clamped_angle, self._config.turn_duration)
+
+            # Update state
+            self._last_angle = doa_angle
+            self._last_turn_time = now
+            self._zone_cooldowns[zone] = now
+
+            return True
+
+        return False
+
+    def _should_track(self) -> bool:
+        """Check if DOA tracking should be active."""
+        if not self._enabled:
+            return False
+
+        if self._face_detected:
+            return False
+
+        return not self._in_conversation
+
+    def _get_zone(self, angle: float) -> int:
+        """Get the direction zone for an angle.
+
+        Divides the 360° space into zones for cooldown tracking.
+        """
+        # Normalize to 0-360
+        normalized = (angle + 180) % 360
+
+        # Calculate zone
+        zone_size = 360 / self._config.num_zones
+        return int(normalized / zone_size)
+
+    def reset_cooldowns(self) -> None:
+        """Reset all zone cooldowns."""
+        self._zone_cooldowns.clear()
+        self._last_turn_time = 0.0
+        logger.debug("DOA cooldowns reset")

reachy_mini_home_assistant/audio/local_audio_player.py

@@ -0,0 +1,39 @@
+"""Local-only audio player for TTS and announcements."""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+
+from .audio_player_playback import AudioPlayerPlaybackMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+class LocalAudioPlayer(AudioPlayerPlaybackMixin):
+    """Audio player for local/TTS playback without Sendspin runtime state."""
+
+    def __init__(self, reachy_mini=None, gstreamer_lock=None) -> None:
+        self.reachy_mini = reachy_mini
+        self._gstreamer_lock = gstreamer_lock if gstreamer_lock is not None else threading.Lock()
+        self.is_playing = False
+        self._playlist: list[str] = []
+        self._done_callback: Callable[[], None] | 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()
+        self._playback_thread: threading.Thread | None = None
+        self._sway_callback: Callable[[dict], None] | None = None
+        self._http_host_override: str | None = None
+
+    def set_sway_callback(self, callback: Callable[[dict], None] | None) -> None:
+        self._sway_callback = callback
+
+    def set_reachy_mini(self, reachy_mini) -> None:
+        self.reachy_mini = reachy_mini
+
+    def set_http_host_override(self, host: str | None) -> None:
+        self._http_host_override = host

reachy_mini_home_assistant/core/__init__.py

@@ -0,0 +1,47 @@
+"""Core module for Reachy Mini HA Voice.
+
+This module contains fundamental components:
+- SleepAwareService: Base class for services that support resource suspend/resume
+- ServiceManager: Manages multiple suspend-aware services
+- Config: Centralized configuration management
+- Exceptions: Custom exception classes
+- SystemDiagnostics: System diagnostics utilities
+- Util: Common utility functions
+"""
+
+from .config import Config
+from .exceptions import (
+    ConfigurationError,
+    DaemonUnavailableError,
+    EntityRegistrationError,
+    ModelLoadError,
+    ReachyHAError,
+    ResourceUnavailableError,
+    RobotConnectionError,
+    ServiceSuspendedError,
+)
+from .service_base import RobustOperationMixin, ServiceManager, ServiceState, SleepAwareService
+from .system_diagnostics import get_system_diagnostics
+from .util import call_all, get_mac
+
+__all__ = [
+    "Config",
+    "ConfigurationError",
+    "DaemonUnavailableError",
+    "EntityRegistrationError",
+    "ModelLoadError",
+    # Exceptions
+    "ReachyHAError",
+    "ResourceUnavailableError",
+    "RobotConnectionError",
+    "RobustOperationMixin",
+    "ServiceManager",
+    "ServiceState",
+    "ServiceSuspendedError",
+    "SleepAwareService",
+    "call_all",
+    # Utilities
+    "get_mac",
+    # System diagnostics
+    "get_system_diagnostics",
+]

reachy_mini_home_assistant/core/config.py

@@ -0,0 +1,435 @@
+"""Centralized configuration for Reachy Mini HA Voice.
+
+This module provides a single source of truth for all configurable values,
+organized by subsystem. Values can be overridden via environment variables
+or a configuration file.
+
+Usage:
+    from core.config import Config
+
+    # Access configuration
+    port = Config.ESPHOME_PORT
+    fps = Config.CAMERA_FPS
+
+    # Or use grouped access
+    camera_cfg = Config.camera
+    fps = camera_cfg.fps
+"""
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _env_bool(key: str, default: bool) -> bool:
+    """Get boolean from environment variable."""
+    val = os.environ.get(key, "").lower()
+    if val in ("true", "1", "yes", "on"):
+        return True
+    if val in ("false", "0", "no", "off"):
+        return False
+    return default
+
+
+def _env_float(key: str, default: float) -> float:
+    """Get float from environment variable."""
+    try:
+        return float(os.environ.get(key, default))
+    except (ValueError, TypeError):
+        return default
+
+
+def _env_int(key: str, default: int) -> int:
+    """Get int from environment variable."""
+    try:
+        return int(os.environ.get(key, default))
+    except (ValueError, TypeError):
+        return default
+
+
+@dataclass
+class DaemonConfig:
+    """Configuration for daemon monitoring."""
+
+    url: str = "http://127.0.0.1:8000"
+    check_interval_active: float = 2.0  # seconds
+    check_interval_sleep: float = 8.0  # seconds
+    check_interval_error: float = 6.0  # seconds
+    max_backoff_interval: float = 15.0  # seconds
+    backoff_multiplier: float = 1.5
+    backoff_error_threshold: int = 2
+    status_cache_ttl: float = 2.0  # seconds
+    volume_cache_ttl: float = 3.0  # seconds
+
+
+@dataclass
+class ESPHomeConfig:
+    """Configuration for ESPHome protocol server."""
+
+    port: int = 6053
+    device_name: str = "reachy-mini"
+    friendly_name: str = "Reachy Mini"
+
+
+@dataclass
+class CameraConfig:
+    """Configuration for camera and video streaming."""
+
+    # HTTP server
+    port: int = 8081
+
+    # Frame capture
+    fps_high: int = 15  # Active mode: smooth face tracking
+    fps_low: int = 10  # Low power: periodic face check
+    fps_idle: float = 5  # Ultra-low power: minimal CPU
+
+    # JPEG encoding
+    quality: int = 80
+
+    # Face tracking runtime tuning
+    face_confidence_threshold: float = 0.5  # Min confidence for face detection (0.3 too low, causes false positives)
+    face_lost_delay: float = 2.0  # Wait before returning to neutral
+    interpolation_duration: float = 1.0  # Time to return to neutral
+    offset_scale: float = 0.6  # Face offset multiplier
+
+    # Power management
+    low_power_threshold: float = 5.0  # Seconds without face -> low power
+    idle_threshold: float = 30.0  # Seconds without face -> idle
+
+    # Gesture detection runtime tuning
+    gesture_detection_interval: int = 1  # Run every frame for maximum gesture responsiveness
+
+
+@dataclass
+class MotionConfig:
+    """Configuration for motion control."""
+
+    # Control loop
+    control_rate_hz: float = 100.0
+    control_interval: float = 0.01  # 1 / control_rate_hz
+    max_send_rate_hz: float = 15.0  # Hard cap for set_target send rate
+    idle_heartbeat_interval_s: float = 1.0  # Keepalive interval when pose unchanged
+
+    # Face tracking
+    face_detected_threshold: float = 0.001  # Min offset to consider face detected
+
+    # Idle behavior
+    idle_look_around_min_interval: float = 8.0  # Min seconds between look-arounds
+    idle_look_around_max_interval: float = 20.0  # Max seconds between look-arounds
+    idle_inactivity_threshold: float = 5.0  # Seconds before look-around starts
+
+    # Animation
+    animation_fps: float = 30.0
+
+    # Smoothing
+    default_transition_duration: float = 0.3  # seconds
+    body_yaw_max_rate_deg_s: float = 85.0  # Faster body follow for smoother head/body coherence
+    body_yaw_deadband_rad: float = 0.0015  # Smaller deadband reduces visible stepwise catch-up
+    body_yaw_min_send_interval_s: float = 0.05  # Min interval for yaw updates
+
+    # Connection recovery backoff for set_target
+    reconnect_backoff_initial_s: float = 2.0
+    reconnect_backoff_max_s: float = 60.0
+    reconnect_backoff_multiplier: float = 2.0
+
+
+@dataclass
+class AudioConfig:
+    """Configuration for audio processing."""
+
+    # Audio format
+    sample_rate: int = 16000
+    channels: int = 1
+
+    # Buffering
+    block_size: int = 1024  # samples
+    max_buffer_size: int = 10240  # samples (10 blocks)
+
+    # Idle pacing
+    idle_sleep_active: float = 0.01  # seconds
+    idle_sleep_sleeping: float = 0.1  # seconds
+
+
+@dataclass
+class DOAConfig:
+    """Configuration for Direction of Arrival (DOA) sound tracking."""
+
+    # Enable/disable DOA tracking
+    enabled: bool = True
+
+    # Threshold settings
+    energy_threshold: float = 0.3  # Min energy to consider sound significant
+    angle_threshold_deg: float = 15.0  # Min angle change to trigger turn
+
+    # Cooldown timing
+    direction_cooldown: float = 5.0  # Seconds before responding to same direction
+    min_turn_interval: float = 2.0  # Min seconds between any turns
+
+    # Turn behavior
+    turn_duration: float = 1.5  # Duration of turn animation
+    max_turn_angle_deg: float = 60.0  # Maximum turn angle
+
+    # Zone tracking
+    num_zones: int = 8  # Number of direction zones for cooldown
+
+
+@dataclass
+class ShutdownConfig:
+    """Configuration for shutdown behavior."""
+
+    audio_thread_join_timeout: float = 1.0  # seconds
+    camera_stop_timeout: float = 3.0  # seconds
+    server_close_timeout: float = 3.0  # seconds
+    sendspin_stop_timeout: float = 3.0  # seconds
+
+
+@dataclass
+class RobotStateConfig:
+    """Configuration for robot state monitoring."""
+
+    check_interval_active: float = 3.0  # seconds
+    check_interval_sleep: float = 8.0  # seconds
+    check_interval_error: float = 6.0  # seconds
+
+
+@dataclass
+class APIConfig:
+    """Configuration for the HTTP API server."""
+
+    port: int = 8080
+    host: str = "0.0.0.0"
+
+
+class Config:
+    """Centralized configuration access.
+
+    All configuration values are accessible as class attributes.
+    Grouped configs are available via nested dataclasses.
+    """
+
+    # Subsystem configurations
+    daemon: DaemonConfig = DaemonConfig()
+    esphome: ESPHomeConfig = ESPHomeConfig()
+    camera: CameraConfig = CameraConfig()
+    motion: MotionConfig = MotionConfig()
+    audio: AudioConfig = AudioConfig()
+    doa: DOAConfig = DOAConfig()
+    robot_state: RobotStateConfig = RobotStateConfig()
+    shutdown: ShutdownConfig = ShutdownConfig()
+    api: APIConfig = APIConfig()
+
+    _initialized = False
+    _config_file: Path | None = None
+
+    @classmethod
+    def load_from_file(cls, path: Path) -> None:
+        """Load configuration overrides from a JSON file.
+
+        Args:
+            path: Path to the JSON configuration file
+        """
+        if not path.exists():
+            logger.debug(f"Config file not found: {path}")
+            return
+
+        try:
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+
+            cls._apply_overrides(data)
+            cls._config_file = path
+            logger.info(f"Loaded configuration from {path}")
+        except Exception as e:
+            logger.error(f"Failed to load config file: {e}")
+
+    @classmethod
+    def load_from_env(cls) -> None:
+        """Load configuration overrides from environment variables.
+
+        Environment variables follow the pattern: REACHY_<SECTION>_<KEY>
+        Example: REACHY_CAMERA_FPS=30
+        """
+        # Daemon
+        cls.daemon.url = os.environ.get("REACHY_DAEMON_URL", cls.daemon.url)
+        cls.daemon.check_interval_active = _env_float(
+            "REACHY_DAEMON_CHECK_INTERVAL_ACTIVE", cls.daemon.check_interval_active
+        )
+        cls.daemon.check_interval_sleep = _env_float(
+            "REACHY_DAEMON_CHECK_INTERVAL_SLEEP", cls.daemon.check_interval_sleep
+        )
+        cls.daemon.check_interval_error = _env_float(
+            "REACHY_DAEMON_CHECK_INTERVAL_ERROR", cls.daemon.check_interval_error
+        )
+        cls.daemon.max_backoff_interval = _env_float(
+            "REACHY_DAEMON_MAX_BACKOFF_INTERVAL", cls.daemon.max_backoff_interval
+        )
+        cls.daemon.backoff_multiplier = _env_float("REACHY_DAEMON_BACKOFF_MULTIPLIER", cls.daemon.backoff_multiplier)
+        cls.daemon.backoff_error_threshold = _env_int(
+            "REACHY_DAEMON_BACKOFF_ERROR_THRESHOLD", cls.daemon.backoff_error_threshold
+        )
+        cls.daemon.status_cache_ttl = _env_float("REACHY_DAEMON_STATUS_CACHE_TTL", cls.daemon.status_cache_ttl)
+        cls.daemon.volume_cache_ttl = _env_float("REACHY_DAEMON_VOLUME_CACHE_TTL", cls.daemon.volume_cache_ttl)
+
+        # ESPHome
+        cls.esphome.port = _env_int("REACHY_ESPHOME_PORT", cls.esphome.port)
+        cls.esphome.device_name = os.environ.get("REACHY_ESPHOME_DEVICE_NAME", cls.esphome.device_name)
+
+        # Camera
+        cls.camera.port = _env_int("REACHY_CAMERA_PORT", cls.camera.port)
+
+        # Motion
+        cls.motion.control_rate_hz = _env_float("REACHY_MOTION_CONTROL_RATE", cls.motion.control_rate_hz)
+        cls.motion.max_send_rate_hz = _env_float("REACHY_MOTION_MAX_SEND_RATE", cls.motion.max_send_rate_hz)
+        cls.motion.idle_heartbeat_interval_s = _env_float(
+            "REACHY_MOTION_IDLE_HEARTBEAT_INTERVAL", cls.motion.idle_heartbeat_interval_s
+        )
+        cls.motion.reconnect_backoff_initial_s = _env_float(
+            "REACHY_MOTION_RECONNECT_BACKOFF_INITIAL", cls.motion.reconnect_backoff_initial_s
+        )
+        cls.motion.reconnect_backoff_max_s = _env_float(
+            "REACHY_MOTION_RECONNECT_BACKOFF_MAX", cls.motion.reconnect_backoff_max_s
+        )
+        cls.motion.reconnect_backoff_multiplier = _env_float(
+            "REACHY_MOTION_RECONNECT_BACKOFF_MULTIPLIER", cls.motion.reconnect_backoff_multiplier
+        )
+
+        # Audio
+        cls.audio.idle_sleep_active = _env_float("REACHY_AUDIO_IDLE_SLEEP_ACTIVE", cls.audio.idle_sleep_active)
+        cls.audio.idle_sleep_sleeping = _env_float("REACHY_AUDIO_IDLE_SLEEP_SLEEPING", cls.audio.idle_sleep_sleeping)
+
+        # Robot state
+        cls.robot_state.check_interval_active = _env_float(
+            "REACHY_ROBOT_STATE_CHECK_INTERVAL_ACTIVE", cls.robot_state.check_interval_active
+        )
+        cls.robot_state.check_interval_sleep = _env_float(
+            "REACHY_ROBOT_STATE_CHECK_INTERVAL_SLEEP", cls.robot_state.check_interval_sleep
+        )
+        cls.robot_state.check_interval_error = _env_float(
+            "REACHY_ROBOT_STATE_CHECK_INTERVAL_ERROR", cls.robot_state.check_interval_error
+        )
+
+        logger.debug("Loaded configuration from environment")
+
+    @classmethod
+    def _apply_overrides(cls, data: dict) -> None:
+        """Apply configuration overrides from a dictionary."""
+        if "daemon" in data:
+            for key, value in data["daemon"].items():
+                if hasattr(cls.daemon, key):
+                    setattr(cls.daemon, key, value)
+
+        if "esphome" in data:
+            for key, value in data["esphome"].items():
+                if hasattr(cls.esphome, key):
+                    setattr(cls.esphome, key, value)
+
+        if "camera" in data:
+            for key, value in data["camera"].items():
+                if hasattr(cls.camera, key):
+                    setattr(cls.camera, key, value)
+
+        if "motion" in data:
+            for key, value in data["motion"].items():
+                if hasattr(cls.motion, key):
+                    setattr(cls.motion, key, value)
+
+        if "audio" in data:
+            for key, value in data["audio"].items():
+                if hasattr(cls.audio, key):
+                    setattr(cls.audio, key, value)
+
+        if "doa" in data:
+            for key, value in data["doa"].items():
+                if hasattr(cls.doa, key):
+                    setattr(cls.doa, key, value)
+
+        if "robot_state" in data:
+            for key, value in data["robot_state"].items():
+                if hasattr(cls.robot_state, key):
+                    setattr(cls.robot_state, key, value)
+
+        if "api" in data:
+            for key, value in data["api"].items():
+                if hasattr(cls.api, key):
+                    setattr(cls.api, key, value)
+
+    @classmethod
+    def initialize(cls, config_file: Path | None = None) -> None:
+        """Initialize configuration.
+
+        Loads from config file if provided, then applies environment overrides.
+
+        Args:
+            config_file: Optional path to JSON configuration file
+        """
+        if cls._initialized:
+            return
+
+        if config_file:
+            cls.load_from_file(config_file)
+
+        cls.load_from_env()
+        cls._initialized = True
+
+    @classmethod
+    def to_dict(cls) -> dict:
+        """Export current configuration as a dictionary."""
+        return {
+            "daemon": {
+                "url": cls.daemon.url,
+                "check_interval_active": cls.daemon.check_interval_active,
+                "check_interval_sleep": cls.daemon.check_interval_sleep,
+                "check_interval_error": cls.daemon.check_interval_error,
+                "max_backoff_interval": cls.daemon.max_backoff_interval,
+                "backoff_multiplier": cls.daemon.backoff_multiplier,
+                "backoff_error_threshold": cls.daemon.backoff_error_threshold,
+                "status_cache_ttl": cls.daemon.status_cache_ttl,
+                "volume_cache_ttl": cls.daemon.volume_cache_ttl,
+            },
+            "esphome": {
+                "port": cls.esphome.port,
+                "device_name": cls.esphome.device_name,
+                "friendly_name": cls.esphome.friendly_name,
+            },
+            "camera": {
+                "port": cls.camera.port,
+            },
+            "motion": {
+                "control_rate_hz": cls.motion.control_rate_hz,
+                "animation_fps": cls.motion.animation_fps,
+                "max_send_rate_hz": cls.motion.max_send_rate_hz,
+                "idle_heartbeat_interval_s": cls.motion.idle_heartbeat_interval_s,
+                "reconnect_backoff_initial_s": cls.motion.reconnect_backoff_initial_s,
+                "reconnect_backoff_max_s": cls.motion.reconnect_backoff_max_s,
+                "reconnect_backoff_multiplier": cls.motion.reconnect_backoff_multiplier,
+            },
+            "audio": {
+                "sample_rate": cls.audio.sample_rate,
+                "block_size": cls.audio.block_size,
+                "idle_sleep_active": cls.audio.idle_sleep_active,
+                "idle_sleep_sleeping": cls.audio.idle_sleep_sleeping,
+            },
+            "doa": {
+                "enabled": cls.doa.enabled,
+                "energy_threshold": cls.doa.energy_threshold,
+                "angle_threshold_deg": cls.doa.angle_threshold_deg,
+                "direction_cooldown": cls.doa.direction_cooldown,
+                "min_turn_interval": cls.doa.min_turn_interval,
+                "turn_duration": cls.doa.turn_duration,
+                "max_turn_angle_deg": cls.doa.max_turn_angle_deg,
+                "num_zones": cls.doa.num_zones,
+            },
+            "robot_state": {
+                "check_interval_active": cls.robot_state.check_interval_active,
+                "check_interval_sleep": cls.robot_state.check_interval_sleep,
+                "check_interval_error": cls.robot_state.check_interval_error,
+            },
+            "api": {
+                "port": cls.api.port,
+                "host": cls.api.host,
+            },
+        }

reachy_mini_home_assistant/core/exceptions.py

@@ -0,0 +1,72 @@
+"""Custom exceptions for Reachy Mini HA Voice.
+
+This module defines application-specific exceptions for better
+error handling and debugging.
+"""
+
+
+class ReachyHAError(Exception):
+    """Base exception for Reachy HA Voice errors."""
+
+    pass
+
+
+class RobotConnectionError(ReachyHAError):
+    """Error connecting to or communicating with the robot."""
+
+    def __init__(self, message: str = "Robot connection failed", cause: Exception = None):
+        super().__init__(message)
+        self.cause = cause
+
+
+class DaemonUnavailableError(ReachyHAError):
+    """The Reachy Mini daemon is not available."""
+
+    def __init__(self, message: str = "Daemon unavailable"):
+        super().__init__(message)
+
+
+class ServiceSuspendedError(ReachyHAError):
+    """Operation attempted while service is suspended for sleep."""
+
+    def __init__(self, service_name: str):
+        super().__init__(f"Service '{service_name}' is suspended")
+        self.service_name = service_name
+
+
+class ResourceUnavailableError(ReachyHAError):
+    """A required resource is not available."""
+
+    def __init__(self, resource_name: str, reason: str = None):
+        message = f"Resource '{resource_name}' unavailable"
+        if reason:
+            message += f": {reason}"
+        super().__init__(message)
+        self.resource_name = resource_name
+        self.reason = reason
+
+
+class ModelLoadError(ReachyHAError):
+    """Error loading an ML model."""
+
+    def __init__(self, model_name: str, cause: Exception = None):
+        super().__init__(f"Failed to load model: {model_name}")
+        self.model_name = model_name
+        self.cause = cause
+
+
+class ConfigurationError(ReachyHAError):
+    """Configuration error."""
+
+    def __init__(self, message: str, key: str = None):
+        super().__init__(message)
+        self.key = key
+
+
+class EntityRegistrationError(ReachyHAError):
+    """Error registering an ESPHome entity."""
+
+    def __init__(self, entity_name: str, cause: Exception = None):
+        super().__init__(f"Failed to register entity: {entity_name}")
+        self.entity_name = entity_name
+        self.cause = cause

reachy_mini_home_assistant/core/service_base.py

@@ -0,0 +1,551 @@
+"""Base classes for sleep-aware services.
+
+This module provides the SleepAwareService abstract base class that all
+services responding to sleep/wake events should implement.
+
+The sleep-aware lifecycle:
+1. Service starts in active state
+2. When robot sleeps: suspend() is called -> release resources
+3. When robot wakes: resume() is called -> restore resources
+4. Service can be stopped completely via stop()
+"""
+
+import asyncio
+import logging
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from enum import Enum
+from typing import Any, TypeVar
+
+logger = logging.getLogger(__name__)
+
+# Type variable for generic return types
+T = TypeVar("T")
+
+
+class RobustOperationMixin:
+    """Mixin that adds automatic error tracking and recovery to services.
+
+    This mixin provides a pattern for executing operations with automatic
+    error counting, timeout-based error rate reset, and optional restart
+    triggers when error thresholds are exceeded.
+
+    Usage:
+        class MyService(RobustOperationMixin):
+            def __init__(self):
+                super().__init__()
+                self._init_error_tracking()
+
+            def do_something(self):
+                def operation():
+                    # Actual work here
+                    pass
+                return self._execute_with_recovery(operation)
+    """
+
+    # Default configuration (can be overridden per-service)
+    _max_consecutive_errors: int = 5
+    _error_reset_interval: float = 60.0  # seconds
+    _restart_on_max_errors: bool = False
+
+    def _init_error_tracking(
+        self,
+        max_errors: int = 5,
+        reset_interval: float = 60.0,
+        restart_on_max_errors: bool = False,
+    ) -> None:
+        """Initialize error tracking with custom configuration.
+
+        Args:
+            max_errors: Maximum consecutive errors before triggering action
+            reset_interval: Time in seconds before error count resets
+            restart_on_max_errors: Whether to trigger restart on max errors
+        """
+        self._error_count = 0
+        self._last_error_time = 0.0
+        self._max_consecutive_errors = max_errors
+        self._error_reset_interval = reset_interval
+        self._restart_on_max_errors = restart_on_max_errors
+        self._restart_callback: Callable | None = None
+        self._error_logger = logging.getLogger(f"{__name__}.robust")
+
+    def set_restart_callback(self, callback: Callable) -> None:
+        """Set a callback to be called when max errors is reached.
+
+        Args:
+            callback: Function to call for service restart/recovery
+        """
+        self._restart_callback = callback
+
+    def _handle_error(self, error: Exception) -> bool:
+        """Track an error and determine if action is needed.
+
+        Args:
+            error: The exception that occurred
+
+        Returns:
+            True if max errors reached and action should be taken
+        """
+        now = time.monotonic()
+
+        # Reset error count if enough time has passed since last error
+        if now - self._last_error_time > self._error_reset_interval:
+            self._error_count = 0
+
+        self._error_count += 1
+        self._last_error_time = now
+
+        # Log with frequency limiting
+        if self._error_count <= 3 or self._error_count == self._max_consecutive_errors:
+            self._error_logger.error(
+                "Service error (%d/%d): %s",
+                self._error_count,
+                self._max_consecutive_errors,
+                error,
+            )
+
+        return self._error_count >= self._max_consecutive_errors
+
+    def _reset_error_count(self) -> None:
+        """Reset the error counter after successful operation."""
+        self._error_count = min(self._error_count, 0)
+
+    def _execute_with_recovery(
+        self,
+        operation: Callable[[], T],
+        *args,
+        suppress_errors: bool = False,
+        default_return: T = None,
+        **kwargs,
+    ) -> T:
+        """Execute an operation with automatic error tracking.
+
+        Args:
+            operation: The function to execute
+            *args: Arguments to pass to operation
+            suppress_errors: If True, return default_return instead of raising
+            default_return: Value to return on error if suppress_errors=True
+            **kwargs: Keyword arguments to pass to operation
+
+        Returns:
+            The operation result, or default_return on suppressed error
+
+        Raises:
+            The original exception if not suppressed
+        """
+        try:
+            result = operation(*args, **kwargs)
+            self._reset_error_count()
+            return result
+        except Exception as e:
+            should_restart = self._handle_error(e)
+
+            if should_restart and self._restart_on_max_errors:
+                if self._restart_callback is not None:
+                    self._error_logger.warning("Max errors reached - triggering restart")
+                    try:
+                        self._restart_callback()
+                    except Exception as restart_error:
+                        self._error_logger.error("Restart failed: %s", restart_error)
+
+            if suppress_errors:
+                return default_return
+            raise
+
+    async def _execute_async_with_recovery(
+        self,
+        operation: Callable[..., Any],
+        *args,
+        suppress_errors: bool = False,
+        default_return: T = None,
+        **kwargs,
+    ) -> T:
+        """Async version of _execute_with_recovery.
+
+        Args:
+            operation: The async function to execute
+            *args: Arguments to pass to operation
+            suppress_errors: If True, return default_return instead of raising
+            default_return: Value to return on error if suppress_errors=True
+            **kwargs: Keyword arguments to pass to operation
+
+        Returns:
+            The operation result, or default_return on suppressed error
+
+        Raises:
+            The original exception if not suppressed
+        """
+        try:
+            result = await operation(*args, **kwargs)
+            self._reset_error_count()
+            return result
+        except Exception as e:
+            should_restart = self._handle_error(e)
+
+            if should_restart and self._restart_on_max_errors:
+                if self._restart_callback is not None:
+                    self._error_logger.warning("Max errors reached - triggering restart")
+                    try:
+                        if asyncio.iscoroutinefunction(self._restart_callback):
+                            await self._restart_callback()
+                        else:
+                            self._restart_callback()
+                    except Exception as restart_error:
+                        self._error_logger.error("Restart failed: %s", restart_error)
+
+            if suppress_errors:
+                return default_return
+            raise
+
+
+class ServiceState(Enum):
+    """Represents the state of a sleep-aware service."""
+
+    STOPPED = "stopped"  # Service not started
+    STARTING = "starting"  # Service is starting up
+    ACTIVE = "active"  # Service is fully operational
+    SUSPENDING = "suspending"  # Service is being suspended (sleep)
+    SUSPENDED = "suspended"  # Service is suspended (sleeping)
+    RESUMING = "resuming"  # Service is resuming from sleep
+    STOPPING = "stopping"  # Service is shutting down
+    ERROR = "error"  # Service encountered an error
+
+
+class SleepAwareService(ABC):
+    """Abstract base class for services that respond to sleep/wake events.
+
+    Services implementing this interface will have their resources managed
+    during robot sleep/wake cycles. When the robot goes to sleep, suspend()
+    is called to release resources. When it wakes, resume() restores them.
+
+    Example:
+        class CameraService(SleepAwareService):
+            @property
+            def service_name(self) -> str:
+                return "camera"
+
+            async def _do_start(self) -> None:
+                self._init_camera()
+                self._start_streaming()
+
+            async def _do_suspend(self) -> None:
+                self._stop_streaming()
+                self._release_camera()
+
+            async def _do_resume(self) -> None:
+                self._init_camera()
+                self._start_streaming()
+
+            async def _do_stop(self) -> None:
+                self._stop_streaming()
+                self._release_camera()
+    """
+
+    def __init__(self):
+        """Initialize the service."""
+        self._state = ServiceState.STOPPED
+        self._state_lock = asyncio.Lock()
+        self._logger = logging.getLogger(f"{__name__}.{self.service_name}")
+
+    @property
+    @abstractmethod
+    def service_name(self) -> str:
+        """Return the name of this service for logging and identification."""
+        pass
+
+    @property
+    def state(self) -> ServiceState:
+        """Get the current service state."""
+        return self._state
+
+    @property
+    def is_active(self) -> bool:
+        """Check if the service is currently active."""
+        return self._state == ServiceState.ACTIVE
+
+    @property
+    def is_suspended(self) -> bool:
+        """Check if the service is currently suspended."""
+        return self._state == ServiceState.SUSPENDED
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the service is running (active or suspended)."""
+        return self._state in (
+            ServiceState.ACTIVE,
+            ServiceState.SUSPENDED,
+            ServiceState.SUSPENDING,
+            ServiceState.RESUMING,
+        )
+
+    async def start(self) -> None:
+        """Start the service.
+
+        This initializes and activates the service. Should only be called
+        when the service is in STOPPED state.
+        """
+        async with self._state_lock:
+            if self._state != ServiceState.STOPPED:
+                self._logger.warning(f"Cannot start service in state {self._state.value}")
+                return
+
+            self._state = ServiceState.STARTING
+            self._logger.info(f"Starting {self.service_name}...")
+
+        try:
+            await self._do_start()
+            async with self._state_lock:
+                self._state = ServiceState.ACTIVE
+            self._logger.info(f"{self.service_name} started successfully")
+        except Exception as e:
+            async with self._state_lock:
+                self._state = ServiceState.ERROR
+            self._logger.error(f"Failed to start {self.service_name}: {e}")
+            raise
+
+    async def stop(self) -> None:
+        """Stop the service completely.
+
+        This releases all resources and stops the service. Can be called
+        from any running state.
+        """
+        async with self._state_lock:
+            if self._state == ServiceState.STOPPED:
+                return
+            if self._state == ServiceState.STOPPING:
+                self._logger.debug("Service already stopping")
+                return
+
+            self._state = ServiceState.STOPPING
+            self._logger.info(f"Stopping {self.service_name}...")
+
+        try:
+            await self._do_stop()
+            async with self._state_lock:
+                self._state = ServiceState.STOPPED
+            self._logger.info(f"{self.service_name} stopped successfully")
+        except Exception as e:
+            async with self._state_lock:
+                self._state = ServiceState.ERROR
+            self._logger.error(f"Error stopping {self.service_name}: {e}")
+            raise
+
+    async def suspend(self) -> None:
+        """Suspend the service (for robot sleep).
+
+        This releases resources while keeping the service in a resumable state.
+        Should only be called when the service is ACTIVE.
+        """
+        async with self._state_lock:
+            if self._state != ServiceState.ACTIVE:
+                self._logger.warning(f"Cannot suspend service in state {self._state.value}")
+                return
+
+            self._state = ServiceState.SUSPENDING
+            self._logger.info(f"Suspending {self.service_name}...")
+
+        try:
+            await self._do_suspend()
+            async with self._state_lock:
+                self._state = ServiceState.SUSPENDED
+            self._logger.info(f"{self.service_name} suspended")
+        except Exception as e:
+            async with self._state_lock:
+                self._state = ServiceState.ERROR
+            self._logger.error(f"Error suspending {self.service_name}: {e}")
+            raise
+
+    async def resume(self) -> None:
+        """Resume the service (after robot wake).
+
+        This restores resources and re-activates the service.
+        Should only be called when the service is SUSPENDED.
+        """
+        async with self._state_lock:
+            if self._state != ServiceState.SUSPENDED:
+                self._logger.warning(f"Cannot resume service in state {self._state.value}")
+                return
+
+            self._state = ServiceState.RESUMING
+            self._logger.info(f"Resuming {self.service_name}...")
+
+        try:
+            await self._do_resume()
+            async with self._state_lock:
+                self._state = ServiceState.ACTIVE
+            self._logger.info(f"{self.service_name} resumed")
+        except Exception as e:
+            async with self._state_lock:
+                self._state = ServiceState.ERROR
+            self._logger.error(f"Error resuming {self.service_name}: {e}")
+            raise
+
+    @abstractmethod
+    async def _do_start(self) -> None:
+        """Implementation-specific start logic.
+
+        Subclasses should implement this to initialize and start their
+        resources.
+        """
+        pass
+
+    @abstractmethod
+    async def _do_stop(self) -> None:
+        """Implementation-specific stop logic.
+
+        Subclasses should implement this to release all resources and
+        stop any background tasks.
+        """
+        pass
+
+    @abstractmethod
+    async def _do_suspend(self) -> None:
+        """Implementation-specific suspend logic.
+
+        Subclasses should implement this to release resources that are
+        not needed during sleep, while keeping the service in a resumable
+        state.
+
+        Typical actions:
+        - Stop background threads
+        - Release ML models from memory
+        - Close network connections
+        - Stop timers
+        """
+        pass
+
+    @abstractmethod
+    async def _do_resume(self) -> None:
+        """Implementation-specific resume logic.
+
+        Subclasses should implement this to restore resources and
+        re-activate the service after sleep.
+
+        Typical actions:
+        - Restart background threads
+        - Reload ML models
+        - Re-establish network connections
+        - Restart timers
+        """
+        pass
+
+    async def __aenter__(self) -> "SleepAwareService":
+        """Context manager entry - starts the service."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """Context manager exit - stops the service."""
+        await self.stop()
+        return False
+
+
+class ServiceManager:
+    """Manages multiple SleepAwareService instances.
+
+    Provides coordinated suspend/resume for all registered services,
+    ensuring proper ordering and error handling.
+
+    Usage:
+        manager = ServiceManager()
+        manager.register(camera_service)
+        manager.register(motion_service)
+
+        # Suspend all services
+        await manager.suspend_all()
+
+        # Resume all services after delay
+        await asyncio.sleep(30)
+        await manager.resume_all()
+    """
+
+    def __init__(self, resume_delay: float = 30.0):
+        """Initialize the service manager.
+
+        Args:
+            resume_delay: Delay in seconds before resuming services after wake
+        """
+        self._services: list[SleepAwareService] = []
+        self._resume_delay = resume_delay
+        self._is_suspended = False
+        self._logger = logging.getLogger(__name__)
+
+    def register(self, service: SleepAwareService) -> None:
+        """Register a service to be managed."""
+        if service not in self._services:
+            self._services.append(service)
+            self._logger.debug(f"Registered service: {service.service_name}")
+
+    def unregister(self, service: SleepAwareService) -> None:
+        """Unregister a service."""
+        if service in self._services:
+            self._services.remove(service)
+            self._logger.debug(f"Unregistered service: {service.service_name}")
+
+    @property
+    def is_suspended(self) -> bool:
+        """Check if all services are suspended."""
+        return self._is_suspended
+
+    async def start_all(self) -> None:
+        """Start all registered services."""
+        self._logger.info(f"Starting {len(self._services)} services...")
+        for service in self._services:
+            try:
+                await service.start()
+            except Exception as e:
+                self._logger.error(f"Failed to start {service.service_name}: {e}")
+
+    async def stop_all(self) -> None:
+        """Stop all registered services."""
+        self._logger.info(f"Stopping {len(self._services)} services...")
+        # Stop in reverse order (LIFO)
+        for service in reversed(self._services):
+            try:
+                await service.stop()
+            except Exception as e:
+                self._logger.error(f"Failed to stop {service.service_name}: {e}")
+
+    async def suspend_all(self) -> None:
+        """Suspend all active services."""
+        if self._is_suspended:
+            self._logger.debug("Services already suspended")
+            return
+
+        self._logger.info("Suspending all services for sleep...")
+        for service in self._services:
+            if service.is_active:
+                try:
+                    await service.suspend()
+                except Exception as e:
+                    self._logger.error(f"Failed to suspend {service.service_name}: {e}")
+
+        self._is_suspended = True
+        self._logger.info("All services suspended")
+
+    async def resume_all(self, delay: float | None = None) -> None:
+        """Resume all suspended services.
+
+        Args:
+            delay: Optional override for resume delay. If None, uses default.
+        """
+        if not self._is_suspended:
+            self._logger.debug("Services not suspended")
+            return
+
+        actual_delay = delay if delay is not None else self._resume_delay
+        if actual_delay > 0:
+            self._logger.info(f"Waiting {actual_delay}s before resuming services...")
+            await asyncio.sleep(actual_delay)
+
+        self._logger.info("Resuming all services after wake...")
+        for service in self._services:
+            if service.is_suspended:
+                try:
+                    await service.resume()
+                except Exception as e:
+                    self._logger.error(f"Failed to resume {service.service_name}: {e}")
+
+        self._is_suspended = False
+        self._logger.info("All services resumed")

reachy_mini_home_assistant/core/system_diagnostics.py

@@ -0,0 +1,207 @@
+"""System Diagnostics for Home Assistant.
+
+This module provides system diagnostic sensors using psutil to monitor
+CPU, memory, disk, and network usage on the Reachy Mini robot.
+
+All sensors are registered with entity_category=2 (diagnostic) so they
+appear in the Diagnostics section in Home Assistant.
+"""
+
+import logging
+import time
+
+import psutil
+
+logger = logging.getLogger(__name__)
+
+
+class SystemDiagnostics:
+    """System diagnostics provider using psutil.
+
+    This class provides getter methods for various system metrics that can
+    be used with SensorEntity's value_getter parameter.
+
+    Metrics are cached briefly to avoid excessive system calls when multiple
+    entities are updated in quick succession.
+    """
+
+    def __init__(self, cache_ttl: float = 1.0):
+        """Initialize system diagnostics.
+
+        Args:
+            cache_ttl: Cache time-to-live in seconds. Metrics are cached
+                to avoid excessive system calls.
+        """
+        self._cache_ttl = cache_ttl
+        self._cache: dict = {}
+        self._cache_time: dict = {}
+
+        # Get initial disk path (root partition)
+        self._disk_path = "/" if psutil.POSIX else "C:\\"
+
+        logger.info("SystemDiagnostics initialized")
+
+    def _get_cached(self, key: str, getter) -> any:
+        """Get a cached value or compute it.
+
+        Args:
+            key: Cache key
+            getter: Callable to get fresh value
+
+        Returns:
+            Cached or fresh value
+        """
+        now = time.monotonic()
+        if key in self._cache:
+            if now - self._cache_time.get(key, 0) < self._cache_ttl:
+                return self._cache[key]
+
+        try:
+            value = getter()
+            self._cache[key] = value
+            self._cache_time[key] = now
+            return value
+        except Exception as e:
+            logger.debug("Error getting %s: %s", key, e)
+            return self._cache.get(key, 0.0)
+
+    # =========================================================================
+    # CPU Metrics
+    # =========================================================================
+
+    def get_cpu_percent(self) -> float:
+        """Get CPU usage percentage (0-100)."""
+        return self._get_cached("cpu_percent", lambda: psutil.cpu_percent(interval=None))
+
+    def get_cpu_temperature(self) -> float:
+        """Get CPU temperature in Celsius.
+
+        Note: May not be available on all platforms.
+        Returns 0.0 if temperature sensors are not available.
+        """
+
+        def _get_temp():
+            temps = psutil.sensors_temperatures()
+            if not temps:
+                return 0.0
+
+            # Try common sensor names
+            for name in ["coretemp", "cpu_thermal", "cpu-thermal", "k10temp", "zenpower"]:
+                if temps.get(name):
+                    return temps[name][0].current
+
+            # Fallback: first available sensor
+            for sensors in temps.values():
+                if sensors:
+                    return sensors[0].current
+
+            return 0.0
+
+        return self._get_cached("cpu_temperature", _get_temp)
+
+    def get_cpu_count(self) -> float:
+        """Get number of CPU cores."""
+        return float(psutil.cpu_count() or 1)
+
+    # =========================================================================
+    # Memory Metrics
+    # =========================================================================
+
+    def get_memory_percent(self) -> float:
+        """Get memory usage percentage (0-100)."""
+        return self._get_cached("memory_percent", lambda: psutil.virtual_memory().percent)
+
+    def get_memory_used_gb(self) -> float:
+        """Get used memory in GB."""
+        return self._get_cached("memory_used_gb", lambda: psutil.virtual_memory().used / (1024**3))
+
+    def get_memory_total_gb(self) -> float:
+        """Get total memory in GB."""
+        return self._get_cached("memory_total_gb", lambda: psutil.virtual_memory().total / (1024**3))
+
+    def get_memory_available_gb(self) -> float:
+        """Get available memory in GB."""
+        return self._get_cached("memory_available_gb", lambda: psutil.virtual_memory().available / (1024**3))
+
+    # =========================================================================
+    # Disk Metrics
+    # =========================================================================
+
+    def get_disk_percent(self) -> float:
+        """Get disk usage percentage (0-100)."""
+        return self._get_cached("disk_percent", lambda: psutil.disk_usage(self._disk_path).percent)
+
+    def get_disk_used_gb(self) -> float:
+        """Get used disk space in GB."""
+        return self._get_cached("disk_used_gb", lambda: psutil.disk_usage(self._disk_path).used / (1024**3))
+
+    def get_disk_total_gb(self) -> float:
+        """Get total disk space in GB."""
+        return self._get_cached("disk_total_gb", lambda: psutil.disk_usage(self._disk_path).total / (1024**3))
+
+    def get_disk_free_gb(self) -> float:
+        """Get free disk space in GB."""
+        return self._get_cached("disk_free_gb", lambda: psutil.disk_usage(self._disk_path).free / (1024**3))
+
+    # =========================================================================
+    # Network Metrics
+    # =========================================================================
+
+    def get_network_bytes_sent_mb(self) -> float:
+        """Get total bytes sent since boot in MB."""
+        return self._get_cached("network_bytes_sent_mb", lambda: psutil.net_io_counters().bytes_sent / (1024**2))
+
+    def get_network_bytes_recv_mb(self) -> float:
+        """Get total bytes received since boot in MB."""
+        return self._get_cached("network_bytes_recv_mb", lambda: psutil.net_io_counters().bytes_recv / (1024**2))
+
+    # =========================================================================
+    # Process Metrics (this process)
+    # =========================================================================
+
+    def get_process_cpu_percent(self) -> float:
+        """Get CPU usage of this process (0-100)."""
+        return self._get_cached("process_cpu_percent", lambda: psutil.Process().cpu_percent(interval=None))
+
+    def get_process_memory_mb(self) -> float:
+        """Get memory usage of this process in MB."""
+        return self._get_cached("process_memory_mb", lambda: psutil.Process().memory_info().rss / (1024**2))
+
+    def get_process_threads(self) -> float:
+        """Get number of threads in this process."""
+        return self._get_cached("process_threads", lambda: float(psutil.Process().num_threads()))
+
+    # =========================================================================
+    # System Metrics
+    # =========================================================================
+
+    def get_uptime_hours(self) -> float:
+        """Get system uptime in hours."""
+        return self._get_cached("uptime_hours", lambda: (time.time() - psutil.boot_time()) / 3600)
+
+    def get_load_average_1m(self) -> float:
+        """Get 1-minute load average.
+
+        Note: Returns 0.0 on Windows.
+        """
+
+        def _get_load():
+            try:
+                return psutil.getloadavg()[0]
+            except (AttributeError, OSError):
+                # Windows doesn't support getloadavg
+                return 0.0
+
+        return self._get_cached("load_average_1m", _get_load)
+
+
+# Singleton instance for easy access
+_diagnostics_instance: SystemDiagnostics | None = None
+
+
+def get_system_diagnostics() -> SystemDiagnostics:
+    """Get or create the singleton SystemDiagnostics instance."""
+    global _diagnostics_instance
+    if _diagnostics_instance is None:
+        _diagnostics_instance = SystemDiagnostics()
+    return _diagnostics_instance

reachy_mini_home_assistant/core/util.py

@@ -0,0 +1,26 @@
+"""Utility functions."""
+
+from collections.abc import Callable
+
+
+def call_all(*funcs: Callable[[], None] | None) -> None:
+    """Call all non-None functions."""
+    for func in funcs:
+        if func is not None:
+            func()
+
+
+def get_mac() -> str:
+    """Return the machine ID as device ID.
+
+    Reads /etc/machine-id and returns first 12 characters.
+    """
+    machine_id = "00000000000000000000000000000000"
+    try:
+        with open("/etc/machine-id") as f:
+            machine_id = f.read().strip()
+    except Exception:
+        pass
+
+    # Return first 12 characters
+    return machine_id[:12]

reachy_mini_home_assistant/entities/__init__.py

@@ -0,0 +1,74 @@
+"""Entities module for Home Assistant integration.
+
+This module handles ESPHome entity definitions:
+- ESPHomeEntity: Base class for all entities
+- EntityRegistry: Entity registration and management
+- EventEmotionMapper: HA event to robot emotion mapping
+# - EmotionKeywordDetector: LLM response emotion detection (DISABLED - moved to HA blueprint)
+- Entity keys: Consistent key management
+- Entity factory: Entity creation utilities
+"""
+
+# DISABLED: Emotion detection moved to Home Assistant blueprint
+# from .emotion_detector import EmotionKeywordDetector
+from .entity import (
+    BinarySensorEntity,
+    CameraEntity,
+    ESPHomeEntity,
+    MediaPlayerEntity,
+    NumberEntity,
+    TextSensorEntity,
+)
+from .entity_extensions import (
+    ButtonEntity,
+    SelectEntity,
+    SensorEntity,
+    SwitchEntity,
+)
+
+# Entity keys - single source of truth
+from .entity_keys import (
+    ENTITY_KEYS,
+    get_entity_key,
+    get_next_available_key,
+    register_entity_key,
+)
+from .entity_registry import EntityRegistry
+from .event_emotion_mapper import (
+    DEFAULT_EVENT_EMOTION_MAP,
+    EventEmotionMapper,
+    EventEmotionMapping,
+    EventSource,
+    EventTrigger,
+    load_event_mappings,
+)
+
+__all__ = [
+    "DEFAULT_EVENT_EMOTION_MAP",
+    # Entity keys
+    "ENTITY_KEYS",
+    "BinarySensorEntity",
+    "ButtonEntity",
+    "CameraEntity",
+    # Entity base classes
+    "ESPHomeEntity",
+    # Emotion detection (DISABLED - moved to HA blueprint)
+    # "EmotionKeywordDetector",
+    # Entity registry
+    "EntityRegistry",
+    "EventEmotionMapper",
+    "EventEmotionMapping",
+    # Event emotion mapping
+    "EventSource",
+    "EventTrigger",
+    "MediaPlayerEntity",
+    "NumberEntity",
+    "SelectEntity",
+    "SensorEntity",
+    "SwitchEntity",
+    "TextSensorEntity",
+    "get_entity_key",
+    "get_next_available_key",
+    "load_event_mappings",
+    "register_entity_key",
+]

reachy_mini_home_assistant/entities/emotion_detector.py

@@ -0,0 +1,115 @@
+"""Emotion keyword detection from text responses.
+
+This module provides automatic emotion detection based on keywords in LLM responses,
+allowing the robot to express emotions naturally during conversation.
+"""
+
+import json
+import logging
+from collections.abc import Callable
+from pathlib import Path
+
+from ..animations.animation_config import get_animation_config_section
+
+_LOGGER = logging.getLogger(__name__)
+
+_UNIFIED_BEHAVIORS_FILE = Path(__file__).parent.parent / "animations" / "conversation_animations.json"
+
+
+class EmotionKeywordDetector:
+    """Detects emotions from text using keyword matching.
+
+    Loads keyword-to-emotion mappings from a JSON configuration file
+    and provides automatic emotion detection for LLM responses.
+    """
+
+    def __init__(
+        self,
+        config_path: Path | None = None,
+        play_emotion_callback: Callable[[str], None] | None = None,
+    ):
+        """Initialize the emotion detector.
+
+        Args:
+            config_path: Path to the unified behavior JSON. Defaults to animations folder.
+            play_emotion_callback: Function to call when emotion is detected.
+        """
+        self._keywords: dict[str, str] = {}
+        self._enabled: bool = True
+        self._play_emotion_callback = play_emotion_callback
+
+        if config_path is None:
+            config_path = _UNIFIED_BEHAVIORS_FILE
+
+        self._load_keywords(config_path)
+
+    def _load_keywords(self, config_path: Path) -> None:
+        """Load emotion keywords from JSON configuration file."""
+        if not config_path.exists():
+            _LOGGER.warning("Emotion keywords file not found: %s", config_path)
+            return
+
+        try:
+            data = get_animation_config_section(config_path, "emotion_keywords") or {}
+
+            self._keywords = data.get("keywords", {})
+            settings = data.get("settings", {})
+            self._enabled = settings.get("enabled", True)
+
+            _LOGGER.info("Loaded %d emotion keywords (enabled=%s)", len(self._keywords), self._enabled)
+        except Exception as e:
+            _LOGGER.error("Failed to load emotion keywords: %s", e)
+
+    def set_play_emotion_callback(self, callback: Callable[[str], None]) -> None:
+        """Set the callback for playing emotions.
+
+        Args:
+            callback: Function that takes emotion name and plays it
+        """
+        self._play_emotion_callback = callback
+
+    def detect_and_play(self, text: str) -> str | None:
+        """Detect emotion from text and trigger corresponding animation.
+
+        Keywords are matched case-insensitively against the text.
+        Only triggers one emotion per response (first match wins).
+
+        Args:
+            text: The text to analyze for emotional content
+
+        Returns:
+            The detected emotion name, or None if no emotion detected
+        """
+        if not text or not self._enabled:
+            return None
+
+        if not self._keywords:
+            return None
+
+        text_lower = text.lower()
+
+        # Check each keyword pattern
+        for keyword, emotion_name in self._keywords.items():
+            if keyword.lower() in text_lower:
+                _LOGGER.info("Auto-detected emotion '%s' from keyword '%s' in response", emotion_name, keyword)
+                if self._play_emotion_callback:
+                    self._play_emotion_callback(emotion_name)
+                return emotion_name
+
+        _LOGGER.debug("No emotion keywords detected in response text")
+        return None
+
+    @property
+    def enabled(self) -> bool:
+        """Check if emotion detection is enabled."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        """Enable or disable emotion detection."""
+        self._enabled = value
+
+    @property
+    def keyword_count(self) -> int:
+        """Get the number of loaded keywords."""
+        return len(self._keywords)

reachy_mini_home_assistant/entities/entity.py

@@ -0,0 +1,409 @@
+"""ESPHome entity definitions."""
+
+import logging
+from abc import abstractmethod
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING
+
+# pylint: disable=no-name-in-module
+from aioesphomeapi.api_pb2 import (  # type: ignore[attr-defined]
+    BinarySensorStateResponse,
+    CameraImageRequest,
+    CameraImageResponse,
+    ListEntitiesBinarySensorResponse,
+    ListEntitiesCameraResponse,
+    ListEntitiesMediaPlayerResponse,
+    ListEntitiesNumberResponse,
+    ListEntitiesRequest,
+    ListEntitiesTextSensorResponse,
+    MediaPlayerCommandRequest,
+    MediaPlayerStateResponse,
+    NumberCommandRequest,
+    NumberStateResponse,
+    SubscribeHomeAssistantStatesRequest,
+    SubscribeStatesRequest,
+    TextSensorStateResponse,
+)
+from aioesphomeapi.model import MediaPlayerCommand, MediaPlayerEntityFeature, MediaPlayerState
+from google.protobuf import message
+
+from ..audio.audio_player import AudioPlayer
+from ..core.util import call_all
+
+if TYPE_CHECKING:
+    from ..protocol.api_server import APIServer
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_get_value(getter: Callable[[], object] | None, current_value: object, entity_name: str) -> object:
+    """Read an entity value without letting getter failures break the ESPHome session."""
+    if getter is None:
+        return current_value
+    try:
+        return getter()
+    except Exception as e:
+        logger.error("Entity getter failed for %s: %s", entity_name, e)
+        return current_value
+
+
+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: str | list[str],
+        announcement: bool = False,
+        done_callback: Callable[[], None] | 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.command == MediaPlayerCommand.STOP:
+                    self.music_player.stop()
+                    yield self._update_state(MediaPlayerState.IDLE)
+            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):
+            # Set feature flags for Music Assistant compatibility
+            # PLAY_MEDIA (512) is required for Music Assistant to recognize the player
+            feature_flags = (
+                MediaPlayerEntityFeature.PAUSE
+                | MediaPlayerEntityFeature.PLAY_MEDIA
+                | MediaPlayerEntityFeature.VOLUME_SET
+                | MediaPlayerEntityFeature.MEDIA_ANNOUNCE
+            )
+            yield ListEntitiesMediaPlayerResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                supports_pause=True,
+                feature_flags=feature_flags,
+            )
+        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,
+        )
+
+
+class TextSensorEntity(ESPHomeEntity):
+    """Text sensor entity for ESPHome (read-only string values)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        icon: str = "",
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        value_getter: Callable[[], str] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.icon = icon
+        self.entity_category = entity_category
+        self._value_getter = value_getter
+        self._value = ""
+
+    @property
+    def value(self) -> str:
+        return str(_safe_get_value(self._value_getter, self._value, self.object_id))
+
+    @value.setter
+    def value(self, new_value: str) -> None:
+        self._value = new_value
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesTextSensorResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, (SubscribeHomeAssistantStatesRequest, SubscribeStatesRequest)):
+            yield self._get_state_message()
+
+    def _get_state_message(self) -> TextSensorStateResponse:
+        return TextSensorStateResponse(
+            key=self.key,
+            state=self.value,
+            missing_state=False,
+        )
+
+    def update_state(self) -> None:
+        """Send state update to Home Assistant."""
+        self.server.send_messages([self._get_state_message()])
+
+
+class BinarySensorEntity(ESPHomeEntity):
+    """Binary sensor entity for ESPHome (read-only boolean values)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        icon: str = "",
+        device_class: str = "",
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        value_getter: Callable[[], bool] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.icon = icon
+        self.device_class = device_class
+        self.entity_category = entity_category
+        self._value_getter = value_getter
+        self._value = False
+
+    @property
+    def value(self) -> bool:
+        return bool(_safe_get_value(self._value_getter, self._value, self.object_id))
+
+    @value.setter
+    def value(self, new_value: bool) -> None:
+        self._value = new_value
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesBinarySensorResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                device_class=self.device_class,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, (SubscribeHomeAssistantStatesRequest, SubscribeStatesRequest)):
+            yield self._get_state_message()
+
+    def _get_state_message(self) -> BinarySensorStateResponse:
+        return BinarySensorStateResponse(
+            key=self.key,
+            state=self.value,
+            missing_state=False,
+        )
+
+    def update_state(self) -> None:
+        """Send state update to Home Assistant."""
+        self.server.send_messages([self._get_state_message()])
+
+
+class NumberEntity(ESPHomeEntity):
+    """Number entity for ESPHome (read-write numeric values)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        min_value: float = 0.0,
+        max_value: float = 100.0,
+        step: float = 1.0,
+        icon: str = "",
+        unit_of_measurement: str = "",
+        mode: int = 0,  # 0 = auto, 1 = box, 2 = slider
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        value_getter: Callable[[], float] | None = None,
+        value_setter: Callable[[float], None] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.min_value = min_value
+        self.max_value = max_value
+        self.step = step
+        self.icon = icon
+        self.unit_of_measurement = unit_of_measurement
+        self.mode = mode
+        self.entity_category = entity_category
+        self._value_getter = value_getter
+        self._value_setter = value_setter
+        self._value = min_value
+
+    @property
+    def value(self) -> float:
+        return float(_safe_get_value(self._value_getter, self._value, self.object_id))
+
+    @value.setter
+    def value(self, new_value: float) -> None:
+        # Clamp value to valid range
+        new_value = max(self.min_value, min(self.max_value, new_value))
+        if self._value_setter:
+            self._value_setter(new_value)
+        self._value = new_value
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesNumberResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                min_value=self.min_value,
+                max_value=self.max_value,
+                step=self.step,
+                unit_of_measurement=self.unit_of_measurement,
+                mode=self.mode,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, (SubscribeHomeAssistantStatesRequest, SubscribeStatesRequest)):
+            yield self._get_state_message()
+        elif isinstance(msg, NumberCommandRequest) and msg.key == self.key:
+            self.value = msg.state
+            yield self._get_state_message()
+
+    def _get_state_message(self) -> NumberStateResponse:
+        return NumberStateResponse(
+            key=self.key,
+            state=self.value,
+            missing_state=False,
+        )
+
+    def update_state(self) -> None:
+        """Send state update to Home Assistant."""
+        self.server.send_messages([self._get_state_message()])
+
+
+class CameraEntity(ESPHomeEntity):
+    """Camera entity for ESPHome (provides image snapshots)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        icon: str = "mdi:camera",
+        image_getter: Callable[[], bytes | None] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.icon = icon
+        self._image_getter = image_getter
+
+    def get_image(self) -> bytes | None:
+        """Get the current camera image as JPEG bytes."""
+        if self._image_getter:
+            return self._image_getter()
+        return None
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesCameraResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+            )
+        elif isinstance(msg, CameraImageRequest):
+            # CameraImageRequest doesn't have a key field - it's a global request
+            # Return camera image for any camera request
+            image_data = self.get_image()
+            if image_data:
+                yield CameraImageResponse(
+                    key=self.key,
+                    data=image_data,
+                    done=True,
+                )
+            else:
+                # Return empty response if no image available
+                yield CameraImageResponse(
+                    key=self.key,
+                    data=b"",
+                    done=True,
+                )

reachy_mini_home_assistant/entities/entity_extensions.py

@@ -0,0 +1,300 @@
+"""Extended ESPHome entity types for Reachy Mini control."""
+
+import logging
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING
+
+from aioesphomeapi.api_pb2 import (  # type: ignore[attr-defined]
+    ButtonCommandRequest,
+    ListEntitiesButtonResponse,
+    ListEntitiesRequest,
+    ListEntitiesSelectResponse,
+    ListEntitiesSensorResponse,
+    ListEntitiesSwitchResponse,
+    SelectCommandRequest,
+    SelectStateResponse,
+    SensorStateResponse,
+    SubscribeHomeAssistantStatesRequest,
+    SubscribeStatesRequest,
+    SwitchCommandRequest,
+    SwitchStateResponse,
+)
+from google.protobuf import message
+
+from .entity import ESPHomeEntity
+
+if TYPE_CHECKING:
+    from ..protocol.api_server import APIServer
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_get_value(getter: Callable[[], object] | None, current_value: object, entity_name: str) -> object:
+    """Read an entity value without letting getter failures break the ESPHome session."""
+    if getter is None:
+        return current_value
+    try:
+        return getter()
+    except Exception as e:
+        logger.error("Entity getter failed for %s: %s", entity_name, e)
+        return current_value
+
+
+class SensorStateClass:
+    """ESPHome SensorStateClass enum values."""
+
+    NONE = 0
+    MEASUREMENT = 1
+    TOTAL_INCREASING = 2
+    TOTAL = 3
+
+
+class SensorEntity(ESPHomeEntity):
+    """Sensor entity for ESPHome (read-only numeric values)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        icon: str = "",
+        unit_of_measurement: str = "",
+        accuracy_decimals: int = 2,
+        device_class: str = "",
+        state_class: int = SensorStateClass.NONE,
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        value_getter: Callable[[], float] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.icon = icon
+        self.unit_of_measurement = unit_of_measurement
+        self.accuracy_decimals = accuracy_decimals
+        self.device_class = device_class
+        self.entity_category = entity_category
+        # Convert string state_class to enum
+        if isinstance(state_class, str):
+            state_class_map = {
+                "": SensorStateClass.NONE,
+                "measurement": SensorStateClass.MEASUREMENT,
+                "total_increasing": SensorStateClass.TOTAL_INCREASING,
+                "total": SensorStateClass.TOTAL,
+            }
+            self.state_class = state_class_map.get(state_class.lower(), SensorStateClass.NONE)
+        else:
+            self.state_class = state_class
+        self._value_getter = value_getter
+        self._value = 0.0
+
+    @property
+    def value(self) -> float:
+        return float(_safe_get_value(self._value_getter, self._value, self.object_id))
+
+    @value.setter
+    def value(self, new_value: float) -> None:
+        self._value = new_value
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesSensorResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                unit_of_measurement=self.unit_of_measurement,
+                accuracy_decimals=self.accuracy_decimals,
+                device_class=self.device_class,
+                state_class=self.state_class,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, (SubscribeHomeAssistantStatesRequest, SubscribeStatesRequest)):
+            yield self._get_state_message()
+
+    def _get_state_message(self) -> SensorStateResponse:
+        return SensorStateResponse(
+            key=self.key,
+            state=self.value,
+            missing_state=False,
+        )
+
+    def update_state(self) -> None:
+        """Send state update to Home Assistant."""
+        self.server.send_messages([self._get_state_message()])
+
+
+class SwitchEntity(ESPHomeEntity):
+    """Switch entity for ESPHome (read-write boolean values)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        icon: str = "",
+        device_class: str = "",
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        value_getter: Callable[[], bool] | None = None,
+        value_setter: Callable[[bool], None] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.icon = icon
+        self.device_class = device_class
+        self.entity_category = entity_category
+        self._value_getter = value_getter
+        self._value_setter = value_setter
+        self._value = False
+
+    @property
+    def value(self) -> bool:
+        return bool(_safe_get_value(self._value_getter, self._value, self.object_id))
+
+    @value.setter
+    def value(self, new_value: bool) -> None:
+        if self._value_setter:
+            self._value_setter(new_value)
+        self._value = new_value
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesSwitchResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                device_class=self.device_class,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, (SubscribeHomeAssistantStatesRequest, SubscribeStatesRequest)):
+            yield self._get_state_message()
+        elif isinstance(msg, SwitchCommandRequest) and msg.key == self.key:
+            self.value = msg.state
+            yield self._get_state_message()
+
+    def _get_state_message(self) -> SwitchStateResponse:
+        return SwitchStateResponse(
+            key=self.key,
+            state=self.value,
+        )
+
+    def update_state(self) -> None:
+        """Send state update to Home Assistant."""
+        self.server.send_messages([self._get_state_message()])
+
+
+class SelectEntity(ESPHomeEntity):
+    """Select entity for ESPHome (read-write string selection)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        options: list[str],
+        icon: str = "",
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        value_getter: Callable[[], str] | None = None,
+        value_setter: Callable[[str], None] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.options = options
+        self.icon = icon
+        self.entity_category = entity_category
+        self._value_getter = value_getter
+        self._value_setter = value_setter
+        self._value = options[0] if options else ""
+
+    @property
+    def value(self) -> str:
+        return str(_safe_get_value(self._value_getter, self._value, self.object_id))
+
+    @value.setter
+    def value(self, new_value: str) -> None:
+        if new_value in self.options:
+            if self._value_setter:
+                self._value_setter(new_value)
+            self._value = new_value
+        else:
+            logger.warning(f"Invalid option '{new_value}' for {self.name}")
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesSelectResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                options=self.options,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, (SubscribeHomeAssistantStatesRequest, SubscribeStatesRequest)):
+            yield self._get_state_message()
+        elif isinstance(msg, SelectCommandRequest) and msg.key == self.key:
+            self.value = msg.state
+            yield self._get_state_message()
+
+    def _get_state_message(self) -> SelectStateResponse:
+        return SelectStateResponse(
+            key=self.key,
+            state=self.value,
+            missing_state=False,
+        )
+
+    def update_state(self) -> None:
+        """Send state update to Home Assistant."""
+        self.server.send_messages([self._get_state_message()])
+
+
+class ButtonEntity(ESPHomeEntity):
+    """Button entity for ESPHome (trigger actions)."""
+
+    def __init__(
+        self,
+        server: "APIServer",
+        key: int,
+        name: str,
+        object_id: str,
+        icon: str = "",
+        device_class: str = "",
+        entity_category: int = 0,  # 0 = none, 1 = config, 2 = diagnostic
+        on_press: Callable[[], None] | None = None,
+    ) -> None:
+        ESPHomeEntity.__init__(self, server)
+        self.key = key
+        self.name = name
+        self.object_id = object_id
+        self.icon = icon
+        self.device_class = device_class
+        self.entity_category = entity_category
+        self._on_press = on_press
+
+    def handle_message(self, msg: message.Message) -> Iterable[message.Message]:
+        if isinstance(msg, ListEntitiesRequest):
+            yield ListEntitiesButtonResponse(
+                object_id=self.object_id,
+                key=self.key,
+                name=self.name,
+                icon=self.icon,
+                device_class=self.device_class,
+                entity_category=self.entity_category,
+            )
+        elif isinstance(msg, ButtonCommandRequest) and msg.key == self.key:
+            if self._on_press:
+                try:
+                    self._on_press()
+                    logger.info(f"Button '{self.name}' pressed")
+                except Exception as e:
+                    logger.error(f"Error executing button '{self.name}': {e}")
+            # Buttons don't have state responses
+            return
+            yield  # Make this a generator

reachy_mini_home_assistant/entities/entity_factory.py

@@ -0,0 +1,538 @@
+"""Entity factory for creating ESPHome entities.
+
+This module provides factory functions for creating entities in a declarative way,
+reducing boilerplate code in entity_registry.py.
+"""
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from .entity import BinarySensorEntity, CameraEntity, NumberEntity, TextSensorEntity
+from .entity_extensions import ButtonEntity, SelectEntity, SensorEntity, SwitchEntity
+from .entity_keys import get_entity_key
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class EntityType(Enum):
+    """Supported entity types."""
+
+    SENSOR = "sensor"
+    BINARY_SENSOR = "binary_sensor"
+    TEXT_SENSOR = "text_sensor"
+    SWITCH = "switch"
+    SELECT = "select"
+    BUTTON = "button"
+    NUMBER = "number"
+    CAMERA = "camera"
+
+
+@dataclass
+class EntityDefinition:
+    """Definition for an entity to be created."""
+
+    entity_type: EntityType
+    key_name: str
+    name: str
+    object_id: str
+    icon: str = "mdi:information"
+
+    # Common optional fields
+    entity_category: int | None = None  # 0=None, 1=config, 2=diagnostic
+
+    # Sensor specific
+    unit_of_measurement: str | None = None
+    accuracy_decimals: int | None = None
+    state_class: str | None = None
+    device_class: str | None = None
+
+    # Number specific
+    min_value: float | None = None
+    max_value: float | None = None
+    step: float | None = None
+    mode: int | None = None  # 0=auto, 1=box, 2=slider
+
+    # Select specific
+    options: list[str] | None = None
+
+    # Callbacks (set at runtime)
+    value_getter: Callable | None = None
+    command_handler: Callable | None = None
+
+    # Additional kwargs
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def create_entity(server, definition: EntityDefinition) -> Any:
+    """Create an entity from a definition.
+
+    Args:
+        server: The VoiceSatelliteProtocol server instance
+        definition: The entity definition
+
+    Returns:
+        The created entity instance
+    """
+    key = get_entity_key(definition.key_name)
+
+    common_args = {
+        "server": server,
+        "key": key,
+        "name": definition.name,
+        "object_id": definition.object_id,
+        "icon": definition.icon,
+    }
+
+    if definition.entity_category is not None:
+        common_args["entity_category"] = definition.entity_category
+
+    if definition.entity_type == EntityType.SENSOR:
+        args = {**common_args}
+        if definition.unit_of_measurement:
+            args["unit_of_measurement"] = definition.unit_of_measurement
+        if definition.accuracy_decimals is not None:
+            args["accuracy_decimals"] = definition.accuracy_decimals
+        if definition.state_class:
+            args["state_class"] = definition.state_class
+        if definition.device_class:
+            args["device_class"] = definition.device_class
+        if definition.value_getter:
+            args["value_getter"] = definition.value_getter
+        args.update(definition.extra)
+        return SensorEntity(**args)
+
+    elif definition.entity_type == EntityType.BINARY_SENSOR:
+        args = {**common_args}
+        if definition.device_class:
+            args["device_class"] = definition.device_class
+        if definition.value_getter:
+            args["value_getter"] = definition.value_getter
+        args.update(definition.extra)
+        return BinarySensorEntity(**args)
+
+    elif definition.entity_type == EntityType.TEXT_SENSOR:
+        args = {**common_args}
+        if definition.value_getter:
+            args["value_getter"] = definition.value_getter
+        args.update(definition.extra)
+        return TextSensorEntity(**args)
+
+    elif definition.entity_type == EntityType.SWITCH:
+        args = {**common_args}
+        if definition.value_getter:
+            args["value_getter"] = definition.value_getter
+        if definition.command_handler:
+            args["command_handler"] = definition.command_handler
+        args.update(definition.extra)
+        return SwitchEntity(**args)
+
+    elif definition.entity_type == EntityType.SELECT:
+        args = {**common_args}
+        if definition.options:
+            args["options"] = definition.options
+        if definition.value_getter:
+            args["value_getter"] = definition.value_getter
+        if definition.command_handler:
+            args["command_handler"] = definition.command_handler
+        args.update(definition.extra)
+        return SelectEntity(**args)
+
+    elif definition.entity_type == EntityType.BUTTON:
+        args = {**common_args}
+        if definition.command_handler:
+            args["command_handler"] = definition.command_handler
+        args.update(definition.extra)
+        return ButtonEntity(**args)
+
+    elif definition.entity_type == EntityType.NUMBER:
+        args = {**common_args}
+        if definition.min_value is not None:
+            args["min_value"] = definition.min_value
+        if definition.max_value is not None:
+            args["max_value"] = definition.max_value
+        if definition.step is not None:
+            args["step"] = definition.step
+        if definition.mode is not None:
+            args["mode"] = definition.mode
+        if definition.unit_of_measurement:
+            args["unit_of_measurement"] = definition.unit_of_measurement
+        if definition.value_getter:
+            args["value_getter"] = definition.value_getter
+        if definition.command_handler:
+            # NumberEntity uses value_setter instead of command_handler
+            args["value_setter"] = definition.command_handler
+        args.update(definition.extra)
+        return NumberEntity(**args)
+
+    elif definition.entity_type == EntityType.CAMERA:
+        args = {**common_args}
+        args.update(definition.extra)
+        return CameraEntity(**args)
+
+    else:
+        raise ValueError(f"Unknown entity type: {definition.entity_type}")
+
+
+def create_entities(server, definitions: list[EntityDefinition]) -> list[Any]:
+    """Create multiple entities from definitions.
+
+    Args:
+        server: The VoiceSatelliteProtocol server instance
+        definitions: List of entity definitions
+
+    Returns:
+        List of created entity instances
+    """
+    entities = []
+    for definition in definitions:
+        try:
+            entity = create_entity(server, definition)
+            entities.append(entity)
+        except Exception as e:
+            _LOGGER.error("Failed to create entity %s: %s", definition.key_name, e)
+    return entities
+
+
+# ============================================================================
+# Predefined entity definition groups
+# ============================================================================
+
+
+def get_diagnostic_sensor_definitions() -> list[EntityDefinition]:
+    """Get definitions for diagnostic sensor entities."""
+    return [
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_cpu_percent",
+            name="System CPU Usage",
+            object_id="sys_cpu_percent",
+            icon="mdi:cpu-64-bit",
+            unit_of_measurement="%",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_cpu_temperature",
+            name="CPU Temperature",
+            object_id="sys_cpu_temperature",
+            icon="mdi:thermometer",
+            unit_of_measurement="°C",
+            accuracy_decimals=1,
+            device_class="temperature",
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_memory_percent",
+            name="System Memory Usage",
+            object_id="sys_memory_percent",
+            icon="mdi:memory",
+            unit_of_measurement="%",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_memory_used",
+            name="System Memory Used",
+            object_id="sys_memory_used",
+            icon="mdi:memory",
+            unit_of_measurement="GB",
+            accuracy_decimals=2,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_disk_percent",
+            name="System Disk Usage",
+            object_id="sys_disk_percent",
+            icon="mdi:harddisk",
+            unit_of_measurement="%",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_disk_free",
+            name="System Disk Free",
+            object_id="sys_disk_free",
+            icon="mdi:harddisk",
+            unit_of_measurement="GB",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_uptime",
+            name="System Uptime",
+            object_id="sys_uptime",
+            icon="mdi:clock-outline",
+            unit_of_measurement="h",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_process_cpu",
+            name="App CPU Usage",
+            object_id="sys_process_cpu",
+            icon="mdi:application-cog",
+            unit_of_measurement="%",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="sys_process_memory",
+            name="App Memory Usage",
+            object_id="sys_process_memory",
+            icon="mdi:application-cog",
+            unit_of_measurement="MB",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+    ]
+
+
+def get_imu_sensor_definitions() -> list[EntityDefinition]:
+    """Get definitions for IMU sensor entities."""
+    definitions = []
+
+    # Accelerometer
+    for axis in ["x", "y", "z"]:
+        definitions.append(
+            EntityDefinition(
+                entity_type=EntityType.SENSOR,
+                key_name=f"imu_accel_{axis}",
+                name=f"IMU Accel {axis.upper()}",
+                object_id=f"imu_accel_{axis}",
+                icon=f"mdi:axis-{axis}-arrow",
+                unit_of_measurement="m/s²",
+                accuracy_decimals=3,
+                state_class="measurement",
+            )
+        )
+
+    # Gyroscope
+    for axis in ["x", "y", "z"]:
+        definitions.append(
+            EntityDefinition(
+                entity_type=EntityType.SENSOR,
+                key_name=f"imu_gyro_{axis}",
+                name=f"IMU Gyro {axis.upper()}",
+                object_id=f"imu_gyro_{axis}",
+                icon="mdi:rotate-3d-variant",
+                unit_of_measurement="rad/s",
+                accuracy_decimals=3,
+                state_class="measurement",
+            )
+        )
+
+    # Temperature
+    definitions.append(
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="imu_temperature",
+            name="IMU Temperature",
+            object_id="imu_temperature",
+            icon="mdi:thermometer",
+            unit_of_measurement="°C",
+            accuracy_decimals=1,
+            device_class="temperature",
+            state_class="measurement",
+        )
+    )
+
+    return definitions
+
+
+def get_robot_info_definitions() -> list[EntityDefinition]:
+    """Get definitions for robot info entities."""
+    return [
+        EntityDefinition(
+            entity_type=EntityType.SENSOR,
+            key_name="control_loop_frequency",
+            name="Control Loop Frequency",
+            object_id="control_loop_frequency",
+            icon="mdi:speedometer",
+            unit_of_measurement="Hz",
+            accuracy_decimals=1,
+            state_class="measurement",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.TEXT_SENSOR,
+            key_name="sdk_version",
+            name="SDK Version",
+            object_id="sdk_version",
+            icon="mdi:information",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.TEXT_SENSOR,
+            key_name="robot_name",
+            name="Robot Name",
+            object_id="robot_name",
+            icon="mdi:robot",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.BINARY_SENSOR,
+            key_name="wireless_version",
+            name="Wireless Version",
+            object_id="wireless_version",
+            icon="mdi:wifi",
+            device_class="connectivity",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.BINARY_SENSOR,
+            key_name="simulation_mode",
+            name="Simulation Mode",
+            object_id="simulation_mode",
+            icon="mdi:virtual-reality",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.TEXT_SENSOR,
+            key_name="wlan_ip",
+            name="WLAN IP",
+            object_id="wlan_ip",
+            icon="mdi:ip-network",
+            entity_category=2,
+        ),
+        EntityDefinition(
+            entity_type=EntityType.TEXT_SENSOR,
+            key_name="error_message",
+            name="Error Message",
+            object_id="error_message",
+            icon="mdi:alert-circle",
+            entity_category=2,
+        ),
+    ]
+
+
+def get_pose_control_definitions() -> list[EntityDefinition]:
+    """Get definitions for pose control entities (Phase 3)."""
+    definitions = []
+
+    # Head position controls (X, Y, Z in mm)
+    for axis in ["x", "y", "z"]:
+        definitions.append(
+            EntityDefinition(
+                entity_type=EntityType.NUMBER,
+                key_name=f"head_{axis}",
+                name=f"Head {axis.upper()} Position",
+                object_id=f"head_{axis}",
+                icon=f"mdi:axis-{axis}-arrow",
+                min_value=-50.0,
+                max_value=50.0,
+                step=1.0,
+                unit_of_measurement="mm",
+                mode=2,  # slider
+            )
+        )
+
+    # Head orientation controls (Roll, Pitch in degrees)
+    for orient in ["roll", "pitch"]:
+        definitions.append(
+            EntityDefinition(
+                entity_type=EntityType.NUMBER,
+                key_name=f"head_{orient}",
+                name=f"Head {orient.capitalize()}",
+                object_id=f"head_{orient}",
+                icon="mdi:rotate-3d-variant",
+                min_value=-40.0,
+                max_value=40.0,
+                step=1.0,
+                unit_of_measurement="°",
+                mode=2,
+            )
+        )
+
+    # Head yaw (wider range)
+    definitions.append(
+        EntityDefinition(
+            entity_type=EntityType.NUMBER,
+            key_name="head_yaw",
+            name="Head Yaw",
+            object_id="head_yaw",
+            icon="mdi:rotate-3d-variant",
+            min_value=-180.0,
+            max_value=180.0,
+            step=1.0,
+            unit_of_measurement="°",
+            mode=2,
+        )
+    )
+
+    # Body yaw control
+    definitions.append(
+        EntityDefinition(
+            entity_type=EntityType.NUMBER,
+            key_name="body_yaw",
+            name="Body Yaw",
+            object_id="body_yaw",
+            icon="mdi:rotate-3d-variant",
+            min_value=-160.0,
+            max_value=160.0,
+            step=1.0,
+            unit_of_measurement="°",
+            mode=2,
+        )
+    )
+
+    # Antenna controls
+    for side, label in [("left", "L"), ("right", "R")]:
+        definitions.append(
+            EntityDefinition(
+                entity_type=EntityType.NUMBER,
+                key_name=f"antenna_{side}",
+                name=f"Antenna({label})",
+                object_id=f"antenna_{side}",
+                icon="mdi:antenna",
+                min_value=-180.0,
+                max_value=180.0,
+                step=1.0,
+                unit_of_measurement="°",
+                mode=2,
+            )
+        )
+
+    return definitions
+
+
+def get_look_at_definitions() -> list[EntityDefinition]:
+    """Get definitions for look-at control entities (Phase 4)."""
+    definitions = []
+
+    for axis in ["x", "y", "z"]:
+        definitions.append(
+            EntityDefinition(
+                entity_type=EntityType.NUMBER,
+                key_name=f"look_at_{axis}",
+                name=f"Look At {axis.upper()}",
+                object_id=f"look_at_{axis}",
+                icon="mdi:crosshairs-gps",
+                min_value=-2.0,
+                max_value=2.0,
+                step=0.1,
+                unit_of_measurement="m",
+                mode=1,  # Box mode for precise input
+            )
+        )
+
+    return definitions

reachy_mini_home_assistant/entities/entity_keys.py

@@ -0,0 +1,133 @@
+"""Entity key definitions for ESPHome entities.
+
+This module provides consistent entity key mappings for all HA entities.
+Keys are fixed to ensure consistency across restarts.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+# Fixed entity key mapping - ensures consistent keys across restarts
+# Keys are based on phase/category organization
+ENTITY_KEYS: dict[str, int] = {
+    # Media player (key 0 reserved)
+    "reachy_mini_media_player": 0,
+    # Phase 1: Basic status and volume (100-199)
+    "daemon_state": 100,
+    "backend_ready": 101,
+    "mute": 102,
+    "speaker_volume": 103,
+    "idle_behavior_enabled": 104,
+    "sendspin_enabled": 105,
+    "face_tracking_enabled": 106,
+    "gesture_detection_enabled": 107,
+    "face_confidence_threshold": 108,
+    "camera_disabled": 109,
+    # Phase 2: Runtime controls (200-299)
+    "motor_mode": 201,
+    # Phase 3: Pose control (300-399)
+    "head_x": 300,
+    "head_y": 301,
+    "head_z": 302,
+    "head_roll": 303,
+    "head_pitch": 304,
+    "head_yaw": 305,
+    "body_yaw": 306,
+    "antenna_left": 307,
+    "antenna_right": 308,
+    # Phase 4: Look at control (400-499)
+    "look_at_x": 400,
+    "look_at_y": 401,
+    "look_at_z": 402,
+    # Phase 5: DOA - Direction of Arrival (500-599)
+    "doa_angle": 500,
+    "speech_detected": 501,
+    # Phase 6: Diagnostic information (600-699)
+    "control_loop_frequency": 600,
+    "sdk_version": 601,
+    "robot_name": 602,
+    "wireless_version": 603,
+    "simulation_mode": 604,
+    "wlan_ip": 605,
+    "error_message": 606,
+    # Phase 7: IMU sensors (700-799)
+    "imu_accel_x": 700,
+    "imu_accel_y": 701,
+    "imu_accel_z": 702,
+    "imu_gyro_x": 703,
+    "imu_gyro_y": 704,
+    "imu_gyro_z": 705,
+    "imu_temperature": 706,
+    # Phase 8: Emotion selector (800-899)
+    "emotion": 800,
+    # Phase 10: Camera (1000-1099)
+    "camera_url": 1000,
+    "camera": 1001,
+    # Phase 21: Continuous conversation (1500-1599)
+    "continuous_conversation": 1500,
+    # Phase 22: Gesture detection (1600-1699)
+    "gesture_detected": 1600,
+    "gesture_confidence": 1601,
+    # Phase 23: Face detection (1700-1799)
+    "face_detected": 1700,
+    # Phase 24: System diagnostics (1800-1899)
+    "sys_cpu_percent": 1800,
+    "sys_cpu_temperature": 1801,
+    "sys_memory_percent": 1802,
+    "sys_memory_used": 1803,
+    "sys_disk_percent": 1804,
+    "sys_disk_free": 1805,
+    "sys_uptime": 1806,
+    "sys_process_cpu": 1807,
+    "sys_process_memory": 1808,
+    # Phase 25: Runtime service state (1900-1999)
+    "services_suspended": 1901,
+    # Phase 26: DOA tracking control (2000+)
+    "doa_tracking_enabled": 2000,
+}
+
+
+def get_entity_key(object_id: str) -> int:
+    """Get a consistent entity key for the given object_id.
+
+    Args:
+        object_id: The entity's object ID
+
+    Returns:
+        Integer key for the entity
+    """
+    if object_id in ENTITY_KEYS:
+        return ENTITY_KEYS[object_id]
+
+    # Fallback: generate key from hash (should not happen if all entities are registered)
+    logger.warning("Entity key not found for %s, generating from hash", object_id)
+    return abs(hash(object_id)) % 10000 + 2000
+
+
+def register_entity_key(object_id: str, key: int) -> None:
+    """Register a new entity key.
+
+    Args:
+        object_id: The entity's object ID
+        key: The key to assign
+    """
+    if object_id in ENTITY_KEYS:
+        logger.warning("Overwriting existing key for %s", object_id)
+    ENTITY_KEYS[object_id] = key
+
+
+def get_next_available_key(phase: int = 2000) -> int:
+    """Get the next available key in a phase range.
+
+    Args:
+        phase: The phase base (e.g., 2000 for phase 26+)
+
+    Returns:
+        Next available key in the range
+    """
+    phase_keys = [k for k in ENTITY_KEYS.values() if phase <= k < phase + 100]
+    if not phase_keys:
+        return phase
+    return max(phase_keys) + 1

reachy_mini_home_assistant/entities/entity_registry.py

@@ -0,0 +1,428 @@
+"""Entity registry for ESPHome entities.
+
+This module handles the registration and management of all ESPHome entities
+for the Reachy Mini voice assistant.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Optional
+
+from ..models import Preferences
+from .entity import BinarySensorEntity, NumberEntity, TextSensorEntity
+from .entity_extensions import SwitchEntity
+from .entity_keys import get_entity_key
+from .runtime_entity_setup import (
+    setup_behavior_entities,
+    setup_camera_entities,
+    setup_runtime_entities,
+    setup_service_entities,
+)
+from .sensor_entity_setup import (
+    append_defined_entities,
+    setup_audio_direction_entities,
+    setup_detection_entities,
+    setup_diagnostic_entities,
+    setup_imu_entities,
+    setup_motion_entities,
+    setup_robot_info_entities,
+)
+
+if TYPE_CHECKING:
+    from ..reachy_controller import ReachyController
+    from ..vision.camera_server import MJPEGCameraServer
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class EntityRegistry:
+    """Registry for managing ESPHome entities."""
+
+    def __init__(
+        self,
+        server,
+        reachy_controller: "ReachyController",
+        camera_server: Optional["MJPEGCameraServer"] = None,
+        play_emotion_callback: Callable[[str], None] | None = None,
+    ):
+        """Initialize the entity registry.
+
+        Args:
+            server: The VoiceSatelliteProtocol server instance
+            reachy_controller: The ReachyController instance
+            camera_server: Optional camera server for camera entity
+            play_emotion_callback: Optional callback for playing emotions
+        """
+        self.server = server
+        self.reachy_controller = reachy_controller
+        self.camera_server = camera_server
+        self._play_emotion_callback = play_emotion_callback
+
+        # Runtime state entities
+        self._services_suspended_entity: BinarySensorEntity | None = None
+        self._face_detected_entity: BinarySensorEntity | None = None
+        self._gesture_entity: TextSensorEntity | None = None
+        self._gesture_confidence_entity: SensorEntity | None = None
+        self._face_tracking_switch_entity: SwitchEntity | None = None
+        self._gesture_detection_switch_entity: SwitchEntity | None = None
+
+        # Gesture detection state
+        self._current_gesture = "none"
+        self._gesture_confidence = 0.0
+
+        # Emotion state
+        self._current_emotion = "None"
+        # Map emotion names to available robot emotions
+        # Full list of available emotions from robot
+        self._emotion_map = {
+            "None": None,
+            # Basic emotions
+            "Happy": "cheerful1",
+            "Sad": "sad1",
+            "Angry": "rage1",
+            "Fear": "fear1",
+            "Surprise": "surprised1",
+            "Disgust": "disgusted1",
+            # Extended emotions
+            "Laughing": "laughing1",
+            "Loving": "loving1",
+            "Proud": "proud1",
+            "Grateful": "grateful1",
+            "Enthusiastic": "enthusiastic1",
+            "Curious": "curious1",
+            "Amazed": "amazed1",
+            "Shy": "shy1",
+            "Confused": "confused1",
+            "Thoughtful": "thoughtful1",
+            "Anxious": "anxiety1",
+            "Scared": "scared1",
+            "Frustrated": "frustrated1",
+            "Irritated": "irritated1",
+            "Furious": "furious1",
+            "Contempt": "contempt1",
+            "Bored": "boredom1",
+            "Tired": "tired1",
+            "Exhausted": "exhausted1",
+            "Lonely": "lonely1",
+            "Downcast": "downcast1",
+            "Resigned": "resigned1",
+            "Uncertain": "uncertain1",
+            "Uncomfortable": "uncomfortable1",
+            "Lost": "lost1",
+            "Indifferent": "indifferent1",
+            # Positive actions
+            "Yes": "yes1",
+            "No": "no1",
+            "Welcoming": "welcoming1",
+            "Helpful": "helpful1",
+            "Attentive": "attentive1",
+            "Understanding": "understanding1",
+            "Calming": "calming1",
+            "Relief": "relief1",
+            "Success": "success1",
+            "Serenity": "serenity1",
+            # Negative actions
+            "Oops": "oops1",
+            "Displeased": "displeased1",
+            "Impatient": "impatient1",
+            "Reprimand": "reprimand1",
+            "GoAway": "go_away1",
+            # Special
+            "Come": "come1",
+            "Inquiring": "inquiring1",
+            "Sleep": "sleep1",
+            "Dance": "dance1",
+            "Electric": "electric1",
+            "Dying": "dying1",
+        }
+
+    def _get_preferences(self) -> Preferences | None:
+        return self.server.state.preferences
+
+    def _get_server_state(self):
+        return self.server.state
+
+    def _save_preferences(self) -> None:
+        self.server.state.save_preferences()
+
+    def _set_preference_and_save(self, key: str, value) -> None:
+        prefs = self._get_preferences()
+        if prefs is not None:
+            setattr(prefs, key, value)
+            self._save_preferences()
+
+    def _idle_behavior_allows_vision(self) -> bool:
+        prefs = self._get_preferences()
+        return bool(prefs.idle_behavior_enabled) if prefs is not None else False
+
+    def _apply_vision_runtime_state(self) -> None:
+        if self.camera_server is None:
+            return
+
+        prefs = self._get_preferences()
+        if prefs is None:
+            self.camera_server.apply_runtime_vision_state(
+                face_requested=False,
+                gesture_requested=False,
+                models_allowed=False,
+            )
+            return
+
+        self.camera_server.apply_runtime_vision_state(
+            face_requested=bool(prefs.face_tracking_enabled),
+            gesture_requested=bool(prefs.gesture_detection_enabled),
+            models_allowed=self._idle_behavior_allows_vision(),
+        )
+
+    def _get_pref_bool(self, key: str, default: bool = False) -> bool:
+        prefs = self._get_preferences()
+        return bool(getattr(prefs, key, default)) if prefs is not None else default
+
+    def _set_pref_bool(self, key: str, enabled: bool) -> None:
+        prefs = self._get_preferences()
+        if prefs is not None:
+            setattr(prefs, key, bool(enabled))
+            self._save_preferences()
+
+    def _get_pref_float(self, key: str, default: float) -> float:
+        prefs = self._get_preferences()
+        return float(getattr(prefs, key, default)) if prefs is not None else default
+
+    def _set_pref_float(self, key: str, value: float) -> None:
+        prefs = self._get_preferences()
+        if prefs is not None:
+            setattr(prefs, key, float(value))
+            self._save_preferences()
+
+    def _set_idle_behavior_enabled(self, enabled: bool) -> None:
+        self.reachy_controller.set_idle_behavior_enabled(enabled)
+
+        prefs = self._get_preferences()
+        if prefs is not None:
+            prefs.set_idle_behavior_enabled(enabled)
+            if not enabled:
+                prefs.face_tracking_enabled = False
+                prefs.gesture_detection_enabled = False
+            self._save_preferences()
+
+        voice_assistant = self.server._voice_assistant_service
+        if voice_assistant is not None:
+            voice_assistant.set_idle_behavior_enabled(enabled)
+
+        self._apply_vision_runtime_state()
+
+        if not enabled:
+            if self._face_tracking_switch_entity is not None:
+                self._face_tracking_switch_entity._value = False
+                self._face_tracking_switch_entity.update_state()
+            if self._gesture_detection_switch_entity is not None:
+                self._gesture_detection_switch_entity._value = False
+                self._gesture_detection_switch_entity.update_state()
+            if self._face_detected_entity is not None:
+                self._face_detected_entity._state = False
+                self._face_detected_entity.update_state()
+            if self._gesture_entity is not None:
+                self._gesture_entity._value = "none"
+                self._gesture_entity.update_state()
+            if self._gesture_confidence_entity is not None:
+                self._gesture_confidence_entity._state = 0.0
+                self._gesture_confidence_entity.update_state()
+
+    def _make_preference_switch(
+        self,
+        *,
+        key_name: str,
+        name: str,
+        object_id: str,
+        icon: str,
+        getter: Callable[[], bool],
+        setter: Callable[[bool], None],
+    ) -> SwitchEntity:
+        """Create a switch entity with the common registry wiring."""
+        return SwitchEntity(
+            server=self.server,
+            key=get_entity_key(key_name),
+            name=name,
+            object_id=object_id,
+            icon=icon,
+            entity_category=1,
+            value_getter=getter,
+            value_setter=setter,
+        )
+
+    def _make_stored_switch(
+        self,
+        *,
+        key_name: str,
+        name: str,
+        object_id: str,
+        icon: str,
+        pref_key: str,
+        getter_transform: Callable[[bool], bool] | None = None,
+        setter_transform: Callable[[bool], bool] | None = None,
+        after_set: Callable[[], None] | None = None,
+    ) -> SwitchEntity:
+        """Create a switch backed by preferences with optional transforms/hooks."""
+
+        def getter() -> bool:
+            value = self._get_pref_bool(pref_key)
+            return getter_transform(value) if getter_transform is not None else value
+
+        def setter(enabled: bool) -> None:
+            stored = setter_transform(enabled) if setter_transform is not None else enabled
+            self._set_pref_bool(pref_key, stored)
+            if after_set is not None:
+                after_set()
+
+        return self._make_preference_switch(
+            key_name=key_name,
+            name=name,
+            object_id=object_id,
+            icon=icon,
+            getter=getter,
+            setter=setter,
+        )
+
+    def _make_preference_number(
+        self,
+        *,
+        key_name: str,
+        name: str,
+        object_id: str,
+        icon: str,
+        getter: Callable[[], float],
+        setter: Callable[[float], None],
+        min_value: float,
+        max_value: float,
+        step: float,
+        mode: int = 2,
+    ) -> NumberEntity:
+        """Create a number entity with the common registry wiring."""
+        return NumberEntity(
+            server=self.server,
+            key=get_entity_key(key_name),
+            name=name,
+            object_id=object_id,
+            min_value=min_value,
+            max_value=max_value,
+            step=step,
+            icon=icon,
+            mode=mode,
+            entity_category=1,
+            value_getter=getter,
+            value_setter=setter,
+        )
+
+    def _append_defined_entities(
+        self,
+        entities: list,
+        definitions: list,
+        callback_map: dict[str, tuple[Callable, Callable] | Callable],
+    ) -> None:
+        """Bind callbacks to declarative definitions and append created entities."""
+        append_defined_entities(self, entities, definitions, callback_map)
+
+    def setup_all_entities(self, entities: list) -> None:
+        """Setup all entity phases."""
+        self._setup_phase1_entities(entities)
+        self._setup_phase2_entities(entities)
+        self._setup_phase3_entities(entities)
+        self._setup_phase4_entities(entities)
+        self._setup_phase5_entities(entities)  # DOA for wakeup turn-to-sound
+        self._setup_phase6_entities(entities)
+        self._setup_phase7_entities(entities)
+        self._setup_phase8_entities(entities)
+        self._setup_phase9_entities(entities)
+        self._setup_phase10_entities(entities)
+        # Phase 11 (LED control) disabled - LEDs are inside the robot and not visible
+        self._setup_phase12_entities(entities)
+        # Phase 13 (Sendspin) - auto-enabled via mDNS discovery, no user entities
+        # Phase 14 (head_joints, passive_joints) removed - not needed
+        # Phase 20 (Tap detection) disabled - too many false triggers
+        self._setup_phase21_entities(entities)
+        self._setup_phase22_entities(entities)
+        self._setup_phase23_entities(entities)
+        self._setup_phase24_entities(entities)  # System diagnostics
+
+        _LOGGER.info("All entities registered: %d total", len(entities))
+
+    def _setup_phase1_entities(self, entities: list) -> None:
+        setup_runtime_entities(self, entities)
+
+    def _setup_phase2_entities(self, entities: list) -> None:
+        setup_service_entities(self, entities)
+
+    def _setup_phase3_entities(self, entities: list) -> None:
+        setup_motion_entities(self, entities)
+
+    def _setup_phase4_entities(self, entities: list) -> None:
+        pass
+
+    def _setup_phase5_entities(self, entities: list) -> None:
+        setup_audio_direction_entities(self, entities)
+
+    def _setup_phase6_entities(self, entities: list) -> None:
+        setup_robot_info_entities(self, entities)
+
+    def _setup_phase7_entities(self, entities: list) -> None:
+        setup_imu_entities(self, entities)
+
+    def _setup_phase8_entities(self, entities: list) -> None:
+        setup_behavior_entities(self, entities)
+
+    def _setup_phase9_entities(self, entities: list) -> None:
+        """Setup Phase 9 entities: Audio controls."""
+        _LOGGER.debug("Phase 9 entities registered: none")
+
+    def _setup_phase10_entities(self, entities: list) -> None:
+        setup_camera_entities(self, entities)
+
+    def _setup_phase12_entities(self, entities: list) -> None:
+        """Setup Phase 12 entities: Audio processing parameters."""
+        _LOGGER.debug("Phase 12 entities registered: none")
+
+    def _setup_phase21_entities(self, entities: list) -> None:
+        pass
+
+    def _setup_phase22_entities(self, entities: list) -> None:
+        setup_detection_entities(self, entities)
+
+    def _setup_phase23_entities(self, entities: list) -> None:
+        pass
+
+    def update_face_detected_state(self) -> None:
+        """Push face_detected state update to Home Assistant."""
+        if self._face_detected_entity:
+            self._face_detected_entity.update_state()
+
+    def update_gesture_state(self) -> None:
+        """Push gesture state update to Home Assistant."""
+        if self._gesture_entity:
+            self._gesture_entity.update_state()
+        if self._gesture_confidence_entity:
+            self._gesture_confidence_entity.update_state()
+
+    def set_services_suspended(self, is_suspended: bool) -> None:
+        """Update the services suspended state and push to Home Assistant.
+
+        Args:
+            is_suspended: True if services are suspended (ML models unloaded)
+        """
+        if self._services_suspended_entity is not None:
+            # For "running" device_class, True = running, False = not running
+            # So we invert: suspended means NOT running
+            self._services_suspended_entity._state = not is_suspended
+            self._services_suspended_entity.update_state()
+            _LOGGER.debug("Services suspended state updated: suspended=%s", is_suspended)
+
+    def find_entity_references(self, entities: list) -> None:
+        """Find and store references to special entities from existing list.
+
+        Args:
+            entities: The list of existing entities to search
+        """
+        # DOA entities are read-only sensors, no special references needed
+        pass
+
+    def _setup_phase24_entities(self, entities: list) -> None:
+        setup_diagnostic_entities(self, entities)

reachy_mini_home_assistant/entities/event_emotion_mapper.py

@@ -0,0 +1,403 @@
+"""Built-in Home Assistant reactions and behavior orchestration for Reachy Mini.
+
+This module now mirrors the reference-project separation more closely:
+- `EventEmotionMapper` resolves HA state changes into normalized reactions
+- `BuiltinBehaviorController` executes the default zero-config behavior layer
+"""
+
+import json
+import logging
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from ..animations.animation_config import get_animation_config_section
+
+logger = logging.getLogger(__name__)
+
+_MODULE_DIR = Path(__file__).parent
+_PACKAGE_DIR = _MODULE_DIR.parent
+_UNIFIED_BEHAVIORS_FILE = _PACKAGE_DIR / "animations" / "conversation_animations.json"
+
+
+class EventSource(Enum):
+    """Source of HA events."""
+
+    BINARY_SENSOR = "binary_sensor"
+    SENSOR = "sensor"
+    SWITCH = "switch"
+    INPUT_BOOLEAN = "input_boolean"
+    WEATHER = "weather"
+    AUTOMATION = "automation"
+    CUSTOM = "custom"
+
+
+@dataclass
+class EventEmotionMapping:
+    """Mapping from HA event to robot emotion."""
+
+    entity_id: str
+    state_value: str  # The state that triggers the emotion
+    emotion: str  # Emotion animation name
+    cooldown: float = 60.0  # Minimum seconds between triggers
+    priority: int = 50  # Higher = more important (0-100)
+    description: str | None = None
+
+
+@dataclass
+class EventTrigger:
+    """Record of a triggered event."""
+
+    entity_id: str
+    old_state: str
+    new_state: str
+    timestamp: float
+    emotion: str | None = None
+
+
+SKILL_PLAY_EMOTION = "play_emotion"
+SKILL_TIMER_ALERT = "timer_alert"
+SKILL_ERROR_REACT = "error_react"
+VOICE_PHASE_LISTENING = "listening"
+VOICE_PHASE_THINKING = "thinking"
+VOICE_PHASE_SPEAKING = "speaking"
+VOICE_PHASE_IDLE = "idle"
+
+
+# Default emotion mappings based on common HA entities
+DEFAULT_EVENT_EMOTION_MAP: dict[str, list[EventEmotionMapping]] = {
+    # Door/window sensors
+    "binary_sensor.front_door": [
+        EventEmotionMapping(
+            entity_id="binary_sensor.front_door",
+            state_value="on",
+            emotion="curious1",
+            cooldown=30.0,
+            priority=70,
+            description="Someone at the door",
+        ),
+    ],
+    # Motion sensors
+    "binary_sensor.living_room_motion": [
+        EventEmotionMapping(
+            entity_id="binary_sensor.living_room_motion",
+            state_value="on",
+            emotion="surprised1",
+            cooldown=60.0,
+            priority=50,
+            description="Motion detected",
+        ),
+    ],
+    # Time-based triggers (via input_boolean)
+    "input_boolean.morning_routine": [
+        EventEmotionMapping(
+            entity_id="input_boolean.morning_routine",
+            state_value="on",
+            emotion="cheerful1",
+            cooldown=3600.0,  # Once per hour
+            priority=60,
+            description="Good morning!",
+        ),
+    ],
+    "input_boolean.bedtime_routine": [
+        EventEmotionMapping(
+            entity_id="input_boolean.bedtime_routine",
+            state_value="on",
+            emotion="sleep1",
+            cooldown=3600.0,
+            priority=60,
+            description="Bedtime",
+        ),
+    ],
+}
+
+
+class EventEmotionMapper:
+    """Maps Home Assistant state changes to normalized emotion reactions.
+
+    This class handles:
+    - Event to emotion mapping based on configuration
+    - Cooldown management to prevent spam
+    - Priority handling for conflicting emotions
+
+    Usage:
+        mapper = EventEmotionMapper()
+
+        # When HA state changes:
+        emotion = mapper.handle_state_change("binary_sensor.front_door", "off", "on")
+    """
+
+    def __init__(
+        self,
+        mappings: dict[str, list[EventEmotionMapping]] | None = None,
+        max_triggers_per_minute: int = 3,
+    ):
+        """Initialize the event emotion mapper.
+
+        Args:
+            mappings: Custom event mappings. Uses defaults if None.
+            max_triggers_per_minute: Rate limit for emotion triggers
+        """
+        self._mappings: dict[str, list[EventEmotionMapping]] = {}
+        self._last_trigger_times: dict[str, float] = {}
+        self._trigger_history: list[EventTrigger] = []
+        self._max_history = 100
+        self._triggers_this_minute = 0
+        self._minute_start_time = time.monotonic()
+        self._max_triggers_per_minute = max_triggers_per_minute
+        self._lock = threading.Lock()
+
+        # Load default or custom mappings
+        if mappings:
+            self._mappings = mappings
+        else:
+            self._mappings = DEFAULT_EVENT_EMOTION_MAP.copy()
+
+        # Time function (can be overridden for testing)
+        self._now = time.monotonic
+
+    def add_mapping(self, mapping: EventEmotionMapping) -> None:
+        """Add or update an event mapping."""
+        entity_id = mapping.entity_id
+        with self._lock:
+            if entity_id not in self._mappings:
+                self._mappings[entity_id] = []
+            # Remove existing mapping for same state
+            self._mappings[entity_id] = [m for m in self._mappings[entity_id] if m.state_value != mapping.state_value]
+            self._mappings[entity_id].append(mapping)
+        logger.debug("Added event mapping: %s -> %s", entity_id, mapping.emotion)
+
+    def remove_mapping(self, entity_id: str, state_value: str | None = None) -> None:
+        """Remove event mapping(s)."""
+        with self._lock:
+            if entity_id in self._mappings:
+                if state_value:
+                    self._mappings[entity_id] = [m for m in self._mappings[entity_id] if m.state_value != state_value]
+                else:
+                    del self._mappings[entity_id]
+
+    def handle_state_change(
+        self,
+        entity_id: str,
+        old_state: str,
+        new_state: str,
+    ) -> str | None:
+        """Handle a Home Assistant state change.
+
+        Args:
+            entity_id: Entity ID that changed
+            old_state: Previous state value
+            new_state: New state value
+
+        Returns:
+            Emotion name if triggered, None otherwise
+        """
+        now = self._now()
+
+        # Rate limiting
+        if not self._check_rate_limit(now):
+            logger.debug("Rate limit exceeded, skipping event")
+            return None
+
+        # Find matching mappings
+        with self._lock:
+            if entity_id not in self._mappings:
+                return None
+
+            mappings = self._mappings[entity_id]
+
+        # Find mapping for new state
+        matching = [m for m in mappings if m.state_value == new_state]
+        if not matching:
+            return None
+
+        # Get highest priority mapping
+        mapping = max(matching, key=lambda m: m.priority)
+
+        # Check cooldown
+        key = f"{entity_id}:{mapping.state_value}"
+        last_trigger = self._last_trigger_times.get(key, 0)
+        if now - last_trigger < mapping.cooldown:
+            logger.debug("Event %s in cooldown (%.0fs remaining)", entity_id, mapping.cooldown - (now - last_trigger))
+            return None
+
+        # Update cooldown and trigger
+        self._last_trigger_times[key] = now
+        self._triggers_this_minute += 1
+
+        # Record trigger
+        trigger = EventTrigger(
+            entity_id=entity_id,
+            old_state=old_state,
+            new_state=new_state,
+            timestamp=now,
+            emotion=mapping.emotion,
+        )
+        self._record_trigger(trigger)
+
+        return mapping.emotion
+
+    def _check_rate_limit(self, now: float) -> bool:
+        """Check if within rate limit."""
+        # Reset counter every minute
+        if now - self._minute_start_time >= 60.0:
+            self._minute_start_time = now
+            self._triggers_this_minute = 0
+
+        return self._triggers_this_minute < self._max_triggers_per_minute
+
+    def _record_trigger(self, trigger: EventTrigger) -> None:
+        """Record a trigger in history."""
+        self._trigger_history.append(trigger)
+        if len(self._trigger_history) > self._max_history:
+            self._trigger_history.pop(0)
+
+    def get_trigger_history(self) -> list[EventTrigger]:
+        """Get recent trigger history."""
+        return self._trigger_history.copy()
+
+    def get_mappings(self) -> dict[str, list[EventEmotionMapping]]:
+        """Get all current mappings."""
+        with self._lock:
+            return {k: v.copy() for k, v in self._mappings.items()}
+
+    def load_from_json(self, json_path: Path) -> bool:
+        """Load event mappings from a JSON file.
+
+        Args:
+            json_path: Path to JSON configuration file
+
+        Returns:
+            True if loaded successfully
+        """
+        if not json_path.exists():
+            logger.warning("Event mappings file not found: %s", json_path)
+            return False
+
+        try:
+            data = get_animation_config_section(json_path, "ha_event_behaviors") or {}
+
+            settings = data.get("settings", {})
+            self._max_triggers_per_minute = settings.get("max_triggers_per_minute", self._max_triggers_per_minute)
+
+            mappings_data = data.get("mappings", {})
+            for entity_id, states in mappings_data.items():
+                for state_config in states:
+                    mapping = EventEmotionMapping(
+                        entity_id=entity_id,
+                        state_value=state_config.get("state", "on"),
+                        emotion=state_config.get("emotion", ""),
+                        cooldown=state_config.get("cooldown", 60.0),
+                        priority=state_config.get("priority", 50),
+                        description=state_config.get("description"),
+                    )
+                    self.add_mapping(mapping)
+
+            logger.info("Loaded %d event mappings from %s", sum(len(v) for v in self._mappings.values()), json_path)
+            return True
+
+        except Exception as e:
+            logger.error("Failed to load event mappings: %s", e)
+            return False
+
+
+def load_event_mappings(json_path: Path | None = None) -> dict[str, list[EventEmotionMapping]]:
+    """Load event mappings from JSON file or return defaults.
+
+    Args:
+        json_path: Path to JSON file. If None, uses default location.
+
+    Returns:
+        Dictionary of entity_id to list of EventEmotionMapping
+    """
+    if json_path is None:
+        json_path = _UNIFIED_BEHAVIORS_FILE
+
+    if json_path.exists():
+        mapper = EventEmotionMapper()
+        if mapper.load_from_json(json_path):
+            return mapper.get_mappings()
+
+    return DEFAULT_EVENT_EMOTION_MAP.copy()
+
+
+class BuiltinBehaviorController:
+    """Execute zero-config built-in reactions.
+
+    This follows the reference-project separation of concerns:
+    protocol layer forwards normalized events here, and this controller
+    decides how to execute the default robot behavior.
+    """
+
+    def __init__(
+        self,
+        *,
+        event_mapper: EventEmotionMapper,
+        cancel_delayed_idle_return: Callable[[], None],
+        set_conversation_mode: Callable[[bool], None],
+        enter_motion_state: Callable[[str, str, bool | None], None],
+        run_motion_state: Callable[[str, str], None],
+        queue_emotion_move: Callable[[str], None],
+    ) -> None:
+        self._event_mapper = event_mapper
+        self._cancel_delayed_idle_return = cancel_delayed_idle_return
+        self._set_conversation_mode = set_conversation_mode
+        self._enter_motion_state = enter_motion_state
+        self._run_motion_state = run_motion_state
+        self._queue_emotion_move = queue_emotion_move
+
+    def handle_voice_phase(self, phase: str) -> None:
+        """Run the built-in robot behavior for a voice phase."""
+        if phase == VOICE_PHASE_LISTENING:
+            self._set_conversation_mode(True)
+            self._enter_motion_state(phase, "on_listening", face_tracking=True)
+            return
+
+        if phase == VOICE_PHASE_THINKING:
+            self._enter_motion_state(phase, "on_thinking", face_tracking=True)
+            return
+
+        if phase == VOICE_PHASE_SPEAKING:
+            self._enter_motion_state(phase, "on_speaking_start", face_tracking=False)
+            return
+
+        if phase == VOICE_PHASE_IDLE:
+            self._set_conversation_mode(False)
+            self._enter_motion_state(phase, "on_idle", face_tracking=True)
+            return
+
+        logger.debug("Unhandled built-in voice phase: %s", phase)
+
+    def execute_skill(
+        self,
+        skill: str,
+        *,
+        emotion_name: str | None = None,
+        event_name: str | None = None,
+        context: str | None = None,
+    ) -> None:
+        """Execute one normalized built-in skill."""
+        if skill == SKILL_PLAY_EMOTION:
+            if emotion_name:
+                self._queue_emotion_move(emotion_name)
+            return
+
+        if skill == SKILL_TIMER_ALERT:
+            self._run_motion_state(context or skill, "on_timer_finished")
+            return
+
+        if skill == SKILL_ERROR_REACT:
+            self._run_motion_state(context or skill, "on_error")
+            return
+
+        logger.debug("Unhandled built-in skill: %s", skill)
+
+    def handle_ha_state_change(self, entity_id: str, old_state: str, new_state: str) -> str | None:
+        """Resolve HA state changes into built-in reactions."""
+        emotion = self._event_mapper.handle_state_change(entity_id, old_state, new_state)
+        if emotion:
+            self.execute_skill(SKILL_PLAY_EMOTION, emotion_name=emotion, context=f"ha:{entity_id}")
+        return emotion

reachy_mini_home_assistant/entities/runtime_entity_setup.py

@@ -0,0 +1,257 @@
+"""Entity setup helpers for runtime/control related entities."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .entity import BinarySensorEntity, CameraEntity, NumberEntity, TextSensorEntity
+from .entity_extensions import SelectEntity, SensorEntity, SwitchEntity
+from .entity_keys import get_entity_key
+
+if TYPE_CHECKING:
+    from .entity_registry import EntityRegistry
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def setup_runtime_entities(registry: "EntityRegistry", entities: list) -> None:
+    rc = registry.reachy_controller
+
+    entities.append(
+        TextSensorEntity(
+            server=registry.server,
+            key=get_entity_key("daemon_state"),
+            name="Daemon State",
+            object_id="daemon_state",
+            icon="mdi:robot",
+            value_getter=rc.get_daemon_state,
+        )
+    )
+    entities.append(
+        BinarySensorEntity(
+            server=registry.server,
+            key=get_entity_key("backend_ready"),
+            name="Backend Ready",
+            object_id="backend_ready",
+            icon="mdi:check-circle",
+            device_class="connectivity",
+            value_getter=rc.get_backend_ready,
+        )
+    )
+    entities.append(
+        NumberEntity(
+            server=registry.server,
+            key=get_entity_key("speaker_volume"),
+            name="Speaker Volume",
+            object_id="speaker_volume",
+            min_value=0.0,
+            max_value=100.0,
+            step=1.0,
+            icon="mdi:volume-high",
+            unit_of_measurement="%",
+            mode=2,
+            entity_category=1,
+            value_getter=rc.get_speaker_volume,
+            value_setter=rc.set_speaker_volume,
+        )
+    )
+
+    def get_muted() -> bool:
+        state = registry._get_server_state()
+        return bool(state.is_muted)
+
+    def set_muted(muted: bool) -> None:
+        state = registry._get_server_state()
+        state.is_muted = muted
+        voice_assistant = registry.server._voice_assistant_service
+        if muted:
+            voice_assistant._suspend_voice_services(reason="mute")
+        else:
+            voice_assistant._resume_voice_services(reason="mute")
+
+    entities.append(
+        SwitchEntity(
+            server=registry.server,
+            key=get_entity_key("mute"),
+            name="Mute",
+            object_id="mute",
+            icon="mdi:microphone-off",
+            entity_category=1,
+            value_getter=get_muted,
+            value_setter=set_muted,
+        )
+    )
+
+    def get_camera_disabled() -> bool:
+        state = registry._get_server_state()
+        return not state.camera_enabled if state is not None else False
+
+    def set_camera_disabled(disabled: bool) -> None:
+        state = registry._get_server_state()
+        if state is None:
+            return
+        state.camera_enabled = not disabled
+        if registry.camera_server:
+            if disabled:
+                registry.camera_server.suspend()
+            else:
+                registry.camera_server.resume_from_suspend()
+
+    entities.append(
+        SwitchEntity(
+            server=registry.server,
+            key=get_entity_key("camera_disabled"),
+            name="Disable Camera",
+            object_id="camera_disabled",
+            icon="mdi:camera-off",
+            entity_category=1,
+            value_getter=get_camera_disabled,
+            value_setter=set_camera_disabled,
+        )
+    )
+
+    entities.append(
+        registry._make_preference_switch(
+            key_name="idle_behavior_enabled",
+            name="Idle Behavior",
+            object_id="idle_behavior_enabled",
+            icon="mdi:motion-play",
+            getter=lambda: bool(registry._get_preferences().idle_behavior_enabled)
+            if registry._get_preferences()
+            else False,
+            setter=registry._set_idle_behavior_enabled,
+        )
+    )
+
+    def sync_sendspin() -> None:
+        registry.server._voice_assistant_service.set_sendspin_enabled(registry._get_pref_bool("sendspin_enabled"))
+
+    entities.append(
+        registry._make_stored_switch(
+            key_name="sendspin_enabled",
+            name="Sendspin",
+            object_id="sendspin_enabled",
+            icon="mdi:speaker-wireless",
+            pref_key="sendspin_enabled",
+            after_set=sync_sendspin,
+        )
+    )
+    registry._face_tracking_switch_entity = registry._make_stored_switch(
+        key_name="face_tracking_enabled",
+        name="Face Tracking",
+        object_id="face_tracking_enabled",
+        icon="mdi:face-recognition",
+        pref_key="face_tracking_enabled",
+        after_set=registry._apply_vision_runtime_state,
+    )
+    entities.append(registry._face_tracking_switch_entity)
+
+    registry._gesture_detection_switch_entity = registry._make_stored_switch(
+        key_name="gesture_detection_enabled",
+        name="Gesture Detection",
+        object_id="gesture_detection_enabled",
+        icon="mdi:hand-wave",
+        pref_key="gesture_detection_enabled",
+        after_set=registry._apply_vision_runtime_state,
+    )
+    entities.append(registry._gesture_detection_switch_entity)
+
+    def get_face_confidence_threshold() -> float:
+        return registry._get_pref_float("face_confidence_threshold", 0.5)
+
+    def set_face_confidence_threshold(value: float) -> None:
+        value = max(0.0, min(1.0, float(value)))
+        registry._set_pref_float("face_confidence_threshold", value)
+        if registry.camera_server is not None:
+            registry.camera_server.set_face_confidence_threshold(value)
+
+    entities.append(
+        registry._make_preference_number(
+            key_name="face_confidence_threshold",
+            name="Face Confidence",
+            object_id="face_confidence_threshold",
+            icon="mdi:target",
+            getter=get_face_confidence_threshold,
+            setter=set_face_confidence_threshold,
+            min_value=0.0,
+            max_value=1.0,
+            step=0.01,
+        )
+    )
+
+    _LOGGER.debug("Phase 1 entities registered")
+
+
+def setup_service_entities(registry: "EntityRegistry", entities: list) -> None:
+    registry._services_suspended_entity = BinarySensorEntity(
+        server=registry.server,
+        key=get_entity_key("services_suspended"),
+        name="Services Suspended",
+        object_id="services_suspended",
+        icon="mdi:pause-circle",
+        device_class="running",
+    )
+    entities.append(registry._services_suspended_entity)
+    _LOGGER.debug("Service state entities registered")
+
+
+def setup_behavior_entities(registry: "EntityRegistry", entities: list) -> None:
+    def get_emotion() -> str:
+        return registry._current_emotion
+
+    def set_emotion(emotion: str) -> None:
+        registry._current_emotion = emotion
+        emotion_name = registry._emotion_map.get(emotion)
+        if emotion_name and registry._play_emotion_callback:
+            registry._play_emotion_callback(emotion_name)
+            registry._current_emotion = "None"
+
+    entities.append(
+        SelectEntity(
+            server=registry.server,
+            key=get_entity_key("emotion"),
+            name="Emotion",
+            object_id="emotion",
+            options=list(registry._emotion_map.keys()),
+            icon="mdi:emoticon",
+            value_getter=get_emotion,
+            value_setter=set_emotion,
+        )
+    )
+
+    entities.append(
+        SwitchEntity(
+            server=registry.server,
+            key=get_entity_key("continuous_conversation"),
+            name="Continuous Conversation",
+            object_id="continuous_conversation",
+            icon="mdi:message-reply-text",
+            device_class="switch",
+            entity_category=1,
+            value_getter=lambda: registry._get_pref_bool("continuous_conversation"),
+            value_setter=lambda enabled: registry._set_pref_bool("continuous_conversation", enabled),
+        )
+    )
+    _LOGGER.debug("Behavior entities registered")
+
+
+def setup_camera_entities(registry: "EntityRegistry", entities: list) -> None:
+    def get_camera_image() -> bytes | None:
+        if registry.camera_server:
+            try:
+                return registry.camera_server.get_snapshot()
+            except Exception as e:
+                _LOGGER.debug("Failed to get camera snapshot: %s", e)
+        return None
+
+    entities.append(
+        CameraEntity(
+            server=registry.server,
+            key=get_entity_key("camera"),
+            name="Camera",
+            object_id="camera",
+            icon="mdi:camera",
+            image_getter=get_camera_image,
+        )
+    )

reachy_mini_home_assistant/entities/sensor_entity_setup.py

@@ -0,0 +1,203 @@
+"""Entity setup helpers for sensors, diagnostics, and motion control entities."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from ..core.system_diagnostics import get_system_diagnostics
+from .entity import BinarySensorEntity, TextSensorEntity
+from .entity_extensions import SensorEntity, SwitchEntity
+from .entity_factory import (
+    create_entity,
+    get_diagnostic_sensor_definitions,
+    get_imu_sensor_definitions,
+    get_look_at_definitions,
+    get_pose_control_definitions,
+    get_robot_info_definitions,
+)
+from .entity_keys import get_entity_key
+
+if TYPE_CHECKING:
+    from .entity_registry import EntityRegistry
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def append_defined_entities(registry: "EntityRegistry", entities: list, definitions: list, callback_map: dict) -> None:
+    for definition in definitions:
+        callbacks = callback_map.get(definition.key_name)
+        if isinstance(callbacks, tuple):
+            definition.value_getter = callbacks[0]
+            definition.command_handler = callbacks[1]
+        elif callbacks is not None:
+            definition.value_getter = callbacks
+        entities.append(create_entity(registry.server, definition))
+
+
+def setup_motion_entities(registry: "EntityRegistry", entities: list) -> None:
+    rc = registry.reachy_controller
+    append_defined_entities(
+        registry,
+        entities,
+        get_pose_control_definitions(),
+        {
+            "head_x": (rc.get_head_x, rc.set_head_x),
+            "head_y": (rc.get_head_y, rc.set_head_y),
+            "head_z": (rc.get_head_z, rc.set_head_z),
+            "head_roll": (rc.get_head_roll, rc.set_head_roll),
+            "head_pitch": (rc.get_head_pitch, rc.set_head_pitch),
+            "head_yaw": (rc.get_head_yaw, rc.set_head_yaw),
+            "body_yaw": (rc.get_body_yaw, rc.set_body_yaw),
+            "antenna_left": (rc.get_antenna_left, rc.set_antenna_left),
+            "antenna_right": (rc.get_antenna_right, rc.set_antenna_right),
+        },
+    )
+    append_defined_entities(
+        registry,
+        entities,
+        get_look_at_definitions(),
+        {
+            "look_at_x": (rc.get_look_at_x, rc.set_look_at_x),
+            "look_at_y": (rc.get_look_at_y, rc.set_look_at_y),
+            "look_at_z": (rc.get_look_at_z, rc.set_look_at_z),
+        },
+    )
+    _LOGGER.debug("Motion entities registered")
+
+
+def setup_audio_direction_entities(registry: "EntityRegistry", entities: list) -> None:
+    rc = registry.reachy_controller
+    entities.append(
+        SensorEntity(
+            server=registry.server,
+            key=get_entity_key("doa_angle"),
+            name="DOA Angle",
+            object_id="doa_angle",
+            icon="mdi:surround-sound",
+            unit_of_measurement="°",
+            accuracy_decimals=1,
+            state_class="measurement",
+            value_getter=rc.get_doa_angle_degrees,
+        )
+    )
+    entities.append(
+        BinarySensorEntity(
+            server=registry.server,
+            key=get_entity_key("speech_detected"),
+            name="Speech Detected",
+            object_id="speech_detected",
+            icon="mdi:account-voice",
+            device_class="sound",
+            value_getter=rc.get_speech_detected,
+        )
+    )
+    entities.append(
+        SwitchEntity(
+            server=registry.server,
+            key=get_entity_key("doa_tracking_enabled"),
+            name="DOA Sound Tracking",
+            object_id="doa_tracking_enabled",
+            icon="mdi:ear-hearing",
+            value_getter=rc.get_doa_enabled,
+            value_setter=rc.set_doa_enabled,
+        )
+    )
+
+
+def setup_robot_info_entities(registry: "EntityRegistry", entities: list) -> None:
+    rc = registry.reachy_controller
+    append_defined_entities(
+        registry,
+        entities,
+        get_robot_info_definitions(),
+        {
+            "control_loop_frequency": rc.get_control_loop_frequency,
+            "sdk_version": rc.get_sdk_version,
+            "robot_name": rc.get_robot_name,
+            "wireless_version": rc.get_wireless_version,
+            "simulation_mode": rc.get_simulation_mode,
+            "wlan_ip": rc.get_wlan_ip,
+            "error_message": rc.get_error_message,
+        },
+    )
+
+
+def setup_imu_entities(registry: "EntityRegistry", entities: list) -> None:
+    rc = registry.reachy_controller
+    append_defined_entities(
+        registry,
+        entities,
+        get_imu_sensor_definitions(),
+        {
+            "imu_accel_x": rc.get_imu_accel_x,
+            "imu_accel_y": rc.get_imu_accel_y,
+            "imu_accel_z": rc.get_imu_accel_z,
+            "imu_gyro_x": rc.get_imu_gyro_x,
+            "imu_gyro_y": rc.get_imu_gyro_y,
+            "imu_gyro_z": rc.get_imu_gyro_z,
+            "imu_temperature": rc.get_imu_temperature,
+        },
+    )
+
+
+def setup_detection_entities(registry: "EntityRegistry", entities: list) -> None:
+    def get_gesture() -> str:
+        return registry.camera_server.get_current_gesture() if registry.camera_server else "none"
+
+    def get_gesture_confidence() -> float:
+        return registry.camera_server.get_gesture_confidence() if registry.camera_server else 0.0
+
+    registry._gesture_entity = TextSensorEntity(
+        server=registry.server,
+        key=get_entity_key("gesture_detected"),
+        name="Gesture Detected",
+        object_id="gesture_detected",
+        icon="mdi:hand-wave",
+        value_getter=get_gesture,
+    )
+    entities.append(registry._gesture_entity)
+
+    registry._gesture_confidence_entity = SensorEntity(
+        server=registry.server,
+        key=get_entity_key("gesture_confidence"),
+        name="Gesture Confidence",
+        object_id="gesture_confidence",
+        icon="mdi:percent",
+        unit_of_measurement="%",
+        accuracy_decimals=1,
+        state_class="measurement",
+        value_getter=get_gesture_confidence,
+    )
+    entities.append(registry._gesture_confidence_entity)
+
+    registry._face_detected_entity = BinarySensorEntity(
+        server=registry.server,
+        key=get_entity_key("face_detected"),
+        name="Face Detected",
+        object_id="face_detected",
+        icon="mdi:face-recognition",
+        device_class="occupancy",
+        value_getter=lambda: registry.camera_server.is_face_detected() if registry.camera_server else False,
+    )
+    entities.append(registry._face_detected_entity)
+
+
+def setup_diagnostic_entities(registry: "EntityRegistry", entities: list) -> None:
+    diag = get_system_diagnostics()
+    append_defined_entities(
+        registry,
+        entities,
+        get_diagnostic_sensor_definitions(),
+        {
+            "sys_cpu_percent": diag.get_cpu_percent,
+            "sys_cpu_temperature": diag.get_cpu_temperature,
+            "sys_memory_percent": diag.get_memory_percent,
+            "sys_memory_used": diag.get_memory_used_gb,
+            "sys_disk_percent": diag.get_disk_percent,
+            "sys_disk_free": diag.get_disk_free_gb,
+            "sys_uptime": diag.get_uptime_hours,
+            "sys_process_cpu": diag.get_process_cpu_percent,
+            "sys_process_memory": diag.get_process_memory_mb,
+        },
+    )

reachy_mini_home_assistant/main.py

@@ -0,0 +1,140 @@
+"""
+Reachy Mini for Home Assistant Application
+
+This is the main entry point for the Reachy Mini application that integrates
+with Home Assistant via ESPHome protocol for voice control.
+"""
+
+import asyncio
+import logging
+import sys
+import threading
+
+from reachy_mini import ReachyMiniApp
+
+from .voice_assistant import VoiceAssistantService
+
+logger = logging.getLogger(__name__)
+
+
+class ReachyMiniHaVoice(ReachyMiniApp):
+    """
+    Reachy Mini for Home Assistant Application.
+
+    This app runs an ESPHome-compatible server 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 via Home Assistant
+    custom_app_url: str | None = None
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the app."""
+        super().__init__(*args, **kwargs)
+        self.stop_event = threading.Event()
+
+    def wrapped_run(self, *args, **kwargs) -> None:
+        """
+        Override wrapped_run to handle Reachy Mini connection failures.
+        """
+        logger.info("Starting Reachy Mini HA Voice App...")
+
+        # Connect to ReachyMini
+        try:
+            logger.info("Attempting to connect to Reachy Mini...")
+            super().wrapped_run(*args, **kwargs)
+        except TimeoutError as e:
+            logger.error(f"Timeout connecting to Reachy Mini: {e}")
+            sys.exit(1)
+        except Exception as e:
+            error_str = str(e)
+            if "Unable to connect" in error_str or "Timeout" in error_str:
+                logger.error(f"Failed to connect to Reachy Mini: {e}")
+                sys.exit(1)
+            else:
+                raise
+
+    def run(self, reachy_mini, stop_event: threading.Event) -> None:
+        """
+        Main application entry point.
+
+        Args:
+            reachy_mini: The Reachy Mini robot instance (required, cannot be None)
+            stop_event: Event to signal graceful shutdown
+        """
+        logger.info("Starting Reachy Mini for Home Assistant...")
+
+        # Create and run the HA service
+        service = VoiceAssistantService(reachy_mini)
+
+        # Always create a new event loop to avoid conflicts with SDK
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        logger.debug("Created new event loop for HA service")
+
+        try:
+            loop.run_until_complete(service.start())
+
+            logger.info("=" * 50)
+            logger.info("Reachy Mini for Home Assistant Started!")
+            logger.info("=" * 50)
+            logger.info("ESPHome Server: 0.0.0.0:6053")
+            logger.info("Camera Server: 0.0.0.0:8081")
+            logger.info("Wake word: Okay Nabu")
+            logger.info("Motion control: enabled")
+            logger.info("Camera: enabled (Reachy Mini)")
+            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("  -> Generic Camera -> http://<ip>:8081/stream")
+            logger.info("=" * 50)
+
+            # Wait for stop signal - keep event loop running
+            # We need to keep the event loop alive to handle ESPHome connections
+            while not stop_event.is_set():
+                loop.run_until_complete(asyncio.sleep(0.1))
+
+        except KeyboardInterrupt:
+            logger.info("Keyboard interruption in main thread... closing server.")
+        except Exception as e:
+            logger.error(f"Error running Reachy Mini HA: {e}")
+            raise
+        finally:
+            logger.info("Shutting down Reachy Mini HA...")
+            try:
+                loop.run_until_complete(service.stop())
+            except Exception as e:
+                logger.error(f"Error stopping service: {e}")
+
+            # Note: Robot connection cleanup is handled by SDK's context manager
+            # in wrapped_run(). We only need to close our event loop here.
+
+            # Close event loop
+            try:
+                loop.close()
+            except Exception as e:
+                logger.debug(f"Error closing event loop: {e}")
+
+            logger.info("Reachy Mini HA stopped.")
+
+
+# This is called when running as: python -m reachy_mini_home_assistant.main
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    # Reduce verbosity for some noisy modules
+    logging.getLogger("reachy_mini.media.media_manager").setLevel(logging.WARNING)
+    logging.getLogger("reachy_mini.media.camera_base").setLevel(logging.WARNING)
+    logging.getLogger("reachy_mini.media.audio_base").setLevel(logging.WARNING)
+    logging.getLogger("matplotlib").setLevel(logging.WARNING)
+
+    app = ReachyMiniHaVoice()
+    try:
+        app.wrapped_run()
+    except KeyboardInterrupt:
+        app.stop()

reachy_mini_home_assistant/models.py

@@ -0,0 +1,178 @@
+"""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 typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import threading
+    from queue import Queue
+
+    from pymicro_wakeword import MicroWakeWord
+    from pyopen_wakeword import OpenWakeWord
+
+    from .audio.audio_player import AudioPlayer
+    from .entities.entity import ESPHomeEntity, MediaPlayerEntity
+    from .protocol.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
+    probability_cutoff: float = 0.7
+
+    def load(self) -> "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)
+            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)
+    # Continuous conversation mode (controlled from Home Assistant)
+    continuous_conversation: bool = False
+    # Unified idle behavior toggle (controlled from Home Assistant)
+    idle_behavior_enabled: bool = False
+    # Sendspin discovery and playback toggle (controlled from Home Assistant)
+    sendspin_enabled: bool = False
+    # Vision toggles and parameters (controlled from Home Assistant)
+    face_tracking_enabled: bool = False
+    gesture_detection_enabled: bool = False
+    face_confidence_threshold: float = 0.5
+
+    def set_idle_behavior_enabled(self, enabled: bool) -> None:
+        """Update the unified idle behavior toggle."""
+        self.idle_behavior_enabled = enabled
+
+
+@dataclass
+class ServerState:
+    """Global server state."""
+
+    name: str
+    mac_address: str
+    audio_queue: "Queue[bytes | None]"
+    entities: "list[ESPHomeEntity]"
+    available_wake_words: "dict[str, AvailableWakeWord]"
+    wake_words: "dict[str, 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: object
+    motion_enabled: bool = True
+    motion: object | None = None  # ReachyMiniMotion instance
+
+    media_player_entity: "MediaPlayerEntity | None" = None
+    satellite: "VoiceSatelliteProtocol | None" = None
+    wake_words_changed: bool = False
+    refractory_seconds: float = 2.0
+    timer_max_ring_seconds: float = 900.0
+    _entities_initialized: bool = False
+
+    _services_suspended: bool = False
+
+    # Mute state (controlled from Home Assistant) - thread-safe via properties
+    _is_muted: bool = False
+
+    # Camera state (controlled from Home Assistant) - thread-safe via properties
+    _camera_enabled: bool = True
+
+    # Thread safety
+    _state_lock: "threading.Lock | None" = None
+
+    def __post_init__(self):
+        """Initialize state lock after dataclass creation."""
+        import threading
+
+        object.__setattr__(self, "_state_lock", threading.Lock())
+
+    @property
+    def services_suspended(self) -> bool:
+        """Thread-safe getter for services_suspended."""
+        if self._state_lock is None:
+            return self._services_suspended
+        with self._state_lock:
+            return self._services_suspended
+
+    @services_suspended.setter
+    def services_suspended(self, value: bool) -> None:
+        """Thread-safe setter for services_suspended."""
+        if self._state_lock is None:
+            object.__setattr__(self, "_services_suspended", value)
+        else:
+            with self._state_lock:
+                object.__setattr__(self, "_services_suspended", value)
+
+    @property
+    def is_muted(self) -> bool:
+        """Thread-safe getter for is_muted."""
+        if self._state_lock is None:
+            return self._is_muted
+        with self._state_lock:
+            return self._is_muted
+
+    @is_muted.setter
+    def is_muted(self, value: bool) -> None:
+        """Thread-safe setter for is_muted."""
+        if self._state_lock is None:
+            object.__setattr__(self, "_is_muted", value)
+        else:
+            with self._state_lock:
+                object.__setattr__(self, "_is_muted", value)
+
+    @property
+    def camera_enabled(self) -> bool:
+        """Thread-safe getter for camera_enabled."""
+        if self._state_lock is None:
+            return self._camera_enabled
+        with self._state_lock:
+            return self._camera_enabled
+
+    @camera_enabled.setter
+    def camera_enabled(self, value: bool) -> None:
+        """Thread-safe setter for camera_enabled."""
+        if self._state_lock is None:
+            object.__setattr__(self, "_camera_enabled", value)
+        else:
+            with self._state_lock:
+                object.__setattr__(self, "_camera_enabled", value)
+
+    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)

reachy_mini_home_assistant/models/crops_classifier.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12a02344f63a7c4f2a2ca90f8740ca10a08c17b683b5585d73c3e88323056762
+size 411683