"fix-duplicate-entity-registration-and-camera-integration"

PROJECT_PLAN.md

@@ -48,7 +48,7 @@
 │                    Home Assistant                           │
 │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
 │  │ STT Engine  │  │ Intent      │  │ TTS Engine          │ │
-│  │ (Whisper)   │  │ Processing  │  │ (Piper/Cloud)       │ │
+│  │             │  │ Processing  │  │                     │ │
 │  └─────────────┘  └─────────────┘  └─────────────────────┘ │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -87,11 +87,12 @@ reachy_mini_ha_voice/
 │   ├── voice_assistant.py      # 语音助手服务
 │   ├── satellite.py            # ESPHome 协议处理
 │   ├── audio_player.py         # 音频播放器
+│   ├── camera_server.py        # MJPEG 摄像头流服务器
 │   ├── motion.py               # 运动控制
 │   ├── models.py               # 数据模型
 │   ├── entity.py               # ESPHome 基础实体
-│   ├── entity_extensions.py    # 扩展实体类型 (NEW)
-│   ├── reachy_controller.py    # Reachy Mini 控制器包装 (NEW)
+│   ├── entity_extensions.py    # 扩展实体类型
+│   ├── reachy_controller.py    # Reachy Mini 控制器包装
 │   ├── api_server.py           # API 服务器
 │   ├── zeroconf.py             # mDNS 发现
 │   └── util.py                 # 工具函数
@@ -107,7 +108,6 @@ reachy_mini_ha_voice/
 │   └── timer_finished.flac
 ├── pyproject.toml              # 项目配置
 ├── README.md                   # 说明文档
-├── ENTITIES.md                 # 实体使用文档 (NEW)
 └── PROJECT_PLAN.md             # 项目计划
 ```
 
@@ -222,6 +222,23 @@ dependencies = [
 | `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()` 等。
 
@@ -264,18 +281,43 @@ dependencies = [
    - [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 控制** ✅ **已完成**
+    - [x] `led_brightness` - LED 亮度 (0-100%)
+    - [x] `led_effect` - LED 效果 (off/solid/breathing/rainbow/doa)
+    - [x] `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` - 回声消除收敛状态（只读）
+
 ---
 
 ## 🎉 所有实体已完成！
 
-**总计：30+ 个实体**
-- Phase 1: 4 个实体
-- Phase 2: 4 个实体
-- Phase 3: 9 个实体
-- Phase 4: 3 个实体
-- Phase 5: 2 个实体
-- Phase 6: 6 个实体
-- Phase 7: 7 个实体
+**总计：45+ 个实体**
+- 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: 5 个实体 (LED 控制)
+- Phase 12: 4 个实体 (音频处理参数)
 
 ### SDK 数据结构参考
 

README.md

@@ -78,7 +78,7 @@ Additional wake words can be configured through Home Assistant.
 
 ## ESPHome Entities
 
-This application exposes 30+ entities to Home Assistant for complete robot control:
+This application exposes 45+ entities to Home Assistant for complete robot control:
 
 ### Status & Control (Phase 1)
 - **Daemon State** - Monitor robot daemon status
@@ -118,7 +118,25 @@ This application exposes 30+ entities to Home Assistant for complete robot contr
 - **Gyroscope** - X/Y/Z angular velocity (rad/s)
 - **Temperature** - IMU temperature (°C)
 
-📖 **[View Complete Entity Documentation](ENTITIES.md)** - Includes usage examples, automations, and Lovelace dashboard configurations
+### Emotion Control (Phase 8)
+- **Emotion** - Select emotion (Happy/Sad/Angry/Fear/Surprise/Disgust)
+
+### Audio Control (Phase 9)
+- **Microphone Volume** - Control microphone input level (0-100%)
+
+### Camera (Phase 10)
+- **Camera** - ESPHome Camera entity with live preview in Home Assistant
+
+### LED Control (Phase 11)
+- **LED Brightness** - Control LED brightness (0-100%)
+- **LED Effect** - Select LED effect (off/solid/breathing/rainbow/doa)
+- **LED Color R/G/B** - Control LED color (0-255 per channel)
+
+### Audio Processing (Phase 12)
+- **AGC Enabled** - Toggle automatic gain control
+- **AGC Max Gain** - Set maximum AGC gain (0-30 dB)
+- **Noise Suppression** - Set noise suppression level (0-100%)
+- **Echo Cancellation Converged** - Monitor echo cancellation status
 
 ## How It Works
 
@@ -145,6 +163,7 @@ This application exposes 30+ entities to Home Assistant for complete robot contr
 reachy_mini_ha_voice/
 ├── reachy_mini_ha_voice/
 │   ├── __init__.py
+│   ├── __main__.py          # CLI entry point
 │   ├── main.py              # App entry point
 │   ├── voice_assistant.py   # Voice assistant service
 │   ├── camera_server.py     # MJPEG camera streaming server
@@ -152,7 +171,9 @@ reachy_mini_ha_voice/
 │   ├── audio_player.py      # Audio playback
 │   ├── motion.py            # Motion control
 │   ├── models.py            # Data models
-│   ├── entity.py            # ESPHome entities
+│   ├── entity.py            # ESPHome base entities
+│   ├── entity_extensions.py # Extended entity types
+│   ├── reachy_controller.py # Reachy Mini controller wrapper
 │   ├── api_server.py        # API server
 │   ├── zeroconf.py          # mDNS discovery
 │   └── util.py              # Utilities

old_entity_extensions.py

@@ -1,283 +0,0 @@
-"""Extended ESPHome entity types for Reachy Mini control."""
-
-from collections.abc import Iterable
-from typing import Callable, List, Optional
-import logging
-
-from aioesphomeapi.api_pb2 import (  # type: ignore[attr-defined]
-    ListEntitiesButtonResponse,
-    ListEntitiesRequest,
-    ListEntitiesSelectResponse,
-    ListEntitiesSensorResponse,
-    ListEntitiesSwitchResponse,
-    ButtonCommandRequest,
-    SelectCommandRequest,
-    SelectStateResponse,
-    SensorStateResponse,
-    SubscribeHomeAssistantStatesRequest,
-    SubscribeStatesRequest,
-    SwitchCommandRequest,
-    SwitchStateResponse,
-)
-from google.protobuf import message
-
-from .api_server import APIServer
-from .entity import ESPHomeEntity
-
-logger = logging.getLogger(__name__)
-
-
-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,
-        value_getter: Optional[Callable[[], float]] = 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
-        # Convert string state_class to int if needed (for backward compatibility)
-        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:
-        if self._value_getter:
-            return self._value_getter()
-        return self._value
-
-    @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,
-            )
-        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: Optional[Callable[[], bool]] = None,
-        value_setter: Optional[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_setter = value_setter
-        self._value = False
-
-    @property
-    def value(self) -> bool:
-        if self._value_getter:
-            return self._value_getter()
-        return self._value
-
-    @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 = "",
-        value_getter: Optional[Callable[[], str]] = None,
-        value_setter: Optional[Callable[[str], 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._value_getter = value_getter
-        self._value_setter = value_setter
-        self._value = options[0] if options else ""
-
-    @property
-    def value(self) -> str:
-        if self._value_getter:
-            return self._value_getter()
-        return self._value
-
-    @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,
-            )
-        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 = "",
-        on_press: Optional[Callable[[], 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._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,
-            )
-        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_ha_voice/satellite.py

@@ -149,30 +149,49 @@ class VoiceSatelliteProtocol(APIServer):
         self._doa_angle_entity: Optional[SensorEntity] = None
         self._speech_detected_entity: Optional[BinarySensorEntity] = None
 
-        if self.state.media_player_entity is None:
-            self.state.media_player_entity = MediaPlayerEntity(
-                server=self,
-                key=self._get_entity_key("reachy_mini_media_player"),
-                name="Media Player",
-                object_id="reachy_mini_media_player",
-                music_player=state.music_player,
-                announce_player=state.tts_player,
-            )
-            self.state.entities.append(self.state.media_player_entity)
-
-        # Setup all entity phases
-        self._setup_phase1_entities()
-        self._setup_phase2_entities()
-        self._setup_phase3_entities()
-        self._setup_phase4_entities()
-        self._setup_phase5_entities()
-        self._setup_phase6_entities()
-        self._setup_phase7_entities()
-        self._setup_phase8_entities()
-        self._setup_phase9_entities()
-        self._setup_phase10_entities()  # Camera
-        # Phase 11 (LED control) disabled - LEDs are inside the robot and not visible
-        self._setup_phase12_entities()  # Audio processing
+        # Only setup entities once (check if already initialized)
+        # This prevents duplicate entity registration on reconnection
+        if not getattr(self.state, '_entities_initialized', False):
+            if self.state.media_player_entity is None:
+                self.state.media_player_entity = MediaPlayerEntity(
+                    server=self,
+                    key=self._get_entity_key("reachy_mini_media_player"),
+                    name="Media Player",
+                    object_id="reachy_mini_media_player",
+                    music_player=state.music_player,
+                    announce_player=state.tts_player,
+                )
+                self.state.entities.append(self.state.media_player_entity)
+
+            # Setup all entity phases
+            self._setup_phase1_entities()
+            self._setup_phase2_entities()
+            self._setup_phase3_entities()
+            self._setup_phase4_entities()
+            self._setup_phase5_entities()
+            self._setup_phase6_entities()
+            self._setup_phase7_entities()
+            self._setup_phase8_entities()
+            self._setup_phase9_entities()
+            self._setup_phase10_entities()  # Camera
+            # Phase 11 (LED control) disabled - LEDs are inside the robot and not visible
+            self._setup_phase12_entities()  # Audio processing
+
+            # Mark entities as initialized
+            self.state._entities_initialized = True
+            _LOGGER.info("Entities initialized: %d total", len(self.state.entities))
+        else:
+            _LOGGER.debug("Entities already initialized, skipping setup")
+            # Update server reference in existing entities
+            for entity in self.state.entities:
+                entity.server = self
+            # Find and store references to DOA entities
+            for entity in self.state.entities:
+                if hasattr(entity, 'object_id'):
+                    if entity.object_id == 'doa_angle':
+                        self._doa_angle_entity = entity
+                    elif entity.object_id == 'speech_detected':
+                        self._speech_detected_entity = entity
 
         self._is_streaming_audio = False
         self._tts_url: Optional[str] = None
@@ -463,6 +482,11 @@ class VoiceSatelliteProtocol(APIServer):
     def connection_lost(self, exc):
         super().connection_lost(exc)
         _LOGGER.info("Disconnected from Home Assistant")
+        # Clear streaming state on disconnect
+        self._is_streaming_audio = False
+        self._tts_url = None
+        self._tts_played = False
+        self._continue_conversation = False
 
     def _download_external_wake_word(
         self, external_wake_word: VoiceAssistantExternalWakeWord

reachy_mini_ha_voice/voice_assistant.py

@@ -137,19 +137,7 @@ class VoiceAssistantService:
         )
         self._audio_thread.start()
 
-        # Create ESPHome server
-        loop = asyncio.get_running_loop()
-        self._server = await loop.create_server(
-            lambda: VoiceSatelliteProtocol(self._state),
-            host=self.host,
-            port=self.port,
-        )
-
-        # Start mDNS discovery
-        self._discovery = HomeAssistantZeroconf(port=self.port, name=self.name)
-        await self._discovery.register_server()
-
-        # Start camera server if enabled
+        # Start camera server if enabled (must be before ESPHome server)
         if self.camera_enabled:
             self._camera_server = MJPEGCameraServer(
                 reachy_mini=self.reachy_mini,
@@ -160,6 +148,19 @@ class VoiceAssistantService:
             )
             await self._camera_server.start()
 
+        # Create ESPHome server (pass camera_server for camera entity)
+        loop = asyncio.get_running_loop()
+        camera_server = self._camera_server  # Capture for lambda
+        self._server = await loop.create_server(
+            lambda: VoiceSatelliteProtocol(self._state, camera_server=camera_server),
+            host=self.host,
+            port=self.port,
+        )
+
+        # Start mDNS discovery
+        self._discovery = HomeAssistantZeroconf(port=self.port, name=self.name)
+        await self._discovery.register_server()
+
         _LOGGER.info("Voice assistant service started on %s:%s", self.host, self.port)
 
     async def stop(self) -> None: