docs: translate PROJECT_PLAN.md to English

PROJECT_PLAN.md

@@ -1,29 +1,29 @@
-# Reachy Mini Home Assistant Voice Assistant - 项目计划
+# Reachy Mini Home Assistant Voice Assistant - Project Plan
 
-## 项目概述
+## Project Overview
 
-将 Home Assistant 语音助手功能集成到 Reachy Mini Wi-Fi版本机器人，通过 ESPHome 协议与 Home Assistant 通信。
+Integrate Home Assistant voice assistant functionality into Reachy Mini Wi-Fi robot, communicating with Home Assistant via ESPHome protocol.
 
-## 本地项目目录参考 (禁止修改参考目录内任何文件)
-1. [linux-voice-assistant](reference/linux-voice-assistant)，这是一个基于 Linux 的Home Assistant的语音助手应用，用于参考。
-2. [Reachy Mini SDK](reference/reachy_mini) 这是 Reachy Mini SDK 的本地项目目录，用于参考。
-3. [reachy_mini_conversation_app](reference/reachy_mini_conversation_app) - Reachy Mini 对话应用，用于参考
-4. [reachy-mini-desktop-app](reference/reachy-mini-desktop-app) - Reachy Mini 桌面应用，用于参考
-5. [sendspin](reference/sendspin-cli/) - sendspin client，用于参考
+## 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
 
-## 核心设计原则
+## Core Design Principles
 
-1. **零配置安装** - 用户只需安装应用，无需手动配置
-2. **使用 Reachy Mini 原生硬件** - 使用机器人自带的麦克风和扬声器
-3. **Home Assistant 集中管理** - 所有配置在 Home Assistant 端完成
-4. **运动反馈** - 语音交互时提供头部运动和天线动画反馈
-5. **项目约束** - 整个项目需要严格遵循 [Reachy Mini SDK](reachy_mini) 的架构设计与约束
-6. **代码质量** - 严格遵循Python开发的标准，并做到代码风格一致，代码结构清晰，注释完整，文档完善，测试覆盖率高，代码质量高，代码可读性高，代码可维护性高，代码可扩展性高，代码可复用性高
-7. **功能优先级** - 与home assistant的语音对话为最高优先级，任何其它的功能都是辅助功能，不能影响语音对话的功能和响应速度
-8. **不调用任何LED功能** - LED都被隐藏在了机器人内部，所有的LED控制全部都忽略，不要使用LED控制
-9. **保留功能优先** - 任何代码修改都应该在保留已完成功能的前提下优化，不能以去除功能的方式来解决问题。当有问题发生时，应该充分参考案例之后以解决问题为优先级，而不是添加各种日志输出为优先级
+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** - All configuration done 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
+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
 
-## 技术架构
+## Technical Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -40,16 +40,16 @@
 │                                                             │
 │  ┌─────────────────────────────────────────────────────┐   │
 │  │ Camera + Face Tracking (YOLO)                       │   │
-│  │ - 15Hz 人脸检测与追踪                                │   │
-│  │ - look_at_image() 计算目标姿态                       │   │
-│  │ - 人脸丢失后平滑回中性位置                            │   │
+│  │ - 15Hz face detection and tracking                  │   │
+│  │ - look_at_image() calculates target pose            │   │
+│  │ - Smooth return to neutral position after face lost │   │
 │  └─────────────────────────────────────────────────────┘   │
 │                                                             │
 │  ┌─────────────────────────────────────────────────────┐   │
 │  │ Motion Controller (Head + Antennas) - 5Hz           │   │
 │  │ - Face tracking offsets (secondary pose)            │   │
-│  │ - Speech sway (语音驱动微动)                         │   │
-│  │ - Breathing animation (空闲呼吸)                     │   │
+│  │ - Speech sway (voice-driven micro-movements)        │   │
+│  │ - Breathing animation (idle breathing)              │   │
 │  │ - on_wakeup → on_listening → on_speaking → on_idle  │   │
 │  └─────────────────────────────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────┘
@@ -65,1035 +65,348 @@
 └─────────────────────────────────────────────────────────────┘
 ```
 
-## 已完成功能
-
-### 核心功能
-- [x] ESPHome 协议服务器实现
-- [x] mDNS 服务发现（自动被 Home Assistant 发现）
-- [x] 本地唤醒词检测（microWakeWord）
-- [x] 拍一拍唤醒（IMU 加速度检测，仅无线版本）
-- [x] 音频流传输到 Home Assistant
-- [x] TTS 音频播放
-- [x] 停止词检测
-
-### Reachy Mini 集成
-- [x] 使用 Reachy Mini SDK 的麦克风输入
-- [x] 使用 Reachy Mini SDK 的扬声器输出
-- [x] 头部运动控制（点头、摇头、注视）
-- [x] 天线动画控制
-- [x] 语音状态反馈动作
-- [x] YOLO 人脸追踪（替代 DOA 声源定位）
-- [x] 5Hz 统一运动控制循环
-
-### 应用架构
-- [x] 符合 Reachy Mini App 架构
-- [x] 自动下载唤醒词模型
-- [x] 自动下载音效文件
-- [x] 无需 .env 配置文件
-
-## 文件清单
+## 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] Tap-to-wake (IMU acceleration detection, wireless version only)
+- [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 (replaces DOA sound source localization)
+- [x] 5Hz unified motion control loop
+
+### Application Architecture
+- [x] Compliant with Reachy Mini App architecture
+- [x] Auto-download wake word models
+- [x] Auto-download sound effect files
+- [x] No .env configuration file required
+
+## File List
 
 ```
 reachy_mini_ha_voice/
 ├── reachy_mini_ha_voice/
-│   ├── __init__.py             # 包初始化
-│   ├── __main__.py  py         # 命令行入口
-│   ├── main.py                 # ReachyMiniApp 入口
-│   ├── voice_assistant.py      # 语音助手服务
-│   ├── satellite.py            # ESPHome 协议处理
-│   ├── audio_player.py         # 音频播放器
-│   ├── camera_server.py        # MJPEG 摄像头流服务器 + 人脸追踪
-│   ├── head_tracker.py         # YOLO 人脸检测器
-│   ├── motion.py               # 运动控制 (高层 API)
-│   ├── movement_manager.py     # 统一运动管理器 (20Hz 控制循环，优化以防止 daemon 崩溃)
-│   ├── models.py               # 数据模型
-│   ├── entity.py               # ESPHome 基础实体
-│   ├── entity_extensions.py    # 扩展实体类型
-│   ├── reachy_controller.py    # Reachy Mini 控制器包装
-│   ├── api_server.py           # API 服务器
-│   ├── zeroconf.py             # mDNS 发现
-│   └── util.py                 # 工具函数
-├── wakewords/                  # 唤醒词模型（自动下载）
-│   ├── okay_nabu.json
-│   ├── okay_nabu.tflite
-│   ├── hey_jarvis.json
-│   ├── hey_jarvis.tflite
-│   ├── stop.json
-│   └── stop.tflite
-├── sounds/                     # 音效文件（自动下载）
-│   ├── wake_word_triggered.flac
-│   └── timer_finished.flac
-├── pyproject.toml              # 项目配置
-├── README.md                   # 说明文档
-└── PROJECT_PLAN.md             # 项目计划
+│   ├── __init__.py             # Package initialization
+│   ├── __main__.py             # Command line entry
+│   ├── main.py                 # ReachyMiniApp entry
+│   ├── voice_assistant.py      # Voice assistant service
+│   ├── satellite.py            # ESPHome protocol handling
+│   ├── audio_player.py         # Audio player
+│   ├── camera_server.py        # MJPEG camera stream server + face tracking
+│   ├── head_tracker.py         # YOLO face detector
+│   ├── motion.py               # Motion control (high-level API)
+│   ├── movement_manager.py     # Unified movement manager (20Hz control loop)
+│   ├── models.py               # Data models
+│   ├── entity.py               # ESPHome base entity
+│   ├── entity_extensions.py    # Extended entity types
+│   ├── reachy_controller.py    # Reachy Mini controller wrapper
+│   ├── api_server.py           # API server
+│   ├── zeroconf.py             # mDNS discovery
+│   └── util.py                 # Utility functions
+├── wakewords/                  # Wake word models (auto-download)
+├── sounds/                     # Sound effect files (auto-download)
+├── pyproject.toml              # Project configuration
+├── README.md                   # Documentation
+└── PROJECT_PLAN.md             # Project plan
 ```
 
-## 依赖项
-
-```toml
-dependencies = [
-    "reachy-mini",           # Reachy Mini SDK
-    "sounddevice>=0.4.6",    # 音频处理（备用）
-    "soundfile>=0.12.0",     # 音频文件读取
-    "numpy>=1.24.0",         # 数值计算
-    "pymicro-wakeword>=2.0.0,<3.0.0",  # 唤醒词检测
-    "pyopen-wakeword>=1.0.0,<2.0.0",   # 备用唤醒词
-    "aioesphomeapi>=42.0.0", # ESPHome 协议
-    "zeroconf>=0.100.0",     # mDNS 发现
-    "scipy>=1.10.0",         # 运动控制
-    "pydantic>=2.0.0",       # 数据验证
-]
-```
-
-## 使用流程
-
-1. **安装应用**
-   - 从 Reachy Mini App Store 安装`reachy-mini-ha-voice`
-
-2. **启动应用**
-   - 应用自动启动 ESPHome 服务器（端口 6053）
-   - 自动下载所需模型和音效
-
-3. **连接 Home Assistant**
-   - Home Assistant 自动发现设备（mDNS）
-   - 或手动添加：设置 → 设备与服务 → 添加集成 → ESPHome
-
-4. **使用语音助手**
-   - 说 "Okay Nabu" 唤醒
-   - 说出命令
-   - Reachy Mini 会做出运动反馈
-
-## ESPHome 实体规划
-
-基于 Reachy Mini SDK 深入分析，以下实体已暴露给 Home Assistant：
-
-### 已实现实体
-
-| 实体类型 | 名称 | 说明 |
-|---------|------|------|
-| Media Player | `media_player` | 音频播放控制 |
-| Voice Assistant | `voice_assistant` | 语音助手管道 |
-
-### 已实现的控制实体 (Controls) - 可读写
-
-#### Phase 1-3: 基础控制与姿态
-
-| ESPHome 实体类型 | 名称 | SDK API | 范围/选项 | 说明 |
-|-----------------|------|---------|----------|------|
-| `Number` | `speaker_volume` | `AudioPlayer.set_volume()` | 0-100 | 扬声器音量 |
-| `Select` | `motor_mode` | `set_motor_control_mode()` | enabled/disabled/gravity_compensation | 电机模式选择 |
-| `Switch` | `motors_enabled` | `enable_motors()` / `disable_motors()` | on/off | 电机扭矩开关 |
-| `Button` | `wake_up` | `mini.wake_up()` | - | 唤醒机器人动作 |
-| `Button` | `go_to_sleep` | `mini.goto_sleep()` | - | 睡眠机器人动作 |
-| `Number` | `head_x` | `goto_target(head=...)` | ±50mm | 头部 X 位置控制 |
-| `Number` | `head_y` | `goto_target(head=...)` | ±50mm | 头部 Y 位置控制 |
-| `Number` | `head_z` | `goto_target(head=...)` | ±50mm | 头部 Z 位置控制 |
-| `Number` | `head_roll` | `goto_target(head=...)` | -40° ~ +40° | 头部翻滚角控制 |
-| `Number` | `head_pitch` | `goto_target(head=...)` | -40° ~ +40° | 头部俯仰角控制 |
-| `Number` | `head_yaw` | `goto_target(head=...)` | -180° ~ +180° | 头部偏航角控制 |
-| `Number` | `body_yaw` | `goto_target(body_yaw=...)` | -160° ~ +160° | 身体偏航角控制 |
-| `Number` | `antenna_left` | `goto_target(antennas=...)` | -90° ~ +90° | 左天线角度控制 |
-| `Number` | `antenna_right` | `goto_target(antennas=...)` | -90° ~ +90° | 右天线角度控制 |
-
-#### Phase 4: 注视控制
-
-| ESPHome 实体类型 | 名称 | SDK API | 范围/选项 | 说明 |
-|-----------------|------|---------|----------|------|
-| `Number` | `look_at_x` | `look_at_world(x, y, z)` | 世界坐标 | 注视点 X 坐标 |
-| `Number` | `look_at_y` | `look_at_world(x, y, z)` | 世界坐标 | 注视点 Y 坐标 |
-| `Number` | `look_at_z` | `look_at_world(x, y, z)` | 世界坐标 | 注视点 Z 坐标 |
-
-### 已实现的传感器实体 (Sensors) - 只读
-
-#### Phase 1 & 5: 基础状态与音频传感器
-
-| ESPHome 实体���型 | 名称 | SDK API | 说明 |
-|-----------------|------|---------|------|
-| `Text Sensor` | `daemon_state` | `DaemonStatus.state` | Daemon 状态 |
-| `Binary Sensor` | `backend_ready` | `backend_status.ready` | 后端是否就绪 |
-| `Text Sensor` | `error_message` | `DaemonStatus.error` | 当前错误信息 |
-| `Sensor` | `doa_angle` | `DoAInfo.angle` | 声源方向角度 (°) |
-| `Binary Sensor` | `speech_detected` | `DoAInfo.speech_detected` | 是否检测到语音 |
-
-#### Phase 6: 诊断信息
-
-| ESPHome 实体类型 | 名称 | SDK API | 说明 |
-|-----------------|------|---------|------|
-| `Sensor` | `control_loop_frequency` | `control_loop_stats` | 控制循环频率 (Hz) |
-| `Text Sensor` | `sdk_version` | `DaemonStatus.version` | SDK 版本号 |
-| `Text Sensor` | `robot_name` | `DaemonStatus.robot_name` | 机器人名称 |
-| `Binary Sensor` | `wireless_version` | `DaemonStatus.wireless_version` | 是否为无线版本 |
-| `Binary Sensor` | `simulation_mode` | `DaemonStatus.simulation_enabled` | 是否在仿真模式 |
-| `Text Sensor` | `wlan_ip` | `DaemonStatus.wlan_ip` | 无线网络 IP |
-
-#### Phase 7: IMU 传感器 (仅无线版本)
-
-| ESPHome 实体类型 | 名称 | SDK API | 说明 |
-|-----------------|------|---------|------|
-| `Sensor` | `imu_accel_x` | `mini.imu["accelerometer"][0]` | X 轴加速度 (m/s²) |
-| `Sensor` | `imu_accel_y` | `mini.imu["accelerometer"][1]` | Y 轴加速度 (m/s²) |
-| `Sensor` | `imu_accel_z` | `mini.imu["accelerometer"][2]` | Z 轴加速度 (m/s²) |
-| `Sensor` | `imu_gyro_x` | `mini.imu["gyroscope"][0]` | X 轴角速度 (rad/s) |
-| `Sensor` | `imu_gyro_y` | `mini.imu["gyroscope"][1]` | Y 轴角速度 (rad/s) |
-| `Sensor` | `imu_gyro_z` | `mini.imu["gyroscope"][2]` | Z 轴角速度 (rad/s) |
-| `Sensor` | `imu_temperature` | `mini.imu["temperature"]` | IMU 温度 (°C) |
-
-#### Phase 8-12: 扩展功能
-
-| ESPHome 实体类型 | 名称 | 说明 |
-|-----------------|------|------|
-| `Select` | `emotion` | 表情选择器 (Happy/Sad/Angry/Fear/Surprise/Disgust) |
-| `Number` | `microphone_volume` | 麦克风音量 (0-100%) |
-| `Camera` | `camera` | ESPHome Camera 实体（实时预览） |
-| `Number` | `led_brightness` | LED 亮度 (0-100%) |
-| `Select` | `led_effect` | LED 效果 (off/solid/breathing/rainbow/doa) |
-| `Number` | `led_color_r` | LED 红色分量 (0-255) |
-| `Number` | `led_color_g` | LED 绿色分量 (0-255) |
-| `Number` | `led_color_b` | LED 蓝色分量 (0-255) |
-| `Switch` | `agc_enabled` | 自动增益控制开关 |
-| `Number` | `agc_max_gain` | AGC 最大增益 (0-30 dB) |
-| `Number` | `noise_suppression` | 噪声抑制级别 (0-100%) |
-| `Binary Sensor` | `echo_cancellation_converged` | 回声消除收敛状态 |
-
-> **注意**: 头部位置 (x/y/z) 和角度 (roll/pitch/yaw)、身体偏航角、天线角度都是**可控制**的实体，
-> 使用 `Number` 类型实现双向控制。设置新值时调用 `goto_target()`，读取当前值时调用 `get_current_head_pose()` 等。
-
-### 实现优先级
-
-1. **Phase 1 - 基础状态与音量** (高优先级) ✅ **已完成**
-   - [x] `daemon_state` - Daemon 状态传感器
-   - [x] `backend_ready` - 后端就绪状态
-   - [x] `error_message` - 错误信息
-   - [x] `speaker_volume` - 扬声器音量控制
-
-2. **Phase 2 - 电机控制** (高优先级) ✅ **已完成**
-   - [x] `motors_enabled` - 电机开关
-   - [x] `motor_mode` - 电机模式选择 (enabled/disabled/gravity_compensation)
-   - [x] `wake_up` / `go_to_sleep` - 唤醒/睡眠按钮
-
-3. **Phase 3 - 姿态控制** (中优先级) ✅ **已完成**
-   - [x] `head_x/y/z` - 头部位置控制
-   - [x] `head_roll/pitch/yaw` - 头部角度控制
-   - [x] `body_yaw` - 身体偏航角控制
-   - [x] `antenna_left/right` - 天线角度控制
-
-4. **Phase 4 - 注视控制** (中优先级) ✅ **已完成**
-   - [x] `look_at_x/y/z` - 注视点坐标控制
-
-5. **Phase 5 - 音频传感器** (低优先级) ✅ **已完成**
-   - [x] `doa_angle` - 声源方向
-   - [x] `speech_detected` - 语音检测
-
-6. **Phase 6 - 诊断信息** (低优先级) ✅ **已完成**
-   - [x] `control_loop_frequency` - 控制循环频率
-   - [x] `sdk_version` - SDK 版本
-   - [x] `robot_name` - 机器人名称
-   - [x] `wireless_version` - 无线版本标识
-   - [x] `simulation_mode` - 仿真模式标识
-   - [x] `wlan_ip` - 无线 IP 地址
-
-7. **Phase 7 - IMU 传感器** (可选，仅无线版本) ✅ **已完成**
-   - [x] `imu_accel_x/y/z` - 加速度计
-   - [x] `imu_gyro_x/y/z` - 陀螺仪
-   - [x] `imu_temperature` - IMU 温度
-
-8. **Phase 8 - 表情控制** ✅ **已完成**
-   - [x] `emotion` - 表情选择器 (Happy/Sad/Angry/Fear/Surprise/Disgust)
-
-9. **Phase 9 - 音频控制** ✅ **已完成**
-   - [x] `microphone_volume` - 麦克风音量控制 (0-100%)
-
-10. **Phase 10 - 摄像头集成** ✅ **已完成**
-    - [x] `camera` - ESPHome Camera 实体（实时预览）
-
-11. **Phase 11 - LED 控制** ❌ **已禁用（LED 隐藏在机器人内部）**
-    - [ ] `led_brightness` - LED 亮度 (0-100%) - 已注释
-    - [ ] `led_effect` - LED 效果 (off/solid/breathing/rainbow/doa) - 已注释
-    - [ ] `led_color_r/g/b` - LED RGB 颜色 (0-255) - 已注释
-
-12. **Phase 12 - 音频处理参数** ✅ **已完成**
-    - [x] `agc_enabled` - 自动增益控制开关
-    - [x] `agc_max_gain` - AGC 最大增益 (0-30 dB)
-    - [x] `noise_suppression` - 噪声抑制级别 (0-100%)
-    - [x] `echo_cancellation_converged` - 回声消除收敛状态（只读）
-
-13. **Phase 13 - Sendspin 音频播放支持** ✅ **已完成**
-    - [x] `sendspin_enabled` - Sendspin 开关 (Switch)
-    - [x] `sendspin_url` - Sendspin 服务器 URL (Text Sensor)
-    - [x] `sendspin_connected` - Sendspin 连接状态 (Binary Sensor)
-    - [x] AudioPlayer 集成 aiosendspin 库
-    - [x] TTS 音频同时发送到本地扬声器和 Sendspin 服务器
-
----
-
-## 🎉 Phase 1-13 实体已完成！
-
-**已完成总计：43 个实体**
-- Phase 1: 4 个实体 (基础状态与音量)
-- Phase 2: 4 个实体 (电机控制)
-- Phase 3: 9 个实体 (姿态控制)
-- Phase 4: 3 个实体 (注视控制)
-- Phase 5: 2 个实体 (音频传感器)
-- Phase 6: 6 个实体 (诊断信息)
-- Phase 7: 7 个实体 (IMU 传感器)
-- Phase 8: 1 个实体 (表情控制)
-- Phase 9: 1 个实体 (麦克风音量)
-- Phase 10: 1 个实体 (摄像头)
-- Phase 11: 0 个实体 (LED 控制 - 已禁用)
-- Phase 12: 4 个实体 (音频处理参数)
-- Phase 13: 3 个实体 (Sendspin 音频输出)
-
----
-
-## 🚀 语音助手增强功能实现状态
-
-### Phase 14 - 情感动作反馈系统 (部分实现) 🟡
-
-**实现状态**: 基础架构已就绪,支持手动触发,对话时使用语音驱动的自然微动
-
-**已实现功能**:
-- ✅ Phase 8 Emotion Selector 实体 (`emotion`)
-- ✅ 基础情感动作播放API (`_play_emotion`)
-- ✅ 情感映射: Happy/Sad/Angry/Fear/Surprise/Disgust
-- ✅ 与 HuggingFace 动作库集成 (`pollen-robotics/reachy-mini-emotions-library`)
-- ✅ 对话时使用 SpeechSway 系统提供自然的头部微动 (不阻塞对话体验)
-
-**设计决策**:
-- 🎯 对话时不自动播放完整情感动作,避免阻塞对话体验
-- 🎯 使用语音驱动的头部摆动 (SpeechSway) 提供自然的动作反馈
-- 🎯 情感动作保留为手动触发功能,可通过 ESPHome 实体控制
-
-**未实现功能**:
-- ❌ 自动根据语音助手响应触发情感动作 (已决定不实现,避免阻塞)
-- ❌ 意图识别与情感匹配
-- ❌ 舞蹈动作库集成
-- ❌ 上下文感知(如天气查询-晴天播放 happy,雨天播放 sad)
-
-**代码位置**:
-- `entity_registry.py:633-658` - Emotion Selector 实体
-- `satellite.py:544-574` - `_play_emotion()` 方法
-- `motion.py:132-156` - 对话开始时的动作控制 (使用 SpeechSway)
-- `movement_manager.py:541-595` - Move 队列管理 (允许 SpeechSway 叠加)
-
-**实际行为**:
-
-| 语音助手事件 | 实际动作 | 实现状态 |
-|-------------|---------|---------|
-| 唤醒词检测 | 转向声源 + 点头确认 | ✅ 已实现 |
-| 对话开始 | 语音驱动的头部微动 (SpeechSway) | ✅ 已实现 |
-| 对话进行中 | 持续的语音驱动微动 + 呼吸动画 | ✅ 已实现 |
-| 对话结束 | 返回中立位置 + 呼吸动画 | ✅ 已实现 |
-| 手动触发情感 | 通过 ESPHome `emotion` 实体播放 | ✅ 已实现 |
-
-**技术说明**:
-```python
-# motion.py - 对话时使用 SpeechSway 而非完整情感动作
-def on_speaking_start(self):
-    self._is_speaking = True
-    self._movement_manager.set_state(RobotState.SPEAKING)
-    # SpeechSway 会自动根据音频响度产生自然的头部微动
-    # 不播放完整情感动作,避免阻塞对话体验
-
-# movement_manager.py - 动作分层系统
-# 1. Move 队列 (情感动作) - 设置基础姿态
-# 2. Action (点头/摇头等) - 叠加在基础姿态上
-# 3. SpeechSway - 语音驱动微动,可与 Move 共存
-# 4. Breathing - 空闲时的呼吸动画
-```
-
-**原始规划** (已决定不实现,避免阻塞对话):
-
-| 语音助手事件 | 原计划动作 | 不实现原因 |
-|-------------|---------|---------|
-| 收到肯定回复 | 播放 "happy" 动作 | 完整动作会阻塞对话流畅性 |
-| 收到否定回复 | 播放 "sad" 动作 | 完整动作会阻塞对话流畅性 |
-| 播放音乐/娱乐 | 播放 "dance" 动作 | 完整动作会阻塞对话流畅性 |
-| 定时器完成 | 播放 "alert" 动作 | 完整动作会阻塞对话流畅性 |
-| 错误/无法理解 | 播放 "confused" 动作 | 完整动作会阻塞对话流畅性 |
-
-**手动触发情感动作示例**:
-```yaml
-# Home Assistant 自动化示例 - 手动触发情感
-automation:
-  - alias: "Reachy 早安问候"
-    trigger:
-      - platform: time
-        at: "07:00:00"
-    action:
-      - service: select.select_option
-        target:
-          entity_id: select.reachy_mini_emotion
-        data:
-          option: "Happy"
-```
-
-### Phase 15 - 人脸追踪（替代 DOA 声源追踪）✅ **已完成**
-
-**目标**: 实现自然的人脸追踪，让机器人在对话时注视说话人。
-
-**设计决策**: 
-- ❌ 原计划使用 DOA (Direction of Arrival) 声源追踪
-- ✅ 改用 YOLO 人脸检测，更稳定、更准确
-- 原因：DOA 在唤醒时判断不够准确，且频繁查询会导致 daemon 崩溃
-
-**已实现功能**:
-
-| 功能 | 说明 | 实现位置 | 实现状态 |
-|------|------|---------|---------|
-| YOLO 人脸检测 | 使用 `AdamCodd/YOLOv11n-face-detection` 模型 | `head_tracker.py` | ✅ 已实现 |
-| 自适应帧率追踪 | 对话时15fps，空闲无人脸时3fps | `camera_server.py` | ✅ 已实现 |
-| look_at_image() | 根据人脸位置计算目标姿态 | `camera_server.py` | ✅ 已实现 |
-| 平滑回中性位置 | 人脸丢失后 1 秒内平滑回归 | `camera_server.py` | ✅ 已实现 |
-| face_tracking_offsets | 作为 secondary pose 叠加到运动控制 | `movement_manager.py` | ✅ 已实现 |
-| 语音活动检测 | DOA 实体仍可用于检测语音 | `DoAInfo.speech_detected` | ✅ 已暴露为实体 |
-| 模型下载重试 | 3次重试，5秒间隔 | `head_tracker.py` | ✅ 已实现 |
-| 对话模式联动 | 语音助手状态变化时自动切换追踪频率 | `satellite.py` | ✅ 已实现 |
-
-**资源优化 (v0.5.1)**:
-- 对话期间（listening/thinking/speaking）：高频追踪 15fps
-- 空闲且检测到人脸：高频追踪 15fps
-- 空闲且10秒无人脸：低功耗模式 3fps（仅检测是否有人出现）
-- 检测到人脸后立即恢复高频追踪
-
-**代码位置**:
-- `head_tracker.py` - YOLO 人脸检测器 (`HeadTracker` 类)
-- `camera_server.py:_capture_frames()` - 自适应帧率人脸追踪
-- `camera_server.py:set_conversation_mode()` - 对话模式切换 API
-- `satellite.py:_set_conversation_mode()` - 语音助手状态联动
-- `movement_manager.py:set_face_tracking_offsets()` - 人脸追踪偏移量 API
-
-**技术细节**:
-```python
-# camera_server.py - 自适应帧率人脸追踪
-class MJPEGCameraServer:
-    def __init__(self):
-        self._fps_high = 15  # 对话/有人脸时
-        self._fps_low = 3    # 空闲无人脸时
-        self._low_power_threshold = 10.0  # 10秒无人脸切换低功耗
-    
-    def _should_run_face_tracking(self, current_time):
-        # 对话模式：始终高频追踪
-        if self._in_conversation:
-            return True
-        # 高频模式：每帧追踪
-        if self._current_fps == self._fps_high:
-            return True
-        # 低功耗模式：周期性检测
-        return time.since_last_check >= 1/self._fps_low
-
-# satellite.py - 语音助手状态联动
-def _reachy_on_listening(self):
-    self._set_conversation_mode(True)  # 开始对话，高频追踪
-    
-def _reachy_on_idle(self):
-    self._set_conversation_mode(False)  # 结束对话，自适应追踪
-```
-
-### Phase 16 - 卡通风格运动模式 (部分实现) 🟡
-
-**目标**: 使用 SDK 的插值技术让机器人动作更有个性和表现力。
-
-**SDK 支持**: `InterpolationTechnique` 枚举
-- `LINEAR` - 线性，机械感
-- `MIN_JERK` - 最小加加速度，自然平滑（默认）
-- `EASE_IN_OUT` - 缓入缓出，优雅
-- `CARTOON` - 卡通风格，带回弹效果，活泼可爱
-
-**已实现功能**:
-- ✅ 20Hz 统一控制循环 (`movement_manager.py`) - 从 100Hz 降低以防止 daemon 崩溃
-- ✅ 姿态变化检测 - 仅在姿态显著变化时发送命令 (阈值 0.001)
-- ✅ 状态查询缓存 - 100ms TTL，减少 daemon 负载
-- ✅ 平滑插值动作 (ease in-out 曲线)
-- ✅ 呼吸动画 - 空闲时 Z 轴微动 + 天线摆动 (`BreathingAnimation`)
-- ✅ 命令队列模式 - 线程安全的外部 API
-- ✅ 错误节流 - 防止日志爆炸
-- ✅ 连接健康监控 - 自动检测和恢复连接丢失
-
-**未实现功能**:
-- ❌ 动态插值技术切换 (CARTOON/EASE_IN_OUT 等)
-- ❌ 夸张的卡通回弹效果
-
-**代码位置**:
-- `movement_manager.py:192-243` - BreathingAnimation 类
-- `movement_manager.py:246-697` - MovementManager 类
-
-**场景实现状态**:
-
-| 场景 | 推荐插值 | 效果 | 实现状态 |
-|------|---------|------|---------|
-| 唤醒点头 | `CARTOON` | 活泼的回弹效果 | ❌ 未实现 |
-| 思考抬头 | `EASE_IN_OUT` | 优雅的过渡 | ✅ 已实现 (平滑插值) |
-| 说话时微动 | `MIN_JERK` | 自然流畅 | ✅ 已实现 (SpeechSway) |
-| 错误摇头 | `CARTOON` | 夸张的否定 | ❌ 未实现 |
-| 返回中立 | `MIN_JERK` | 平滑归位 | ✅ 已实现 |
-| 空闲呼吸 | - | 微妙的生命感 | ✅ 已实现 (BreathingAnimation) |
-
-### Phase 17 - 说话时天线同步动画 (部分实现) 🟡
-
-**目标**: TTS 播放时，天线随音频节奏摆动，模拟"说话"效果。
-
-**已实现功能**:
-- ✅ 语音驱动头部摆动 (`SpeechSwayGenerator`)
-- ✅ 基于音频响度的 VAD 检测
-- ✅ 多频率正弦波叠加 (Lissajous 运动)
-- ✅ 平滑包络过渡
-
-**代码位置**:
-- `movement_manager.py:124-189` - SpeechSwayGenerator 类
-- `motion.py:212-222` - update_audio_loudness() 方法
-
-**技术细节**:
-```python
-# 语音摆动参数
-SWAY_A_PITCH_DEG = 3.0   # 俯仰幅度 (度)
-SWAY_A_YAW_DEG = 2.0     # 偏航幅度
-SWAY_A_ROLL_DEG = 2.0    # 翻滚幅度
-SWAY_F_PITCH = 0.8       # 俯仰频率 Hz
-SWAY_F_YAW = 0.6         # 偏航频率
-SWAY_F_ROLL = 0.5        # 翻滚频率
-
-# VAD 阈值
-VAD_DB_ON = -35   # 开始检测阈值
-VAD_DB_OFF = -45  # 停止检测阈值
-```
-
-**未实现功能**:
-- ❌ 天线随音频节奏摆动 (当前仅头部摆动)
-- ❌ 音频频谱分析驱动动画
-
-### Phase 18 - 视觉注视交互 (未实现) ❌
-
-**目标**: 利用摄像头检测人脸，实现眼神交流。
-
-**SDK 支持**:
-- `look_at_image(u, v)` - 注视图像中的点
-- `look_at_world(x, y, z)` - 注视世界坐标点
-- `media.get_frame()` - 获取摄像头画面 (✅ 已在 `camera_server.py:146` 实现)
-
-**未实现功能**:
-
-| 功能 | 说明 | 实现状态 |
-|------|------|---------|
-| 人脸检测 | 使用 OpenCV/MediaPipe 检测人脸 | ❌ 未实现 |
-| 眼神追踪 | 对话时注视说话人的脸 | ❌ 未实现 |
-| 多人切换 | 检测到多人时，注视当前说话人 | ❌ 未实现 |
-| 空闲扫视 | 空闲时随机环顾四周 | ❌ 未实现 |
-
-### Phase 19 - 重力补偿互动模式 (部分实现) 🟡
-
-**目标**: 允许用户物理触摸和引导机器人头部，实现"教学"式交互。
-
-**SDK 支持**: `enable_gravity_compensation()` - 电机进入重力补偿模式，可手动移动
-
-**已实现功能**:
-- ✅ 重力补偿模式切换 (`motor_mode` Select 实体，选项 "gravity_compensation")
-- ✅ `reachy_controller.py:236-237` - 重力补偿 API 调用
-
-**未实现功能**:
-- ❌ 教学模式 - 录制动作轨迹
-- ❌ 保存/播放自定义动作
-- ❌ 语音命令触发教学流程
-
-**应用场景**:
-- ❌ 用户说 "让我教你一个动作" → 进入重力补偿模式
-- ❌ 用户手动移动头部 → 录制动作轨迹
-- ❌ 用户说 "记住这个" → 保存动作
-- ❌ 用户说 "做刚才的动作" → 播放录制的动作
-
-### Phase 20 - 环境感知响应 (部分实现) 🟡
-
-**目标**: 利用 IMU 传感器感知环境变化并做出响应。
-
-**SDK 支持**:
-- ✅ `mini.imu["accelerometer"]` - 加速度计 (Phase 7 已实现为实体)
-- ✅ `mini.imu["gyroscope"]` - 陀螺仪 (Phase 7 已实现为实体)
-
-**已实现功能**:
-
-| 检测事件 | 响应动作 | 实现状态 |
-|---------|---------|---------|
-| 拍一拍唤醒 | 进入持续对话模式 | ✅ 已实现 |
-| 再次拍一拍 | 退出持续对话模式 | ✅ 已实现 |
-
-**拍一拍唤醒 vs 语音唤醒**:
-
-| 唤醒方式 | 对话模式 | 说明 |
-|---------|---------|------|
-| 语音唤醒 (Okay Nabu) | 单次对话 | 每次对话需要重新说唤醒词 |
-| 拍一拍唤醒 | 持续对话 | TTS 结束后自动继续监听，再拍一次退出 |
-
-**技术实现**:
-- `tap_detector.py` - IMU 加速度突变检测
-- `satellite.py:_tap_conversation_mode` - 持续对话模式标志
-- 阈值: 2.0g (可配置)
-- 冷却时间: 1.0s (防止重复触发)
-- 仅限无线版本 (Wireless) 可用
-
-```python
-# satellite.py - 持续对话模式
-def wakeup_from_tap(self):
-    if self._tap_conversation_mode:
-        # 第二次拍 - 退出持续对话
-        self._tap_conversation_mode = False
-        self._reachy_on_idle()
-    else:
-        # 第一次拍 - 进入持续对话
-        self._tap_conversation_mode = True
-        self.send_messages([VoiceAssistantRequest(start=True)])
-
-def _tts_finished(self):
-    if self._tap_conversation_mode:
-        # 持续对话模式：自动继续监听
-        self.send_messages([VoiceAssistantRequest(start=True)])
-```
-
-**未实现功能**:
-
-| 检测事件 | 响应动作 | 实现状态 |
-|---------|---------|---------|
-| 被摇晃 | 播放晕眩动作 + 语音 "别晃我~" | ❌ 未实现 |
-| 倾斜/倒下 | 播放求助动作 + 语音 "我倒了，帮帮我" | ❌ 未实现 |
-| 长时间静止 | 进入休眠动画 | ❌ 未实现 |
-
-### Phase 21 - Home Assistant 场景联动 (未实现) ❌
-
-**目标**: 根据 Home Assistant 的场景/自动化触发机器人动作。
-
-**实现方案**: 通过 ESPHome 服务调用
-
-**未实现场景**:
-
-| HA 场景 | 机器人响应 | 实现状态 |
-|--------|-----------|---------|
-| 早安场景 | 播放唤醒动作 + "早上好!" | ❌ 未实现 |
-| 晚安场景 | 播放睡眠动作 + "晚安~" | ❌ 未实现 |
-| 有人回家 | 转向门口 + 挥手 + "欢迎回家!" | ❌ 未实现 |
-| 门铃响起 | 转向门口 + 警觉动作 | ❌ 未实现 |
-| 播放音乐 | 随音乐节奏摆动 | ❌ 未实现 |
-
----
-
-## 📊 功��实现总结
+## Usage Flow
 
-### ✅ 已完成功能
-
-#### 核心语音助手 (Phase 1-12)
-- **45+ ESPHome 实体** - 全部实现
-- **基础语音交互** - 唤醒词检测、STT/TTS 集成
-- **运动反馈** - 点头、摇头、注视等基础动作
-- **音频处理** - AGC、噪声抑制、回声消除
-- **摄像头流** - MJPEG 实时预览
-
-#### 部分实现功能 (Phase 14-21)
-- **Phase 14** - 情感动作 API 基础设施 (手动触发可用)
-- **Phase 19** - 重力补偿模式切换 (教学流程未实现)
-
-### ❌ 未实现功能
-
-#### 高优先级
-- ~~**Phase 13** - Sendspin 音频播放支持~~ ✅ **已完成**
-- **Phase 14** - 自动情感动作反馈 (需与语音助手事件关联)
-- **Phase 15** - 持续声源追踪 (仅唤醒时转向)
-
-#### 中优先级
-- **Phase 16** - 卡通风格运动模式 (需动态插值切换)
-- **Phase 17** - 天线同步动画
-- **Phase 18** - 人脸追踪与眼神交互
-
-#### 低优先级
-- **Phase 19** - 教学模式录制/播放功能
-- **Phase 20** - IMU 环境感知响应
-- **Phase 21** - Home Assistant 场景联动
-
----
-
-## 功能优先级总结 (更新版)
-
-### 高优先级 (已完成 ✅)
-- ✅ **Phase 1-12**: 基础 ESPHome 实体 (45+ 个)
-- ✅ 核心语音助手功能
-- ✅ 基础运动反馈 (点头、摇头、注视)
-
-### 高优先级 (部分实现 🟡)
-- 🟡 **Phase 13**: 情感动作反馈系统
-  - ✅ Emotion Selector 实体与 API 基础设施
-  - ❌ 自动根据语音助手响应触发情感动作
-  - ❌ 意图识别与情感匹配
-  - ❌ 舞蹈动作库集成
-
-### 高优先级 (未实现 ❌)
-- ❌ **Phase 14**: 智能声源追踪增强
-  - ✅ 唤醒时转向声源
-  - ❌ 持续声源追踪
-  - ❌ 多人对话切换
-  - ❌ 声源可视化
-
-### 中优先级 (部分实现 🟡)
-- 🟡 **Phase 15**: 卡通风格运动模式
-  - ✅ 20Hz 统一控制循环架构 (优化以防止 daemon 崩溃)
-  - ✅ 姿态变化检测 + 状态查询缓存 (减少 daemon 负载)
-  - ✅ 平滑插值动作 + 呼吸动画
-  - ❌ 动态插值技术切换 (CARTOON 等)
-- 🟡 **Phase 16**: 说话时天线同步
-  - ✅ 语音驱动头部摆动 (SpeechSwayGenerator)
-  - ❌ 天线随音频节奏摆动
-
-### 中优先级 (未实现 ❌)
-- ❌ **Phase 17**: 视觉注视交互 - 眼神交流
-
-### 低优先级 (部分实现 🟡)
-- 🟡 **Phase 18**: 重力补偿互动模式
-  - ✅ 重力补偿模式切换
-  - ❌ 教学式交互 (录制/播放功能)
-
-### 低优先级 (未实现 ❌)
-- ❌ **Phase 19**: 环境感知响应 - IMU 触发动作
-- ❌ **Phase 20**: Home Assistant 场景联动 - 智能家居整合
+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 via Settings → Devices & Services → Add Integration → ESPHome
+4. **Use Voice Assistant** - Say "Okay Nabu" to wake, speak command, Reachy Mini provides motion feedback
 
 ---
 
-## 📈 完成度统计
-
-| 阶段 | 状态 | 完成度 | 说明 |
-|------|------|--------|------|
-| Phase 1-12 | ✅ 完成 | 100% | 40 个 ESPHome 实体已实现（Phase 11 LED 已禁用） |
-| Phase 13 | 🟡 部分完成 | 30% | API 基础设施就绪,缺自动触发 |
-| Phase 14 | ❌ 未完成 | 20% | 仅实现唤醒时转向 |
-| Phase 15 | 🟡 部分完成 | 70% | 20Hz控制循环+姿态变化检测+状态缓存+呼吸动画已实现 |
-| Phase 16 | 🟡 部分完成 | 50% | 语音驱动头部摆动已实现 |
-| Phase 17 | ❌ 未完成 | 10% | 摄像头已实现,缺人脸检测 |
-| Phase 18 | 🟡 部分完成 | 40% | 模式切换已实现,缺教学流程 |
-| Phase 19 | ❌ 未完成 | 10% | IMU 数据已暴露,缺触发逻辑 |
-| Phase 20 | ❌ 未完成 | 0% | 完全未实现 |
-
-**总体完成度**: **Phase 1-12: 100%** | **Phase 13-20: ~35%**
+## ESPHome Entity Implementation
+
+### Completed Entities Summary
+
+**Total: 43+ entities implemented**
+- Phase 1-4: Basic controls, motor control, pose control, gaze control
+- Phase 5-7: Audio sensors, diagnostics, IMU sensors
+- Phase 8-12: Emotion control, microphone volume, camera, audio processing
+- Phase 13: Sendspin audio output support
+
+### Control Entities (Read/Write)
+
+| Entity Type | Name | Description |
+|-------------|------|-------------|
+| `Number` | `speaker_volume` | Speaker volume (0-100) |
+| `Select` | `motor_mode` | Motor mode (enabled/disabled/gravity_compensation) |
+| `Switch` | `motors_enabled` | Motor torque switch |
+| `Button` | `wake_up` / `go_to_sleep` | Wake/sleep robot actions |
+| `Number` | `head_x/y/z` | Head position control (±50mm) |
+| `Number` | `head_roll/pitch/yaw` | Head angle control |
+| `Number` | `body_yaw` | Body yaw angle (-160° ~ +160°) |
+| `Number` | `antenna_left/right` | Antenna angle control (±90°) |
+| `Number` | `look_at_x/y/z` | Gaze point coordinates |
+| `Select` | `emotion` | Emotion selector (Happy/Sad/Angry/Fear/Surprise/Disgust) |
+| `Number` | `microphone_volume` | Microphone volume (0-100%) |
+| `Switch` | `agc_enabled` | Auto gain control switch |
+| `Number` | `agc_max_gain` | AGC max gain (0-30 dB) |
+| `Number` | `noise_suppression` | Noise suppression level (0-100%) |
+| `Number` | `tap_sensitivity` | Tap detection sensitivity (0.5-4.0g) |
+| `Switch` | `sendspin_enabled` | Sendspin switch |
+
+### Sensor Entities (Read-only)
+
+| Entity Type | Name | Description |
+|-------------|------|-------------|
+| `Text Sensor` | `daemon_state` | Daemon status |
+| `Binary Sensor` | `backend_ready` | Backend ready status |
+| `Text Sensor` | `error_message` | Current error message |
+| `Sensor` | `doa_angle` | Sound source direction angle |
+| `Binary Sensor` | `speech_detected` | Speech detection status |
+| `Sensor` | `control_loop_frequency` | Control loop frequency (Hz) |
+| `Text Sensor` | `sdk_version` | SDK version |
+| `Text Sensor` | `robot_name` | Robot name |
+| `Binary Sensor` | `wireless_version` | Wireless version flag |
+| `Binary Sensor` | `simulation_mode` | Simulation mode flag |
+| `Text Sensor` | `wlan_ip` | Wireless IP address |
+| `Sensor` | `imu_accel_x/y/z` | Accelerometer (m/s²) |
+| `Sensor` | `imu_gyro_x/y/z` | Gyroscope (rad/s) |
+| `Sensor` | `imu_temperature` | IMU temperature (°C) |
+| `Binary Sensor` | `echo_cancellation_converged` | Echo cancellation convergence status |
+| `Camera` | `camera` | ESPHome Camera entity |
+| `Text Sensor` | `sendspin_url` | Sendspin server URL |
+| `Binary Sensor` | `sendspin_connected` | Sendspin connection status |
 
 ---
 
-## 🔧 Daemon 崩溃问题修复 (2025-01-05)
-
-### 问题描述
-长期运行过程中，`reachy_mini daemon` 会崩溃，导致机器人失去响应。
-
-### 根本原因
-1. **100Hz 控制循环过于频繁** - 每 10ms 调用一次 `robot.set_target()`，即使姿态没有变化
-2. **频繁的状态查询** - 每次读取实体状态都调用 `get_status()`、`get_current_head_pose()` 等
-3. **缺少变化检测** - 即使姿态没有变化，也会持续发送相同的命令
-4. **Zenoh 消息队列堵塞** - 累积起来可能每秒 150+ 条消息，daemon 无法及时处理
-
-### 修复方案
+## Voice Assistant Enhancement Features
 
-#### 1. 降低控制循环频率 (movement_manager.py)
-```python
-# 从 100Hz 降低到 20Hz
-CONTROL_LOOP_FREQUENCY_HZ = 20  # 减少 80% 的消息量
-```
-
-#### 2. 添加姿态变化检测 (movement_manager.py)
-```python
-# 仅在姿态显著变化时发送命令
-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:  # 阈值: 0.001 rad 或 0.001 m
-        return  # 跳过发送
-```
+### Phase 14 - Emotion Action Feedback System 🟡 Partial
 
-#### 3. 状态查询缓存 (reachy_controller.py)
-```python
-# 缓存 daemon 状态查询结果
-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')  # 使用缓存
-    # ... 查询并更新缓存
-```
+**Status**: Basic infrastructure ready, supports manual trigger, uses voice-driven natural micro-movements during conversation
 
-#### 4. 头部姿态查询缓存 (reachy_controller.py)
-```python
-# 缓存 get_current_head_pose() 和 get_current_joint_positions() 结果
-def _get_cached_head_pose(self):
-    # 100ms 内复用缓存结果
-```
+**Implemented**:
+- ✅ Emotion Selector entity (`emotion`)
+- ✅ Basic emotion action playback API (`_play_emotion`)
+- ✅ Emotion mapping: Happy/Sad/Angry/Fear/Surprise/Disgust
+- ✅ Integration with HuggingFace action library
+- ✅ SpeechSway system for natural head micro-movements during conversation
 
-### 修复效果
+**Design Decisions**:
+- 🎯 No auto-play of full emotion actions during conversation to avoid blocking
+- 🎯 Use voice-driven head sway (SpeechSway) for natural motion feedback
+- 🎯 Emotion actions retained as manual trigger feature via ESPHome entity
 
-| 指标 | 修复前 | 修复后 | 改善 |
-|------|--------|--------|------|
-| 控制消息频率 | ~100 msg/s | ~20 msg/s | ↓ 80% |
-| 状态查询频率 | ~50 msg/s | ~5 msg/s | ↓ 90% |
-| 总 Zenoh 消息 | ~150 msg/s | ~25 msg/s | ↓ 83% |
-| Daemon CPU 负载 | 持续高负载 | 正常负载 | 显著降低 |
-| 预期稳定性 | 数小时内崩溃 | 可稳定运行数天 | 大幅提升 |
+### Phase 15 - Face Tracking (Replaces DOA) ✅ Complete
 
-### 相关文件
-- `DAEMON_CRASH_FIX_PLAN.md` - 详细修复方案和测试计划
-- `movement_manager.py` - 控制循环优化
-- `reachy_controller.py` - 状态查询缓存
+**Goal**: Implement natural face tracking so robot looks at speaker during conversation.
 
-### 后续优化建议
-1. ⏳ 动态频率调整 - 运动时 50Hz，空闲时 5Hz
-2. ⏳ 批量状态查询 - 一次性获取所有状态
-3. ⏳ 性能监控和告警 - 实时监控 daemon 健康状态
+**Design Decision**: 
+- ❌ Original plan: DOA (Direction of Arrival) sound source tracking
+- ✅ Changed to: YOLO face detection - more stable and accurate
+- Reason: DOA inaccurate at wakeup, frequent queries cause daemon crash
 
----
+**Implemented Features**:
+- ✅ YOLO face detection using `AdamCodd/YOLOv11n-face-detection` model
+- ✅ Adaptive frame rate: 15fps during conversation, 3fps when idle without face
+- ✅ look_at_image() calculates target pose from face position
+- ✅ Smooth return to neutral position after face lost (1 second)
+- ✅ face_tracking_offsets as secondary pose overlay
+- ✅ Model download retry (3 attempts, 5s interval)
+- ✅ Conversation mode integration with voice assistant state
 
-## 🔧 Daemon 崩溃问题深度修复 (2026-01-07)
+**Resource Optimization (v0.5.1)**:
+- During conversation (listening/thinking/speaking): High-frequency tracking 15fps
+- Idle with face detected: High-frequency tracking 15fps
+- Idle without face for 10s: Low-power mode 3fps
+- Immediately restore high-frequency tracking when face detected
 
-### 问题描述
-长期运行过程中，`reachy_mini daemon` 仍然会崩溃，之前的修复不够彻底。
+### Phase 16 - Cartoon Style Motion Mode 🟡 Partial
 
-### 根本原因分析
+**Goal**: Use SDK interpolation techniques for more expressive robot movements.
 
-通过深入分析 SDK 源码发现：
+**Implemented**:
+- ✅ 20Hz unified control loop (reduced from 100Hz to prevent daemon crash)
+- ✅ Pose change detection - only send commands on significant changes (threshold 0.001)
+- ✅ State query caching - 100ms TTL, reduces daemon load
+- ✅ Smooth interpolation (ease in-out curve)
+- ✅ Breathing animation - idle Z-axis micro-movement + antenna sway
+- ✅ Command queue mode - thread-safe external API
+- ✅ Error throttling - prevents log explosion
+- ✅ Connection health monitoring - auto-detect and recover from connection loss
 
-1. **每次 `set_target()` 发送 3 条 Zenoh 消息**
-   - `set_target_head_pose()` - 1 条消息
-   - `set_target_antenna_joint_positions()` - 1 条消息  
-   - `set_target_body_yaw()` - 1 条消息
+**Not Implemented**:
+- ❌ Dynamic interpolation technique switching (CARTOON/EASE_IN_OUT etc.)
+- ❌ Exaggerated cartoon bounce effects
 
-2. **Daemon 控制循环是 50Hz**
-   - 见 `reachy_mini/daemon/backend/robot/backend.py`: `control_loop_frequency = 50.0`
-   - 如果消息发送频率超过 50Hz，daemon 可能无法及时处理
+### Phase 17 - Antenna Sync Animation During Speech 🟡 Partial
 
-3. **之前的 20Hz 控制循环仍然过高**
-   - 20Hz × 3 消息 = 60 消息/秒
-   - 已经超过 daemon 的 50Hz 处理能力
+**Goal**: Antennas sway with audio rhythm during TTS playback, simulating "speaking" effect.
 
-4. **姿态变化阈值太小 (0.002)**
-   - 呼吸动画、语音摆动、人脸追踪持续产生微小变化
-   - 几乎每次循环都会触发 `set_target()`
+**Implemented**:
+- ✅ Voice-driven head sway (`SpeechSwayGenerator`)
+- ✅ VAD detection based on audio loudness
+- ✅ Multi-frequency sine wave overlay (Lissajous motion)
+- ✅ Smooth envelope transitions
 
-### 修复方案
+**Not Implemented**:
+- ❌ Antenna sway with audio rhythm (currently only head sway)
+- ❌ Audio spectrum analysis driven animation
 
-#### 1. 进一步降低控制循环频率 (movement_manager.py)
-```python
-# 从 20Hz 降低到 10Hz
-# 10Hz × 3 消息 = 30 消息/秒，安全低于 daemon 的 50Hz 容量
-CONTROL_LOOP_FREQUENCY_HZ = 10
-```
+### Phase 18 - Visual Gaze Interaction ❌ Not Implemented
 
-#### 2. 增大姿态变化阈值 (movement_manager.py)
-```python
-# 从 0.002 增大到 0.005
-# 0.005 rad ≈ 0.29 度，仍然足够平滑
-self._pose_change_threshold = 0.005
-```
+**Goal**: Use camera to detect faces for eye contact.
 
-#### 3. 降低摄像头/人脸追踪频率 (camera_server.py)
-```python
-# 从 15fps 降低到 10fps
-fps: int = 10
-```
+### Phase 19 - Gravity Compensation Interactive Mode 🟡 Partial
 
-#### 4. 降低 IMU 轮询频率 (tap_detector.py)
-```python
-# 从 50Hz 降低到 20Hz
-TAP_DETECTION_RATE_HZ = 20
-```
+**Implemented**:
+- ✅ Gravity compensation mode switch (`motor_mode` Select entity)
 
-#### 5. 增大状态缓存 TTL (reachy_controller.py)
-```python
-# 从 1 秒增大到 2 秒
-self._cache_ttl = 2.0
-```
+**Not Implemented**:
+- ❌ Teaching mode - record motion trajectory
+- ❌ Save/playback custom actions
 
-### 修复效果
+### Phase 20 - Environment Awareness Response 🟡 Partial
 
-| 指标 | 修复前 (20Hz) | 修复后 (10Hz) | 改善 |
-|------|---------------|---------------|------|
-| 控制循环频率 | 20 Hz | 10 Hz | ↓ 50% |
-| 最大 Zenoh 消息 | 60 msg/s | 30 msg/s | ↓ 50% |
-| 实际��息 (有变化检测) | ~40 msg/s | ~15 msg/s | ↓ 62% |
-| 人脸追踪频率 | 15 Hz | 10 Hz | ↓ 33% |
-| IMU 轮询频率 | 50 Hz | 20 Hz | ↓ 60% |
-| 状态缓存 TTL | 1 秒 | 2 秒 | ↑ 100% |
-| 预期稳定性 | 数小时崩溃 | 可稳定运行 | 大幅提升 |
+**Implemented**:
+- ✅ Tap-to-wake enters continuous conversation mode
+- ✅ Second tap exits continuous conversation mode
 
-### 关键发现
+**Tap-to-wake vs Voice Wake**:
+| Wake Method | Conversation Mode | Description |
+|-------------|-------------------|-------------|
+| Voice wake (Okay Nabu) | Single conversation | Need to say wake word for each conversation |
+| Tap-to-wake | Continuous conversation | Auto-continue listening after TTS ends, tap again to exit |
 
-参考 `reachy_mini_conversation_app` 使用 100Hz 控制循环，但它是官方应用，可能有特殊优化或在更强硬件上运行。我们的应用需要更保守的设置。
+**Not Implemented**:
+- ❌ Shake detection - play dizzy action
+- ❌ Tilt/fall detection - play help action
+- ❌ Long idle - enter sleep animation
 
-### 相关文件
-- `movement_manager.py` - 控制循环频率和姿态阈值
-- `camera_server.py` - 人脸追踪频率
-- `tap_detector.py` - IMU 轮询频率
-- `reachy_controller.py` - 状态缓存 TTL
+### Phase 21 - Home Assistant Scene Integration ❌ Not Implemented
 
 ---
 
-## 🔧 拍一拍唤醒与麦克风灵敏度修复 (2026-01-07)
-
-### 问题描述
-1. **拍一拍唤醒阻塞** - 拍一拍唤醒后对话功能不正常，存在阻塞问题
-2. **麦克风灵敏度低** - 需要靠很近才能识别语音
-
-### 根本原因
-1. **音频播放阻塞** - `_tap_continue_feedback()` 在持续对话模式下播放提示音，阻塞了音频流处理
-2. **AGC 设置不优化** - ReSpeaker XVF3800 的默认设置不适合远距离语音识别
+## Completion Statistics
 
-### 修复方案
+| Phase | Status | Completion | Notes |
+|-------|--------|------------|-------|
+| Phase 1-12 | ✅ Complete | 100% | 40 ESPHome entities implemented (Phase 11 LED disabled) |
+| Phase 13 | ✅ Complete | 100% | Sendspin audio output support |
+| Phase 14 | 🟡 Partial | 30% | API infrastructure ready, missing auto-trigger |
+| Phase 15 | ✅ Complete | 100% | YOLO face tracking fully implemented |
+| Phase 16 | 🟡 Partial | 70% | Control loop + pose detection + breathing animation |
+| Phase 17 | 🟡 Partial | 50% | Voice-driven head sway implemented |
+| Phase 18 | ❌ Not done | 10% | Camera implemented, missing face detection |
+| Phase 19 | 🟡 Partial | 40% | Mode switch implemented, missing teaching flow |
+| Phase 20 | 🟡 Partial | 30% | Tap-to-wake implemented |
+| Phase 21 | ❌ Not done | 0% | Not implemented |
 
-#### 1. 移除持续对话反馈中的音频播放 (satellite.py)
-```python
-def _tap_continue_feedback(self) -> None:
-    """Provide feedback when continuing conversation in tap mode.
-    
-    Triggers a nod to indicate ready for next input.
-    Sound is NOT played here to avoid blocking audio streaming.
-    """
-    # NOTE: Do NOT play sound here - it blocks audio streaming
-    if self.state.motion_enabled and self.state.motion:
-        self.state.motion.on_continue_listening()
-```
-
-#### 2. 添加异常处理到 tap 回调 (voice_assistant.py)
-```python
-def _on_tap_detected(self) -> None:
-    """Callback when tap is detected on the robot.
-    
-    NOTE: This is called from the tap_detector background thread.
-    """
-    try:
-        self._state.satellite.wakeup_from_tap()
-        # ... motion feedback
-    except Exception as e:
-        _LOGGER.error("Error in tap detection callback: %s", e)
-```
-
-#### 3. 全面优化麦克风设置 (voice_assistant.py) - 更新于 2026-01-07
-```python
-def _optimize_microphone_settings(self) -> None:
-    """Optimize ReSpeaker XVF3800 microphone settings for voice recognition."""
-    
-    # ========== 1. AGC (Automatic Gain Control) Settings ==========
-    # Enable AGC for automatic volume normalization
-    respeaker.write("PP_AGCONOFF", [1])
-    
-    # Increase AGC max gain for better distant speech pickup (default ~15dB -> 30dB)
-    respeaker.write("PP_AGCMAXGAIN", [30.0])
-    
-    # Set AGC desired output level (default ~-25dB -> -18dB for stronger output)
-    respeaker.write("PP_AGCDESIREDLEVEL", [-18.0])
-    
-    # Optimize AGC time constant for voice commands
-    respeaker.write("PP_AGCTIME", [0.5])
-    
-    # ========== 2. Base Microphone Gain ==========
-    # Increase base microphone gain (default 1.0 -> 2.0)
-    respeaker.write("AUDIO_MGR_MIC_GAIN", [2.0])
-    
-    # ========== 3. Noise Suppression Settings ==========
-    # Reduce noise suppression to preserve quiet speech (default ~0.5 -> 0.15)
-    respeaker.write("PP_MIN_NS", [0.15])
-    respeaker.write("PP_MIN_NN", [0.15])
-    
-    # ========== 4. Echo Cancellation & High-pass Filter ==========
-    respeaker.write("PP_ECHOONOFF", [1])
-    respeaker.write("AEC_HPFONOFF", [1])
-```
-
-### 修复效果
-
-| 参数 | 修复前 | 修复后 | 说明 |
-|------|--------|--------|------|
-| 拍一拍持续对话 | 阻塞 | 正常工作 | 移除阻塞音频播放 |
+**Overall Completion**: **Phase 1-13: 100%** | **Phase 14-21: ~45%**
 
 ---
 
-## 🔧 v0.5.1 Bug 修复 (2026-01-08)
-
-### 问题 1: 音乐播放在语音对话后不恢复
-
-**问题描述**: 播放音乐时，语音对话结束后，音乐没有恢复播放。
-
-**根本原因**: Sendspin 被错误地连接到 `tts_player` 而不是 `music_player`。
-
-**修复方案**:
-- `voice_assistant.py`: Sendspin discovery 现在连接到 `music_player`
-- `satellite.py`: `duck()`/`unduck()` 现在调用 `music_player.pause_sendspin()`/`resume_sendspin()`
-
-### 问题 2: tap_sensitivity 设置不持久化
-
-**问题描述**: ESPHome 中设置的 tap_sensitivity 值在重启后丢失。
-
-**修复方案**:
-- `models.py`: 在 `Preferences` dataclass 中添加 `tap_sensitivity` 字段
-- `entity_registry.py`: 实体 setter 现在保存到 `preferences.json`
-- 启动时从保存的偏好设置加载值
-
-### 问题 3: 语音助手唤醒时的音频冲突
-
-**问题描述**: 音频推流时（Sendspin 或 ESPHome 音频），语音助手被唤醒会导致冲突。
-
-**修复方案**:
-- `audio_player.py`: 添加 `pause_sendspin()` 和 `resume_sendspin()` 方法
-- `satellite.py`: `duck()` 现在暂停 Sendspin，`unduck()` 恢复它
-- 改进 `pause()` 方法以实际停止音频输出
-
-### 问题 4: AttributeError for _camera_server
-
-**问题描述**: `_set_conversation_mode()` 中引用了不存在的 `_camera_server` 属性。
-
-**修复方案**: 将 `self._camera_server` 改为 `self.camera_server`（移除下划线前缀）
-
-### 问题 5: tap_sensitivity 默认值错误
-
-**问题描述**: tap_sensitivity 默认值仍为 2.0g，而不是预期的 0.5g。
-
-**修复方案**: 使用 `TAP_THRESHOLD_G_DEFAULT` 常量作为默认值
-
-### 问题 6: Sendspin 采样率优化
-
-**问题描述**: ReSpeaker 硬件输入/输出是 16kHz（硬件限制），但 Sendspin 可能尝试使用更高采样率。
-
-**修复方案**: 在 Sendspin 支持格式列表中优先使用 16kHz，避免不必要的重采样
+## Bug Fixes History
+
+### v0.5.1 Bug Fixes (2026-01-08)
+
+#### Issue 1: Music Not Resuming After Voice Conversation
+**Problem**: Music doesn't resume after voice conversation ends.
+**Root Cause**: Sendspin was incorrectly connected to `tts_player` instead of `music_player`.
+**Fix**: 
+- `voice_assistant.py`: Sendspin discovery now connects to `music_player`
+- `satellite.py`: `duck()`/`unduck()` now call `music_player.pause_sendspin()`/`resume_sendspin()`
+
+#### Issue 2: tap_sensitivity Not Persisted
+**Problem**: tap_sensitivity value set in ESPHome lost after restart.
+**Fix**:
+- `models.py`: Added `tap_sensitivity` field to `Preferences` dataclass
+- `entity_registry.py`: Entity setter now saves to `preferences.json`
+- Load saved value on startup
+
+#### Issue 3: Audio Conflict During Voice Assistant Wakeup
+**Problem**: Audio streaming (Sendspin or ESPHome audio) conflicts when voice assistant wakes up.
+**Fix**:
+- `audio_player.py`: Added `pause_sendspin()` and `resume_sendspin()` methods
+- `satellite.py`: `duck()` now pauses Sendspin, `unduck()` resumes it
+- Improved `pause()` method to actually stop audio output
+
+#### Issue 4: AttributeError for _camera_server
+**Problem**: `_set_conversation_mode()` referenced non-existent `_camera_server` attribute.
+**Fix**: Changed `self._camera_server` to `self.camera_server` (removed underscore prefix)
+
+#### Issue 5: tap_sensitivity Default Value Wrong
+**Problem**: tap_sensitivity default was still 2.0g instead of expected 0.5g.
+**Fix**: Use `TAP_THRESHOLD_G_DEFAULT` constant as default value
+
+#### Issue 6: Sendspin Sample Rate Optimization
+**Problem**: ReSpeaker hardware I/O is 16kHz (hardware limitation), but Sendspin might try higher sample rates.
+**Fix**: Prioritize 16kHz in Sendspin supported formats list to avoid unnecessary resampling
+
+### Daemon Crash Fix (2026-01-07)
+
+**Problem**: `reachy_mini daemon` crashes during long-term operation.
+
+**Root Cause Analysis**:
+1. Each `set_target()` sends 3 Zenoh messages
+2. Daemon control loop is 50Hz
+3. Previous 20Hz control loop still too high (20Hz × 3 = 60 msg/s > 50Hz capacity)
+4. Pose change threshold too small (0.002) - almost every loop triggers `set_target()`
+
+**Fix**:
+- Control loop frequency: 20Hz → 10Hz
+- Pose change threshold: 0.002 → 0.005
+- Camera/face tracking frequency: 15fps → 10fps
+- IMU polling frequency: 50Hz → 20Hz
+- State cache TTL: 1s → 2s
+
+**Results**:
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Control loop frequency | 20 Hz | 10 Hz | ↓ 50% |
+| Max Zenoh messages | 60 msg/s | 30 msg/s | ↓ 50% |
+| Expected stability | Hours before crash | Stable operation | Significant |
+
+### Tap-to-Wake and Microphone Sensitivity Fix (2026-01-07)
+
+**Problems**:
+1. Tap-to-wake blocking - conversation not working properly after tap wake
+2. Low microphone sensitivity - need to be very close for voice recognition
+
+**Fixes**:
+1. Removed audio playback in `_tap_continue_feedback()` to avoid blocking
+2. Comprehensive microphone optimization:
+   - AGC enabled with max gain 30dB
+   - AGC desired level -18dB
+   - Base microphone gain 2.0x
+   - Noise suppression reduced to 0.15
+   - Echo cancellation and high-pass filter enabled
+
+**Results**:
+| Parameter | Before | After |
+|-----------|--------|-------|
+| Microphone sensitivity | ~30cm | ~2-3m |
+| AGC max gain | ~15dB | 30dB |
+| Noise suppression | ~0.5 | 0.15 |
 
 ---
-| 麦克风灵敏度 | ~30cm | ~2-3m | 全面优化 AGC 和增益 |
-| AGC 开关 | 关闭 | 开启 | 自动音量归一化 |
-| AGC 最大增益 | ~15dB | 30dB | 提升远距离拾音 |
-| AGC 目标电平 | -25dB | -18dB | 更强输出信号 |
-| 麦克风增益 | 1.0x | 2.0x | 基础增益翻倍 |
-| 噪声抑制 | ~0.5 | 0.15 | 减少对语音的误抑制 |
-| 回声消除 | 开启 | 开启 | 保持 TTS 播放时的清晰度 |
-| 高通滤波 | 关闭 | 开启 | 去除低频噪声 |
-
-### XVF3800 参数参考
-
-| 参数名 | 类型 | 范围 | 说明 |
-|--------|------|------|------|
-| `PP_AGCONOFF` | int32 | 0/1 | AGC 开关 |
-| `PP_AGCMAXGAIN` | float | 0-40 dB | AGC 最大增益 |
-| `PP_AGCDESIREDLEVEL` | float | dB | AGC 目标输出电平 |
-| `PP_AGCTIME` | float | 秒 | AGC 时间常数 |
-| `AUDIO_MGR_MIC_GAIN` | float | 0-4.0 | 麦克风增益倍数 |
-| `PP_MIN_NS` | float | 0-1.0 | 最小噪声抑制 (越低越少抑制) |
-| `PP_MIN_NN` | float | 0-1.0 | 最小噪声估计 |
-| `PP_ECHOONOFF` | int32 | 0/1 | 回声消除开关 |
-| `AEC_HPFONOFF` | int32 | 0/1 | 高通滤波开关 |
-
-### 相关文件
-- `satellite.py` - 移除阻塞的音频播放
-- `voice_assistant.py` - 全面麦克风优化
-- `reachy_controller.py` - AGC 实体默认值更新
-- `entity_registry.py` - AGC max gain 范围更新 (0-40dB)
-- `reachy_mini/src/reachy_mini/media/audio_control_utils.py` - SDK 参考
 
----
-
-### SDK 数据结构参考
+## SDK Data Structure Reference
 
 ```python
-# 电机控制模式
+# Motor control mode
 class MotorControlMode(str, Enum):
-    Enabled = "enabled"              # 扭矩开启，位置控制
-    Disabled = "disabled"            # 扭矩关闭
-    GravityCompensation = "gravity_compensation"  # 重力补偿模式
+    Enabled = "enabled"              # Torque on, position control
+    Disabled = "disabled"            # Torque off
+    GravityCompensation = "gravity_compensation"  # Gravity compensation mode
 
-# Daemon 状态
+# Daemon state
 class DaemonState(Enum):
     NOT_INITIALIZED = "not_initialized"
     STARTING = "starting"
@@ -1102,70 +415,14 @@ class DaemonState(Enum):
     STOPPED = "stopped"
     ERROR = "error"
 
-# 完整状态
-class FullState:
-    control_mode: MotorControlMode
-    head_pose: XYZRPYPose  # x, y, z (m), roll, pitch, yaw (rad)
-    head_joints: list[float]  # 7 个关节角度
-    body_yaw: float
-    antennas_position: list[float]  # [right, left]
-    doa: DoAInfo  # angle (rad), speech_detected (bool)
-
-# IMU 数据 (仅无线版本)
-imu_data = {
-    "accelerometer": [x, y, z],  # m/s²
-    "gyroscope": [x, y, z],      # rad/s
-    "quaternion": [w, x, y, z],  # 姿态四元数
-    "temperature": float         # °C
-}
-
-# 安全限制
+# Safety limits
 HEAD_PITCH_ROLL_LIMIT = [-40°, +40°]
 HEAD_YAW_LIMIT = [-180°, +180°]
 BODY_YAW_LIMIT = [-160°, +160°]
-YAW_DELTA_MAX = 65°  # 头部与身体偏航角最大差值
-```
-
-### ESPHome 协议实现说明
-
-ESPHome 协议通过 protobuf 消息与 Home Assistant 通信。需要实现以下消息类型：
-
-```python
-from aioesphomeapi.api_pb2 import (
-    # Number 实体 (音量/角度控制)
-    ListEntitiesNumberResponse,
-    NumberStateResponse,
-    NumberCommandRequest,
-
-    # Select 实体 (电机模式)
-    ListEntitiesSelectResponse,
-    SelectStateResponse,
-    SelectCommandRequest,
-
-    # Button 实体 (唤醒/睡眠)
-    ListEntitiesButtonResponse,
-    ButtonCommandRequest,
-
-    # Switch 实体 (电机开关)
-    ListEntitiesSwitchResponse,
-    SwitchStateResponse,
-    SwitchCommandRequest,
-
-    # Sensor 实体 (数值传感器)
-    ListEntitiesSensorResponse,
-    SensorStateResponse,
-
-    # Binary Sensor 实体 (布尔传感器)
-    ListEntitiesBinarySensorResponse,
-    BinarySensorStateResponse,
-
-    # Text Sensor 实体 (文本传感器)
-    ListEntitiesTextSensorResponse,
-    TextSensorStateResponse,
-)
+YAW_DELTA_MAX = 65°  # Max difference between head and body yaw
 ```
 
-## 参考项目
+## 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)