Initial commit: Reachy Mini Home Assistant Voice Assistant

- Implement ESPHome protocol for Home Assistant integration
- Support multiple wake words (microWakeWord and openWakeWord)
- Integrate Reachy Mini robot actions and feedback
- Include all wake word models and sound files
- Add Hugging Face Spaces deployment support

.gitattributes

@@ -1,37 +1,24 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Source code
+*.py text eol=lf
+*.sh text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.json text eol=lf
+*.toml text eol=lf
+*.md text eol=lf
+# Binary files
+*.tflite binary
+*.flac binary
+*.wav binary
+*.mp3 binary
+# Windows scripts
+*.ps1 text eol=crlf
+# Git LFS for large files
 *.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
 "reachy_mini_ha_voice/wakewords/**/*.tflite filter=lfs diff=lfs merge=lfs -text
 reachy_mini_ha_voice/sounds/**/*.flac" filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+env/
+venv/
+ENV/
+.ENV
+.pytest_cache/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.DS_Store
+*.log
+preferences.json
+local/
+*.tflite
+*.flac
+*.wav
+*.mp3

Dockerfile

@@ -0,0 +1,33 @@
+# Use Python 3.11 slim image
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    portaudio19-dev \
+    build-essential \
+    libportaudio2 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the application code
+COPY . .
+
+# Install the package
+RUN pip install -e .
+
+# Expose the ESPHome API port
+EXPOSE 6053
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+
+# Default command - can be overridden by Hugging Face Spaces
+CMD ["python", "-m", "reachy_mini_ha_voice", "--name", "ReachyMini"]

README.md

@@ -1,10 +1,248 @@
----
-title: Reachy Mini Ha Voice
-emoji: 🌖
-colorFrom: green
-colorTo: gray
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Reachy Mini Home Assistant Voice Assistant
+
+基于 ESPHome 协议的 Reachy Mini 语音助手，用于连接 Home Assistant。可通过 Hugging Face Spaces 一键安装和部署。
+
+## 功能特性
+
+- 🎤 唤醒词检测（支持多个唤醒词）
+- 🔊 语音识别和合成
+- 🏠 Home Assistant 指令执行
+- 🤖 Reachy Mini 机器人集成
+- ⏰ 定时器功能
+- 📢 广播通知
+
+## 快速开始
+
+### 通过 Hugging Face Spaces 安装
+
+1. 访问 [Hugging Face Spaces](https://huggingface.co/spaces)
+2. 创建新的 Space，选择 Docker 模板
+3. 将此仓库克隆到你的 Space
+4. 等待构建完成，服务将自动启动
+
+### 本地运行
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-username/reachy_mini_ha_voice.git
+cd reachy_mini_ha_voice
+
+# 安装系统依赖（Linux）
+sudo apt-get install portaudio19-dev build-essential libportaudio2
+
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# 安装 Python 依赖
+pip install -r requirements.txt
+pip install -e .
+
+# 运行
+python -m reachy_mini_ha_voice --name "ReachyMini"
+```
+
+## 连接到 Home Assistant
+
+1. 在 Home Assistant 中，进入 "设置" -> "设备与服务"
+2. 点击 "添加集成" 按钮
+3. 选择 "ESPHome" 然后选择 "设置另一个 ESPHome 实例"
+4. 输入语音助手的 IP 地址和端口 6053
+5. 点击 "提交"
+
+## 命令行选项
+
+```
+python -m reachy_mini_ha_voice --help
+
+选项:
+  --name NAME                    设备名称（必需）
+  --host HOST                    服务器地址（默认: 0.0.0.0）
+  --port PORT                    服务器端口（默认: 6053）
+  --audio-input-device DEVICE    音频输入设备
+  --list-input-devices           列出可用的音频输入设备
+  --audio-output-device DEVICE   音频输出设备
+  --list-output-devices          列出可用的音频输出设备
+  --wake-model MODEL             唤醒词模型（默认: okay_nabu）
+  --stop-model MODEL             停止词模型（默认: stop）
+  --refractory-seconds SECONDS   唤醒词冷却时间（默认: 2.0）
+  --debug                        启用调试日志
+```
+
+## 包含的 Assets
+
+项目已经包含了所有必需的唤醒词模型和声音文件，无需额外下载：
+
+### 唤醒词模型（microWakeWord）
+
+- `okay_nabu.tflite` - "Okay Nabu"（默认）
+- `stop.tflite` - "Stop"
+- `alexa.tflite` - "Alexa"
+- `hey_jarvis.tflite` - "Hey Jarvis"
+- `hey_home_assistant.tflite` - "Hey Home Assistant"
+- `hey_luna.tflite` - "Hey Luna"
+- `hey_mycroft.tflite` - "Hey Mycroft"
+- `okay_computer.tflite` - "Okay Computer"
+- `choo_choo_homie.tflite` - "Choo Choo Homie"
+
+### 唤醒词模型（openWakeWord）
+
+在 `wakewords/openWakeWord/` 目录中：
+- `alexa_v0.1.tflite` - Alexa
+- `hey_jarvis_v0.1.tflite` - Hey Jarvis
+- `hey_mycroft_v0.1.tflite` - Hey Mycroft
+- `hey_rhasspy_v0.1.tflite` - Hey Rhasspy
+- `ok_nabu_v0.1.tflite` - Okay Nabu
+
+### 声音文件
+
+- `wake_word_triggered.flac` - 唤醒词触发时播放
+- `timer_finished.flac` - 定时器结束时播放
+
+## 音频设备配置
+
+### 查看可用设备
+
+```bash
+# 列出音频输入设备
+python -m reachy_mini_ha_voice --name Test --list-input-devices
+
+# 列出音频输出设备
+python -m reachy_mini_ha_voice --name Test --list-output-devices
+```
+
+### 指定音频设备
+
+```bash
+python -m reachy_mini_ha_voice \
+  --name "ReachyMini" \
+  --audio-input-device "麦克风名称" \
+  --audio-output-device "扬声器名称"
+```
+
+**注意**：麦克风设备必须支持 16KHz 单声道音频。
+
+## 唤醒词
+
+### 默认唤醒词
+
+- `okay_nabu`（默认）
+
+### 使用其他唤醒词
+
+项目已经包含了多个唤醒词模型，你可以直接使用：
+
+```bash
+# 使用 "Hey Jarvis"
+python -m reachy_mini_ha_voice --name "ReachyMini" --wake-model hey_jarvis
+
+# 使用 "Alexa"
+python -m reachy_mini_ha_voice --name "ReachyMini" --wake-model alexa
+
+# 使用 openWakeWord 版本的 "Hey Jarvis"
+python -m reachy_mini_ha_voice --name "ReachyMini" \
+  --wake-model hey_jarvis_v0.1 \
+  --wake-word-dir wakewords/openWakeWord
+```
+
+### 添加自定义唤醒词
+
+如果你想添加其他唤醒词：
+
+更多唤醒词模型请访问：[home-assistant-wakewords-collection](https://github.com/fwartner/home-assistant-wakewords-collection)
+
+## Reachy Mini 集成
+
+### 动作反馈
+
+语音助手会根据不同状态触发 Reachy Mini 的动作：
+
+- **唤醒时**：头部抬起，眼睛闪烁
+- **监听中**：头部轻微摆动
+- **响应中**：点头或摇头
+- **错误时**：头部倾斜
+
+### 自定义动作
+
+编辑 `reachy_mini_ha_voice/reachy_integration.py` 来自定义 Reachy Mini 的动作反馈。
+
+## 故障排除
+
+### 音频设备问题
+
+如果无法检测��音频设备：
+
+```bash
+# 检查 PulseAudio 服务
+systemctl --user status pulseaudio
+
+# 重新加载 PulseAudio
+pulseaudio --kill
+pulseaudio --start
+```
+
+### 回声消除
+
+启用 PulseAudio 的回声消除模块：
+
+```bash
+pactl load-module module-echo-cancel \
+  aec_method=webrtc \
+  aec_args="analog_gain_control=0 digital_gain_control=1 noise_suppression=1"
+```
+
+查看设备：
+
+```bash
+pactl list short sources
+pactl list short sinks
+```
+
+使用回声消除设备：
+
+```bash
+python -m reachy_mini_ha_voice \
+  --name "ReachyMini" \
+  --audio-input-device 'Echo-Cancel Source' \
+  --audio-output-device 'pipewire/echo-cancel-sink'
+```
+
+### Hugging Face Spaces 部署问题
+
+如果构建失败：
+
+1. 检查 Dockerfile 中的依赖是否正确
+2. 确保 requirements.txt 中的版本兼容
+3. 查看构建日志中的错误信息
+4. 确保没有使用需要系统特权的功能
+
+## 开发
+
+### 运行测试
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### 代码格式化
+
+```bash
+black reachy_mini_ha_voice/
+flake8 reachy_mini_ha_voice/
+```
+
+## 许可证
+
+Apache License 2.0
+
+## 致谢
+
+本项目基于 [OHF-Voice/linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant) 修改而来，适配 Reachy Mini 机器人和 Hugging Face Spaces 环境。
+
+## 相关链接
+
+- [Home Assistant](https://www.home-assistant.io/)
+- [ESPHome](https://esphome.io/)
+- [Reachy Mini](https://github.com/pollen-robotics/reachy)
+- [Hugging Face Spaces](https://huggingface.co/spaces)

README_ASSETS.md

@@ -0,0 +1,151 @@
+# Assets Setup Guide
+
+This document explains how to set up the required assets (wake word models and sound files).
+
+## Included Assets
+
+All required wake word models and sound files are already included in the repository:
+
+### Wake Word Models (microWakeWord)
+
+- `okay_nabu.tflite` - "Okay Nabu" (default)
+- `stop.tflite` - "Stop"
+- `alexa.tflite` - "Alexa"
+- `hey_jarvis.tflite` - "Hey Jarvis"
+- `hey_home_assistant.tflite` - "Hey Home Assistant"
+- `hey_luna.tflite` - "Hey Luna"
+- `hey_mycroft.tflite` - "Hey Mycroft"
+- `okay_computer.tflite` - "Okay Computer"
+- `choo_choo_homie.tflite` - "Choo Choo Homie"
+
+### Wake Word Models (openWakeWord)
+
+Located in `wakewords/openWakeWord/`:
+- `alexa_v0.1.tflite` - Alexa
+- `hey_jarvis_v0.1.tflite` - Hey Jarvis
+- `hey_mycroft_v0.1.tflite` - Hey Mycroft
+- `hey_rhasspy_v0.1.tflite` - Hey Rhasspy
+- `ok_nabu_v0.1.tflite` - Okay Nabu
+
+### Sound Files
+
+- `wake_word_triggered.flac` - Played when wake word is detected
+- `timer_finished.flac` - Played when timer finishes
+
+## Wake Word Models
+
+The application uses two wake word engines:
+- **microWakeWord**: Lightweight, good for embedded systems
+- **openWakeWord**: More accurate, uses more resources
+
+### Adding Custom Wake Words
+
+#### microWakeWord Models
+
+1. Download a model from [microWakeWord releases](https://github.com/kahrendt/microWakeWord/releases)
+2. Place the `.tflite` file in the `wakewords/` directory
+3. Create a corresponding `.json` file:
+
+```json
+{
+  "type": "microWakeWord",
+  "wake_word": "Your Wake Word",
+  "trained_languages": ["en"]
+}
+```
+
+#### openWakeWord Models
+
+1. Download a model from [home-assistant-wakewords-collection](https://github.com/fwartner/home-assistant-wakewords-collection)
+2. Place the `.tflite` file in the `wakewords/` directory
+3. Create a corresponding `.json` file:
+
+```json
+{
+  "type": "openWakeWord",
+  "wake_word": "Your Wake Word",
+  "model": "your_wake_word.tflite",
+  "trained_languages": ["en"]
+}
+```
+
+### Popular Wake Words
+
+Here are some popular wake words you can add:
+
+- **Hey Jarvis**: [Download](https://github.com/fwartner/home-assistant-wakewords-collection/raw/main/en/hey_jarvis/hey_jarvis.tflite)
+- **Alexa**: [Download](https://github.com/fwartner/home-assistant-wakewords-collection/raw/main/en/alexa/alexa.tflite)
+- **Hey Google**: [Download](https://github.com/fwartner/home-assistant-wakewords-collection/raw/main/en/hey_google/hey_google.tflite)
+- **GLaDOS**: [Download](https://github.com/fwartner/home-assistant-wakewords-collection/raw/main/en/glados/glados.tflite)
+
+## Sound Files
+
+The application uses sound files for feedback:
+
+### Included Files
+
+1. **wake_word_triggered.flac** - Played when wake word is detected
+2. **timer_finished.flac** - Played when timer finishes
+
+### Customizing Sound Files
+
+You can replace these files with your own:
+
+1. Keep them short (1-2 seconds)
+2. Use FLAC or WAV format
+3. Sample rate: 16kHz or 44.1kHz
+4. Mono or stereo
+
+### Example Using Online Tools
+
+1. Go to [TTSMP3](https://ttsmp3.com/)
+2. Enter text like "I'm listening" or "Timer finished"
+3. Generate and download as MP3
+4. Convert to FLAC using [Online Audio Converter](https://online-audio-converter.com/)
+5. Replace the file in `sounds/` directory
+
+## Directory Structure
+
+After setup, your directory should look like:
+
+```
+reachy_mini_ha_voice/
+├── wakewords/
+│   ├── okay_nabu.json
+│   ├── okay_nabu.tflite          # Downloaded
+│   ├── stop.json
+│   ├── stop.tflite               # Downloaded
+│   ├── hey_jarvis.json           # Optional
+│   └── hey_jarvis.tflite         # Optional
+└── sounds/
+    ├── wake_word_triggered.flac  # You provide
+    └── timer_finished.flac       # You provide
+```
+
+## Troubleshooting
+
+### Wake Word Not Detected
+
+1. Check that the `.tflite` file exists
+2. Verify the `.json` configuration is correct
+3. Try a different wake word
+4. Check microphone input volume
+
+### Sound Not Playing
+
+1. Verify the sound file exists and is not empty
+2. Check audio output device is configured
+3. Try playing the file manually: `aplay sounds/wake_word_triggered.flac`
+
+### Model Loading Errors
+
+1. Ensure the model is compatible with your architecture
+2. Check that TensorFlow Lite is installed correctly
+3. Verify the model file is not corrupted
+
+## Additional Resources
+
+- [microWakeWord GitHub](https://github.com/kahrendt/microWakeWord)
+- [openWakeWord GitHub](https://github.com/dscripka/openWakeWord)
+- [Home Assistant Wake Words Collection](https://github.com/fwartner/home-assistant-wakewords-collection)
+- [ESPHome Voice Assistant](https://esphome.io/components/voice_assistant.html)

README_HF_SPACES.md

@@ -0,0 +1,98 @@
+# Reachy Mini Home Assistant Voice Assistant - Hugging Face Spaces
+
+这是一个可以通过 Hugging Face Spaces 一键安装的 Reachy Mini 语音助手应用，用于连接 Home Assistant。
+
+## 🚀 通过 Hugging Face Spaces 安装
+
+1. 访问你的 Reachy Mini 仪表板
+2. 进入 "Applications" -> "Install from Hugging Face"
+3. 搜索 "reachy-mini-ha-voice"
+4. 点击 "Install" 按钮
+5. 等待安装完成
+
+安装完成后，应用程序将出现在 "Applications" 列表中。
+
+## ⚙️ 配置
+
+安装后，点击应用设置图标进行配置：
+
+- **Device Name**: 设备名称（默认: ReachyMini）
+- **Enable Reachy**: 启用 Reachy Mini 机器人集成（默认: true）
+- **Audio Input Device**: 音频输入设备索引
+- **Audio Output Device**: 音频输出设备索引
+- **Wake Word**: 唤醒词（默认: okay_nabu）
+
+## 🔌 连接到 Home Assistant
+
+1. 在 Home Assistant 中，进入 "设置" -> "设备与服务"
+2. 点击 "添加集成" 按钮
+3. 选择 "ESPHome" 然后选择 "设置另一个 ESPHome 实例"
+4. 输入 Reachy Mini 的 IP 地址和端口 6053
+5. 点击 "提交"
+
+## 📝 使用说明
+
+### 启动应用
+
+在 Reachy Mini 仪表板中：
+1. 找到 "reachy-mini-ha-voice" 应用
+2. 点击 "Run" 按钮启动
+3. 应用将在端口 6053 上运行
+
+### 唤醒词
+
+默认唤醒词是 "Okay Nabu"。你可以说：
+- "Okay Nabu, turn on the lights"
+- "Okay Nabu, what's the weather?"
+- "Okay Nabu, set a timer for 5 minutes"
+
+### Reachy Mini 动作
+
+当启用 Reachy Mini 集成时，机器人会对不同的语音状态做出反应：
+- **唤醒时**: 头部抬起
+- **监听中**: 头部轻微摆动
+- **响应中**: 点头
+- **停止时**: 摇头
+
+## 🔧 故障排除
+
+### 音频设备问题
+
+如果无法检测到音频设备：
+
+1. 在 Reachy Mini 终端中运行：
+   ```bash
+   python -m reachy_mini_ha_voice --list-input-devices
+   python -m reachy_mini_ha_voice --list-output-devices
+   ```
+
+2. 在应用配置中设置正确的设备索引
+
+### 连接问题
+
+如果无法连接到 Home Assistant：
+
+1. 检查 Reachy Mini 和 Home Assistant 是否在同一网络
+2. 确认端口 6053 未被防火墙阻止
+3. 查看 Home Assistant 日志中的连接错误
+
+### 调试模式
+
+启用调试日志：
+
+在应用配置中添加环境变量：
+```
+DEBUG=true
+```
+
+## 📚 更多信息
+
+完整文档请访问: [README.md](README.md)
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 许可证
+
+Apache License 2.0

app.yaml

@@ -0,0 +1,67 @@
+# Reachy Mini App Configuration
+# This file is used by the Reachy Mini app assistant
+
+name: reachy-mini-ha-voice
+version: 1.0.0
+description: Home Assistant Voice Assistant for Reachy Mini using ESPHome protocol
+author: Reachy Mini HA Voice Contributors
+license: Apache-2.0
+
+# App type: python, javascript, or web
+type: python
+
+# Main entry point
+entry_point: reachy_mini_ha_voice.__main__:main
+
+# Dependencies
+dependencies:
+  - aioesphomeapi==42.7.0
+  - numpy>=2,<3
+  - pymicro-wakeword>=2,<3
+  - pyopen-wakeword>=1,<2
+  - pyaudio>=0.2.11
+  - zeroconf<1
+
+# Optional dependencies for Reachy Mini integration
+optional_dependencies:
+  - reachy-sdk
+
+# System requirements
+system_requirements:
+  - portaudio19-dev
+  - build-essential
+  - libportaudio2
+
+# Configuration options
+config:
+  - name: device_name
+    type: string
+    default: "ReachyMini"
+    description: "Device name for Home Assistant"
+  - name: enable_reachy
+    type: boolean
+    default: true
+    description: "Enable Reachy Mini robot integration"
+  - name: audio_input_device
+    type: integer
+    default: null
+    description: "Audio input device index"
+  - name: audio_output_device
+    type: integer
+    default: null
+    description: "Audio output device index"
+  - name: wake_word
+    type: string
+    default: "okay_nabu"
+    description: "Wake word to use"
+
+# Ports exposed by the app
+ports:
+  - 6053
+
+# Tags for categorization
+tags:
+  - voice
+  - home-assistant
+  - esphome
+  - assistant

pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=62.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name        = "reachy-mini-ha-voice"
+version     = "1.0.0"
+license     = {text = "Apache-2.0"}
+description = "Reachy Mini voice assistant for Home Assistant using ESPHome protocol"
+readme      = "README.md"
+authors     = [
+    {name = "Reachy Mini HA Voice Contributors", email = "hello@reachy-mini.org"}
+]
+keywords    = ["home", "assistant", "voice", "esphome", "reachy", "robot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+requires-python = ">=3.9.0"
+dependencies = [
+    "aioesphomeapi==42.7.0",
+    "numpy>=2,<3",
+    "pymicro-wakeword>=2,<3",
+    "pyopen-wakeword>=1,<2",
+    "pyaudio>=0.2.11",
+    "zeroconf<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "flake8",
+    "mypy",
+    "pylint",
+    "pytest",
+]
+
+[project.urls]
+"Source Code" = "https://github.com/your-username/reachy_mini_ha_voice"
+
+[tool.setuptools]
+platforms = ["any"]
+zip-safe  = true
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["reachy_mini_ha_voice"]
+exclude = ["tests", "tests.*"]

reachy_mini_ha_voice/__init__.py

@@ -0,0 +1,3 @@
+"""Reachy Mini Home Assistant Voice Assistant."""
+
+__version__ = "1.0.0"

reachy_mini_ha_voice/__main__.py

@@ -0,0 +1,449 @@
+#!/usr/bin/env python3
+"""Main entry point for Reachy Mini Home Assistant Voice Assistant."""
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+import threading
+import time
+from pathlib import Path
+from queue import Queue
+from typing import Dict, List, Optional, Set, Union
+
+import numpy as np
+import pyaudio
+from pymicro_wakeword import MicroWakeWord, MicroWakeWordFeatures
+from pyopen_wakeword import OpenWakeWord, OpenWakeWordFeatures
+
+from .models import AvailableWakeWord, Preferences, ServerState, WakeWordType, AudioPlayer
+from .satellite import VoiceSatelliteProtocol
+from .util import get_mac
+from .zeroconf import HomeAssistantZeroconf
+from .reachy_integration import ReachyMiniIntegration
+
+_LOGGER = logging.getLogger(__name__)
+_MODULE_DIR = Path(__file__).parent
+_REPO_DIR = _MODULE_DIR.parent
+_WAKEWORDS_DIR = _REPO_DIR / "wakewords"
+_SOUNDS_DIR = _REPO_DIR / "sounds"
+
+
+async def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Reachy Mini Voice Assistant for Home Assistant"
+    )
+    parser.add_argument("--name", required=True, help="Device name")
+    parser.add_argument(
+        "--audio-input-device",
+        type=int,
+        help="Audio input device index (see --list-input-devices)",
+    )
+    parser.add_argument(
+        "--list-input-devices",
+        action="store_true",
+        help="List audio input devices and exit",
+    )
+    parser.add_argument(
+        "--audio-output-device",
+        type=int,
+        help="Audio output device index (see --list-output-devices)",
+    )
+    parser.add_argument(
+        "--list-output-devices",
+        action="store_true",
+        help="List audio output devices and exit",
+    )
+    parser.add_argument(
+        "--wake-word-dir",
+        default=[_WAKEWORDS_DIR],
+        action="append",
+        help="Directory with wake word models (.tflite) and configs (.json)",
+    )
+    parser.add_argument(
+        "--wake-model", default="okay_nabu", help="Id of active wake model"
+    )
+    parser.add_argument("--stop-model", default="stop", help="Id of stop model")
+    parser.add_argument(
+        "--download-dir",
+        default=_REPO_DIR / "local",
+        help="Directory to download custom wake word models, etc.",
+    )
+    parser.add_argument(
+        "--refractory-seconds",
+        default=2.0,
+        type=float,
+        help="Seconds before wake word can be activated again",
+    )
+    parser.add_argument(
+        "--wakeup-sound", default=str(_SOUNDS_DIR / "wake_word_triggered.flac")
+    )
+    parser.add_argument(
+        "--timer-finished-sound", default=str(_SOUNDS_DIR / "timer_finished.flac")
+    )
+    parser.add_argument("--preferences-file", default=_REPO_DIR / "preferences.json")
+    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(
+        "--debug", action="store_true", help="Print DEBUG messages to console"
+    )
+    parser.add_argument(
+        "--enable-reachy",
+        action="store_true",
+        help="Enable Reachy Mini integration",
+    )
+    args = parser.parse_args()
+
+    # List devices and exit
+    if args.list_input_devices:
+        p = pyaudio.PyAudio()
+        print("Input devices")
+        print("=" * 13)
+        for i in range(p.get_device_count()):
+            info = p.get_device_info_by_index(i)
+            if info["maxInputChannels"] > 0:
+                print(f"[{i}] {info['name']}")
+        p.terminate()
+        return
+
+    if args.list_output_devices:
+        p = pyaudio.PyAudio()
+        print("Output devices")
+        print("=" * 14)
+        for i in range(p.get_device_count()):
+            info = p.get_device_info_by_index(i)
+            if info["maxOutputChannels"] > 0:
+                print(f"[{i}] {info['name']}")
+        p.terminate()
+        return
+
+    # Setup logging
+    logging.basicConfig(
+        level=logging.DEBUG if args.debug else logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+    _LOGGER.debug(args)
+
+    # Create directories
+    args.download_dir = Path(args.download_dir)
+    args.download_dir.mkdir(parents=True, exist_ok=True)
+
+    # Initialize Reachy Mini integration
+    reachy_integration = ReachyMiniIntegration()
+    if args.enable_reachy:
+        reachy_integration.connect()
+    else:
+        _LOGGER.info("Reachy Mini integration disabled")
+
+    # Load available wake words
+    wake_word_dirs = [Path(ww_dir) for ww_dir in args.wake_word_dir]
+    wake_word_dirs.append(args.download_dir / "external_wake_words")
+    available_wake_words: Dict[str, AvailableWakeWord] = {}
+
+    for wake_word_dir in wake_word_dirs:
+        if not wake_word_dir.exists():
+            continue
+
+        for model_config_path in wake_word_dir.glob("*.json"):
+            model_id = model_config_path.stem
+            if model_id == args.stop_model:
+                continue
+
+            try:
+                with open(model_config_path, "r", encoding="utf-8") as model_config_file:
+                    model_config = json.load(model_config_file)
+                    model_type = WakeWordType(model_config.get("type", "microWakeWord"))
+                    if model_type == WakeWordType.OPEN_WAKE_WORD:
+                        wake_word_path = model_config_path.parent / model_config["model"]
+                    else:
+                        wake_word_path = model_config_path
+
+                    available_wake_words[model_id] = AvailableWakeWord(
+                        id=model_id,
+                        type=WakeWordType(model_type),
+                        wake_word=model_config["wake_word"],
+                        trained_languages=model_config.get("trained_languages", []),
+                        wake_word_path=wake_word_path,
+                    )
+            except Exception as e:
+                _LOGGER.error("Error loading wake word config %s: %s", model_config_path, e)
+
+    _LOGGER.debug("Available wake words: %s", list(sorted(available_wake_words.keys())))
+
+    # Load preferences
+    preferences_path = Path(args.preferences_file)
+    if preferences_path.exists():
+        try:
+            with open(preferences_path, "r", encoding="utf-8") as preferences_file:
+                preferences_dict = json.load(preferences_file)
+                preferences = Preferences(**preferences_dict)
+        except Exception as e:
+            _LOGGER.error("Error loading preferences: %s", e)
+            preferences = Preferences()
+    else:
+        preferences = Preferences()
+
+    # Load wake/stop models
+    active_wake_words: Set[str] = set()
+    wake_models: Dict[str, Union[MicroWakeWord, OpenWakeWord]] = {}
+
+    if preferences.active_wake_words:
+        for wake_word_id in preferences.active_wake_words:
+            wake_word = available_wake_words.get(wake_word_id)
+            if wake_word is None:
+                _LOGGER.warning("Unrecognized wake word id: %s", wake_word_id)
+                continue
+
+            try:
+                _LOGGER.debug("Loading wake model: %s", wake_word_id)
+                wake_models[wake_word_id] = wake_word.load()
+                active_wake_words.add(wake_word_id)
+            except Exception as e:
+                _LOGGER.error("Error loading wake model %s: %s", wake_word_id, e)
+
+    if not wake_models:
+        wake_word_id = args.wake_model
+        if wake_word_id in available_wake_words:
+            try:
+                wake_word = available_wake_words[wake_word_id]
+                _LOGGER.debug("Loading wake model: %s", wake_word_id)
+                wake_models[wake_word_id] = wake_word.load()
+                active_wake_words.add(wake_word_id)
+            except Exception as e:
+                _LOGGER.error("Error loading default wake model: %s", e)
+        else:
+            _LOGGER.error("Default wake word not found: %s", wake_word_id)
+
+    # Load stop model
+    stop_model: Optional[MicroWakeWord] = None
+    for wake_word_dir in wake_word_dirs:
+        stop_config_path = wake_word_dir / f"{args.stop_model}.json"
+        if not stop_config_path.exists():
+            continue
+
+        try:
+            _LOGGER.debug("Loading stop model: %s", stop_config_path)
+            stop_model = MicroWakeWord.from_config(stop_config_path)
+            break
+        except Exception as e:
+            _LOGGER.error("Error loading stop model: %s", e)
+
+    if stop_model is None:
+        _LOGGER.warning("Stop model not loaded")
+
+    # Create audio players
+    music_player = AudioPlayer(device=args.audio_output_device)
+    tts_player = AudioPlayer(device=args.audio_output_device)
+
+    # Create server state
+    state = ServerState(
+        name=args.name,
+        mac_address=get_mac(),
+        audio_queue=Queue(),
+        entities=[],
+        available_wake_words=available_wake_words,
+        wake_words=wake_models,
+        active_wake_words=active_wake_words,
+        stop_word=stop_model,
+        music_player=music_player,
+        tts_player=tts_player,
+        wakeup_sound=args.wakeup_sound,
+        timer_finished_sound=args.timer_finished_sound,
+        preferences=preferences,
+        preferences_path=preferences_path,
+        refractory_seconds=args.refractory_seconds,
+        download_dir=args.download_dir,
+        reachy_integration=reachy_integration,
+    )
+
+    # Start audio processing thread
+    process_audio_thread = threading.Thread(
+        target=process_audio,
+        args=(state, args.audio_input_device),
+        daemon=True,
+    )
+    process_audio_thread.start()
+
+    # Start ESPHome server
+    loop = asyncio.get_running_loop()
+    server = await loop.create_server(
+        lambda: VoiceSatelliteProtocol(state), host=args.host, port=args.port
+    )
+
+    # Auto discovery (zeroconf, mDNS)
+    discovery = HomeAssistantZeroconf(port=args.port, name=args.name)
+    await discovery.register_server()
+
+    try:
+        async with server:
+            _LOGGER.info("Server started (host=%s, port=%s)", args.host, args.port)
+            if reachy_integration.is_connected():
+                _LOGGER.info("Reachy Mini integration enabled")
+            await server.serve_forever()
+    except KeyboardInterrupt:
+        _LOGGER.info("Shutting down...")
+    finally:
+        state.audio_queue.put_nowait(None)
+        process_audio_thread.join(timeout=5)
+        if reachy_integration.is_connected():
+            reachy_integration.disconnect()
+        music_player.close()
+        tts_player.close()
+        await discovery.unregister_server()
+
+    _LOGGER.debug("Server stopped")
+
+
+def process_audio(state: ServerState, input_device: Optional[int]) -> None:
+    """Process audio chunks from the microphone."""
+    import pyaudio
+
+    p = pyaudio.PyAudio()
+
+    # Get input device
+    if input_device is not None:
+        device_index = input_device
+    else:
+        # Try to find default input device
+        device_index = None
+        for i in range(p.get_device_count()):
+            info = p.get_device_info_by_index(i)
+            if info["maxInputChannels"] > 0 and info["isDefaultInputDevice"]:
+                device_index = i
+                break
+
+        if device_index is None:
+            _LOGGER.error("No default input device found")
+            return
+
+    device_info = p.get_device_info_by_index(device_index)
+    _LOGGER.info(
+        "Using audio input device: %s (index: %s)", device_info["name"], device_index
+    )
+
+    # Audio parameters
+    CHUNK = 1024
+    FORMAT = pyaudio.paInt16
+    CHANNELS = 1
+    RATE = 16000
+
+    try:
+        stream = p.open(
+            format=FORMAT,
+            channels=CHANNELS,
+            rate=RATE,
+            input=True,
+            input_device_index=device_index,
+            frames_per_buffer=CHUNK,
+        )
+
+        wake_words: List[Union[MicroWakeWord, OpenWakeWord]] = []
+        micro_features: Optional[MicroWakeWordFeatures] = None
+        micro_inputs: List[np.ndarray] = []
+
+        oww_features: Optional[OpenWakeWordFeatures] = None
+        oww_inputs: List[np.ndarray] = []
+        has_oww = False
+
+        last_active: Optional[float] = None
+
+        _LOGGER.info("Audio processing started")
+
+        while True:
+            try:
+                # Read audio chunk
+                data = stream.read(CHUNK, exception_on_overflow=False)
+                audio_array = np.frombuffer(data, dtype=np.int16).astype(np.float32) / 32768.0
+
+                # Send to satellite if connected
+                if state.satellite is not None:
+                    state.satellite.handle_audio(data)
+
+                # Update wake word models
+                if (not wake_words) or (state.wake_words_changed and state.wake_words):
+                    state.wake_words_changed = False
+                    wake_words = [
+                        ww
+                        for ww in state.wake_words.values()
+                        if ww.id in state.active_wake_words
+                    ]
+
+                    has_oww = False
+                    for wake_word in wake_words:
+                        if isinstance(wake_word, OpenWakeWord):
+                            has_oww = True
+
+                    if micro_features is None:
+                        micro_features = MicroWakeWordFeatures()
+
+                    if has_oww and (oww_features is None):
+                        oww_features = OpenWakeWordFeatures.from_builtin()
+
+                # Process wake words
+                if wake_words:
+                    assert micro_features is not None
+                    micro_inputs.clear()
+                    micro_inputs.extend(micro_features.process_streaming(data))
+
+                    if has_oww:
+                        assert oww_features is not None
+                        oww_inputs.clear()
+                        oww_inputs.extend(oww_features.process_streaming(data))
+
+                    for wake_word in wake_words:
+                        activated = False
+                        if isinstance(wake_word, MicroWakeWord):
+                            for micro_input in micro_inputs:
+                                if wake_word.process_streaming(micro_input):
+                                    activated = True
+                        elif isinstance(wake_word, OpenWakeWord):
+                            for oww_input in oww_inputs:
+                                for prob in wake_word.process_streaming(oww_input):
+                                    if prob > 0.5:
+                                        activated = True
+
+                        if activated:
+                            now = time.monotonic()
+                            if (last_active is None) or (
+                                (now - last_active) > state.refractory_seconds
+                            ):
+                                state.satellite.wakeup(wake_word)
+                                if state.reachy_integration.is_connected():
+                                    state.reachy_integration.on_wake_word_detected()
+                                last_active = now
+
+                    # Process stop word
+                    if state.stop_word is not None:
+                        stopped = False
+                        for micro_input in micro_inputs:
+                            if state.stop_word.process_streaming(micro_input):
+                                stopped = True
+
+                        if stopped and (state.stop_word.id in state.active_wake_words):
+                            state.satellite.stop()
+                            if state.reachy_integration.is_connected():
+                                state.reachy_integration.on_stop()
+
+            except Exception as e:
+                _LOGGER.error("Error processing audio: %s", e)
+                time.sleep(0.1)
+
+    except Exception as e:
+        _LOGGER.error("Error opening audio stream: %s", e)
+    finally:
+        stream.stop_stream()
+        stream.close()
+        p.terminate()
+        _LOGGER.info("Audio processing stopped")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

reachy_mini_ha_voice/api_server.py

@@ -0,0 +1,74 @@
+"""API server for Home Assistant integration."""
+
+import asyncio
+import json
+import logging
+from typing import Dict, List, Optional
+
+from .models import ServerState
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class APIServer:
+    """API server for Home Assistant."""
+
+    def __init__(self, state: ServerState):
+        """Initialize API server."""
+        self.state = state
+        self._handlers: Dict[str, callable] = {
+            "hello": self._handle_hello,
+            "list_entities": self._handle_list_entities,
+            "get_state": self._handle_get_state,
+            "subscribe_states": self._handle_subscribe_states,
+        }
+
+    async def handle_request(self, command: str, payload: dict) -> dict:
+        """Handle an API request."""
+        handler = self._handlers.get(command)
+        if handler:
+            try:
+                return await handler(payload)
+            except Exception as e:
+                _LOGGER.error("Error handling request %s: %s", command, e)
+                return {"error": str(e)}
+        else:
+            return {"error": f"Unknown command: {command}"}
+
+    async def _handle_hello(self, payload: dict) -> dict:
+        """Handle hello request."""
+        return {
+            "name": self.state.name,
+            "mac_address": self.state.mac_address,
+            "version": "1.0.0",
+        }
+
+    async def _handle_list_entities(self, payload: dict) -> dict:
+        """Handle list_entities request."""
+        entities = []
+        for entity in self.state.entities:
+            entities.append(
+                {
+                    "key": entity.key,
+                    "name": entity.name,
+                    "state": entity.state,
+                    "attributes": entity.attributes,
+                }
+            )
+        return {"entities": entities}
+
+    async def _handle_get_state(self, payload: dict) -> dict:
+        """Handle get_state request."""
+        key = payload.get("key")
+        entity = next((e for e in self.state.entities if e.key == key), None)
+        if entity:
+            return {
+                "key": entity.key,
+                "state": entity.state,
+                "attributes": entity.attributes,
+            }
+        return {"error": "Entity not found"}
+
+    async def _handle_subscribe_states(self, payload: dict) -> dict:
+        """Handle subscribe_states request."""
+        return {"result": "ok"}

reachy_mini_ha_voice/entity.py

@@ -0,0 +1,36 @@
+"""Entity management for Home Assistant."""
+
+import logging
+from typing import Dict, List
+
+from .models import Entity
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class EntityManager:
+    """Manage Home Assistant entities."""
+
+    def __init__(self):
+        """Initialize entity manager."""
+        self._entities: Dict[str, Entity] = {}
+
+    def add_entity(self, entity: Entity) -> None:
+        """Add an entity."""
+        self._entities[entity.key] = entity
+        _LOGGER.debug("Added entity: %s", entity.key)
+
+    def update_entity(self, key: str, state: str, attributes: Dict[str, str]) -> None:
+        """Update an entity."""
+        if key in self._entities:
+            self._entities[key].state = state
+            self._entities[key].attributes.update(attributes)
+            _LOGGER.debug("Updated entity: %s", key)
+
+    def get_entity(self, key: str) -> Entity:
+        """Get an entity by key."""
+        return self._entities.get(key)
+
+    def list_entities(self) -> List[Entity]:
+        """List all entities."""
+        return list(self._entities.values())

reachy_mini_ha_voice/models.py

@@ -0,0 +1,123 @@
+"""Data models for the voice assistant."""
+
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from queue import Queue
+from typing import Dict, List, Optional, Set, Union
+
+import numpy as np
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class WakeWordType(str, Enum):
+    """Type of wake word model."""
+
+    MICRO_WAKE_WORD = "microWakeWord"
+    OPEN_WAKE_WORD = "openWakeWord"
+
+
+@dataclass
+class AvailableWakeWord:
+    """Information about an available wake word model."""
+
+    id: str
+    type: WakeWordType
+    wake_word: str
+    trained_languages: List[str] = field(default_factory=list)
+    wake_word_path: Optional[Path] = None
+
+    def load(self):
+        """Load the wake word model."""
+        if self.type == WakeWordType.MICRO_WAKE_WORD:
+            from pymicro_wakeword import MicroWakeWord
+
+            return MicroWakeWord.from_config(self.wake_word_path)
+        elif self.type == WakeWordType.OPEN_WAKE_WORD:
+            from pyopen_wakeword import OpenWakeWord
+
+            return OpenWakeWord.from_config(self.wake_word_path)
+        else:
+            raise ValueError(f"Unknown wake word type: {self.type}")
+
+
+@dataclass
+class Preferences:
+    """User preferences."""
+
+    active_wake_words: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ServerState:
+    """Shared server state."""
+
+    name: str
+    mac_address: str
+    audio_queue: Queue
+    entities: List["Entity"]
+    available_wake_words: Dict[str, AvailableWakeWord]
+    wake_words: Dict[str, Union["MicroWakeWord", "OpenWakeWord"]]
+    active_wake_words: Set[str]
+    stop_word: "MicroWakeWord"
+    music_player: "AudioPlayer"
+    tts_player: "AudioPlayer"
+    wakeup_sound: str
+    timer_finished_sound: str
+    preferences: Preferences
+    preferences_path: Path
+    refractory_seconds: float
+    download_dir: Path
+    satellite: Optional["VoiceSatelliteProtocol"] = None
+    wake_words_changed: bool = True
+    reachy_integration: Optional["ReachyMiniIntegration"] = None
+
+
+@dataclass
+class Entity:
+    """A Home Assistant entity."""
+
+    key: str
+    name: str
+    state: str
+    attributes: Dict[str, str] = field(default_factory=dict)
+
+
+class AudioPlayer:
+    """Simple audio player using PyAudio."""
+
+    def __init__(self, device: Optional[int] = None):
+        """Initialize audio player."""
+        self.device = device
+        self._stream = None
+        self._pyaudio = None
+
+    def play(self, audio_data: bytes) -> None:
+        """Play audio data."""
+        import pyaudio
+
+        if self._pyaudio is None:
+            self._pyaudio = pyaudio.PyAudio()
+
+        # Assume 16-bit PCM, 16kHz, mono
+        if self._stream is None:
+            self._stream = self._pyaudio.open(
+                format=pyaudio.paInt16,
+                channels=1,
+                rate=16000,
+                output=True,
+                output_device_index=self.device,
+            )
+
+        self._stream.write(audio_data)
+
+    def close(self) -> None:
+        """Close the audio player."""
+        if self._stream is not None:
+            self._stream.close()
+            self._stream = None
+        if self._pyaudio is not None:
+            self._pyaudio.terminate()
+            self._pyaudio = None

reachy_mini_ha_voice/reachy_integration.py

@@ -0,0 +1,114 @@
+"""Reachy Mini integration module."""
+
+import logging
+from typing import Optional
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ReachyMiniIntegration:
+    """Integration with Reachy Mini robot."""
+
+    def __init__(self):
+        """Initialize Reachy Mini integration."""
+        self._reachy = None
+        self._connected = False
+
+    def connect(self) -> bool:
+        """Connect to Reachy Mini."""
+        try:
+            # Import reachy-mini SDK
+            # This will be installed when running on Reachy Mini
+            from reachy_sdk import ReachySDK
+
+            self._reachy = ReachySDK()
+            self._connected = True
+            _LOGGER.info("Connected to Reachy Mini")
+            return True
+        except ImportError:
+            _LOGGER.warning("Reachy SDK not available, running in standalone mode")
+            return False
+        except Exception as e:
+            _LOGGER.error("Failed to connect to Reachy Mini: %s", e)
+            return False
+
+    def disconnect(self) -> None:
+        """Disconnect from Reachy Mini."""
+        if self._reachy:
+            try:
+                self._reachy.disconnect()
+                self._connected = False
+                _LOGGER.info("Disconnected from Reachy Mini")
+            except Exception as e:
+                _LOGGER.error("Error disconnecting from Reachy Mini: %s", e)
+
+    def on_wake_word_detected(self) -> None:
+        """Handle wake word detection."""
+        if not self._connected:
+            return
+
+        try:
+            # Make Reachy Mini look up
+            self._reachy.head.tilt.goto(20, duration=0.5, wait=True)
+            self._reachy.head.pan.goto(0, duration=0.5, wait=True)
+            _LOGGER.debug("Reachy Mini: Look up on wake word")
+        except Exception as e:
+            _LOGGER.error("Error moving Reachy Mini on wake word: %s", e)
+
+    def on_listening(self) -> None:
+        """Handle listening state."""
+        if not self._connected:
+            return
+
+        try:
+            # Subtle head movement to indicate listening
+            self._reachy.head.pan.goto(10, duration=0.3, wait=True)
+            self._reachy.head.pan.goto(-10, duration=0.6, wait=True)
+            self._reachy.head.pan.goto(0, duration=0.3, wait=True)
+            _LOGGER.debug("Reachy Mini: Listening head movement")
+        except Exception as e:
+            _LOGGER.error("Error moving Reachy Mini while listening: %s", e)
+
+    def on_response(self) -> None:
+        """Handle response state."""
+        if not self._connected:
+            return
+
+        try:
+            # Nod to acknowledge
+            self._reachy.head.tilt.goto(10, duration=0.3, wait=True)
+            self._reachy.head.tilt.goto(-10, duration=0.6, wait=True)
+            self._reachy.head.tilt.goto(0, duration=0.3, wait=True)
+            _LOGGER.debug("Reachy Mini: Nod on response")
+        except Exception as e:
+            _LOGGER.error("Error moving Reachy Mini on response: %s", e)
+
+    def on_error(self) -> None:
+        """Handle error state."""
+        if not self._connected:
+            return
+
+        try:
+            # Tilt head to indicate error
+            self._reachy.head.tilt.goto(-20, duration=0.5, wait=True)
+            _LOGGER.debug("Reachy Mini: Tilt head on error")
+        except Exception as e:
+            _LOGGER.error("Error moving Reachy Mini on error: %s", e)
+
+    def on_stop(self) -> None:
+        """Handle stop command."""
+        if not self._connected:
+            return
+
+        try:
+            # Shake head to indicate stop
+            self._reachy.head.pan.goto(-15, duration=0.3, wait=True)
+            self._reachy.head.pan.goto(15, duration=0.6, wait=True)
+            self._reachy.head.pan.goto(0, duration=0.3, wait=True)
+            _LOGGER.debug("Reachy Mini: Shake head on stop")
+        except Exception as e:
+            _LOGGER.error("Error moving Reachy Mini on stop: %s", e)
+
+    def is_connected(self) -> bool:
+        """Check if connected to Reachy Mini."""
+        return self._connected

reachy_mini_ha_voice/satellite.py

@@ -0,0 +1,136 @@
+"""Voice satellite protocol implementation for ESPHome."""
+
+import asyncio
+import json
+import logging
+import struct
+from typing import Optional, Union
+
+from .models import ServerState
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VoiceSatelliteProtocol(asyncio.Protocol):
+    """ESPHome voice satellite protocol implementation."""
+
+    def __init__(self, state: ServerState):
+        """Initialize protocol."""
+        self.state = state
+        self.transport: Optional[asyncio.Transport] = None
+        self._buffer = bytearray()
+        self._connected = False
+
+    def connection_made(self, transport: asyncio.Transport) -> None:
+        """Handle new connection."""
+        self.transport = transport
+        self.state.satellite = self
+        self._connected = True
+        _LOGGER.info("Client connected: %s", transport.get_extra_info("peername"))
+
+    def connection_lost(self, exc: Optional[Exception]) -> None:
+        """Handle connection loss."""
+        self._connected = False
+        self.state.satellite = None
+        _LOGGER.info("Client disconnected")
+        if exc:
+            _LOGGER.error("Connection error: %s", exc)
+
+    def data_received(self, data: bytes) -> None:
+        """Handle incoming data."""
+        self._buffer.extend(data)
+
+        while len(self._buffer) >= 3:
+            # Parse message header
+            msg_type = self._buffer[0]
+            msg_length = struct.unpack(">H", self._buffer[1:3])[0]
+
+            if len(self._buffer) < 3 + msg_length:
+                # Need more data
+                break
+
+            # Extract message
+            msg_data = bytes(self._buffer[3 : 3 + msg_length])
+            self._buffer = self._buffer[3 + msg_length :]
+
+            # Process message
+            asyncio.create_task(self._process_message(msg_type, msg_data))
+
+    async def _process_message(self, msg_type: int, msg_data: bytes) -> None:
+        """Process a message."""
+        try:
+            if msg_type == 0x01:  # Hello
+                await self._handle_hello(msg_data)
+            elif msg_type == 0x02:  # Voice Assistant Start
+                await self._handle_voice_assistant_start(msg_data)
+            elif msg_type == 0x03:  # Voice Assistant End
+                await self._handle_voice_assistant_end(msg_data)
+            elif msg_type == 0x04:  # TTS Audio
+                await self._handle_tts_audio(msg_data)
+            else:
+                _LOGGER.warning("Unknown message type: %s", msg_type)
+        except Exception as e:
+            _LOGGER.error("Error processing message: %s", e)
+
+    async def _handle_hello(self, data: bytes) -> None:
+        """Handle hello message."""
+        _LOGGER.debug("Received hello message")
+        # Send hello response
+        response = self._build_message(0x01, json.dumps({"name": self.state.name}))
+        self._send_message(response)
+
+    async def _handle_voice_assistant_start(self, data: bytes) -> None:
+        """Handle voice assistant start message."""
+        _LOGGER.info("Voice assistant started")
+        # Play wake sound
+        try:
+            with open(self.state.wakeup_sound, "rb") as f:
+                self.state.tts_player.play(f.read())
+        except Exception as e:
+            _LOGGER.error("Error playing wake sound: %s", e)
+
+    async def _handle_voice_assistant_end(self, data: bytes) -> None:
+        """Handle voice assistant end message."""
+        _LOGGER.info("Voice assistant ended")
+
+    async def _handle_tts_audio(self, data: bytes) -> None:
+        """Handle TTS audio message."""
+        try:
+            self.state.tts_player.play(data)
+        except Exception as e:
+            _LOGGER.error("Error playing TTS audio: %s", e)
+
+    def handle_audio(self, audio_chunk: bytes) -> None:
+        """Handle audio chunk from microphone."""
+        if self._connected and self.transport:
+            # Send audio data to Home Assistant
+            message = self._build_message(0x10, audio_chunk)
+            self._send_message(message)
+
+    def wakeup(self, wake_word) -> None:
+        """Handle wake word detection."""
+        _LOGGER.info("Wake word detected: %s", wake_word.id)
+        # Send wake notification to Home Assistant
+        message = self._build_message(
+            0x11, json.dumps({"wake_word": wake_word.wake_word})
+        )
+        self._send_message(message)
+
+    def stop(self) -> None:
+        """Handle stop word detection."""
+        _LOGGER.info("Stop word detected")
+        # Send stop notification to Home Assistant
+        message = self._build_message(0x12, json.dumps({"action": "stop"}))
+        self._send_message(message)
+
+    def _build_message(self, msg_type: int, data: Union[str, bytes]) -> bytes:
+        """Build a message."""
+        if isinstance(data, str):
+            data = data.encode("utf-8")
+        length = len(data)
+        return bytes([msg_type]) + struct.pack(">H", length) + data
+
+    def _send_message(self, message: bytes) -> None:
+        """Send a message."""
+        if self._connected and self.transport:
+            self.transport.write(message)

reachy_mini_ha_voice/util.py

@@ -0,0 +1,19 @@
+"""Utility functions."""
+
+import logging
+import socket
+
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def get_mac() -> str:
+    """Get the MAC address of the first network interface."""
+    try:
+        mac = ":".join(
+            f"{byte:02x}" for byte in socket.gethostbyname(socket.gethostname()).encode()
+        )
+    except Exception:
+        mac = "00:00:00:00:00:00"
+
+    return mac

reachy_mini_ha_voice/zeroconf.py

@@ -0,0 +1,68 @@
+"""Zeroconf/mDNS service discovery for Home Assistant."""
+
+import asyncio
+import logging
+import socket
+from typing import Optional
+
+from zeroconf import IPVersion, ServiceInfo, Zeroconf
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class HomeAssistantZeroconf:
+    """Zeroconf service discovery for Home Assistant."""
+
+    def __init__(self, port: int, name: str):
+        """Initialize zeroconf discovery."""
+        self.port = port
+        self.name = name
+        self._zeroconf: Optional[Zeroconf] = None
+        self._service_info: Optional[ServiceInfo] = None
+
+    async def register_server(self) -> None:
+        """Register the server with zeroconf."""
+        try:
+            self._zeroconf = Zeroconf(ip_version=IPVersion.V4Only)
+
+            # Get local IP address
+            hostname = socket.gethostname()
+            local_ip = socket.gethostbyname(hostname)
+
+            # Create service info
+            service_type = "_esphomelib._tcp.local."
+            service_name = f"{self.name}._esphomelib._tcp.local."
+
+            self._service_info = ServiceInfo(
+                service_type,
+                name=service_name,
+                addresses=[socket.inet_aton(local_ip)],
+                port=self.port,
+                properties={
+                    "version": "1.0",
+                    "platform": "ReachyMini",
+                },
+                server=f"{hostname}.local.",
+            )
+
+            await asyncio.get_event_loop().run_in_executor(
+                None, self._zeroconf.register_service, self._service_info
+            )
+
+            _LOGGER.info(
+                "Registered zeroconf service: %s at %s:%s",
+                service_name,
+                local_ip,
+                self.port,
+            )
+        except Exception as e:
+            _LOGGER.error("Failed to register zeroconf service: %s", e)
+
+    async def unregister_server(self) -> None:
+        """Unregister the server from zeroconf."""
+        if self._zeroconf and self._service_info:
+            await asyncio.get_event_loop().run_in_executor(
+                None, self._zeroconf.unregister_service, self._service_info
+            )
+            self._zeroconf.close()
+            _LOGGER.info("Unregistered zeroconf service")

requirements.txt

@@ -0,0 +1,6 @@
+aioesphomeapi==42.7.0
+numpy>=2,<3
+pymicro-wakeword>=2,<3
+pyopen-wakeword>=1,<2
+pyaudio>=0.2.11
+zeroconf<1

script/download_assets.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Download wake word models and sound files."""
+
+import os
+import urllib.request
+from pathlib import Path
+
+
+def download_file(url: str, dest: Path) -> None:
+    """Download a file from URL to destination."""
+    print(f"Downloading {url}...")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    urllib.request.urlretrieve(url, dest)
+    print(f"Saved to {dest}")
+
+
+def main():
+    """Main function."""
+    base_dir = Path(__file__).parent.parent
+    wakewords_dir = base_dir / "wakewords"
+    sounds_dir = base_dir / "sounds"
+
+    print("Downloading wake word models...")
+
+    # Download okay_nabu model (microWakeWord)
+    download_file(
+        "https://github.com/kahrendt/microWakeWord/releases/download/v2.0.0/okay_nabu.tflite",
+        wakewords_dir / "okay_nabu.tflite",
+    )
+
+    # Download stop model (microWakeWord)
+    download_file(
+        "https://github.com/kahrendt/microWakeWord/releases/download/v2.0.0/stop.tflite",
+        wakewords_dir / "stop.tflite",
+    )
+
+    print("\nDownloading sound files...")
+
+    # Note: These are placeholder URLs. You may need to replace them with actual sound files
+    # or provide your own sound files.
+
+    print("\nSound files need to be provided manually.")
+    print("Please add the following files to the 'sounds' directory:")
+    print("  - wake_word_triggered.flac  (played when wake word is detected)")
+    print("  - timer_finished.flac       (played when timer finishes)")
+    print("\nYou can use any short audio file in FLAC or WAV format.")
+    print("For now, creating placeholder files...")
+
+    # Create empty placeholder files
+    (sounds_dir / "wake_word_triggered.flac").touch()
+    (sounds_dir / "timer_finished.flac").touch()
+
+    print("\nDownload complete!")
+    print("\nTo add more wake words, visit:")
+    print("  - https://github.com/kahrendt/microWakeWord (microWakeWord models)")
+    print("  - https://github.com/dscripka/openWakeWord (openWakeWord models)")
+    print("  - https://github.com/fwartner/home-assistant-wakewords-collection (collection)")
+
+
+if __name__ == "__main__":
+    main()

setup.ps1

@@ -0,0 +1,34 @@
+# Setup script for Reachy Mini Home Assistant Voice Assistant (Windows)
+
+Write-Host "Setting up Reachy Mini Home Assistant Voice Assistant..." -ForegroundColor Green
+
+# Create virtual environment
+if (-not (Test-Path ".venv")) {
+    Write-Host "Creating virtual environment..." -ForegroundColor Yellow
+    python -m venv .venv
+}
+
+# Activate virtual environment
+.venv\Scripts\Activate.ps1
+
+# Upgrade pip
+Write-Host "Upgrading pip..." -ForegroundColor Yellow
+pip install --upgrade pip setuptools wheel
+
+# Install dependencies
+Write-Host "Installing Python dependencies..." -ForegroundColor Yellow
+pip install -r requirements.txt
+
+# Install package
+Write-Host "Installing package..." -ForegroundColor Yellow
+pip install -e .
+
+Write-Host ""
+Write-Host "Setup complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "All wake word models and sound files are already included." -ForegroundColor Cyan
+Write-Host ""
+Write-Host "Run the application:" -ForegroundColor White
+Write-Host "  python -m reachy_mini_ha_voice --name 'ReachyMini' --enable-reachy" -ForegroundColor Gray
+Write-Host ""
+Write-Host "For more information, see README.md" -ForegroundColor Gray

setup.py

@@ -0,0 +1,23 @@
+"""Setup script for Reachy Mini Home Assistant Voice Assistant."""
+
+from setuptools import setup, find_packages
+
+setup(
+    name="reachy-mini-ha-voice",
+    version="1.0.0",
+    packages=find_packages(),
+    install_requires=[
+        "aioesphomeapi==42.7.0",
+        "numpy>=2,<3",
+        "pymicro-wakeword>=2,<3",
+        "pyopen-wakeword>=1,<2",
+        "pyaudio>=0.2.11",
+        "zeroconf<1",
+    ],
+    python_requires=">=3.9",
+    entry_points={
+        "console_scripts": [
+            "reachy-mini-ha-voice=reachy_mini_ha_voice.__main__:main",
+        ],
+    },
+)

setup.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Setup script for Reachy Mini Home Assistant Voice Assistant
+
+set -e
+
+echo "Setting up Reachy Mini Home Assistant Voice Assistant..."
+
+# Create virtual environment
+if [ ! -d ".venv" ]; then
+    echo "Creating virtual environment..."
+    python3 -m venv .venv
+fi
+
+# Activate virtual environment
+source .venv/bin/activate
+
+# Upgrade pip
+echo "Upgrading pip..."
+pip install --upgrade pip setuptools wheel
+
+# Install dependencies
+echo "Installing Python dependencies..."
+pip install -r requirements.txt
+
+# Install package
+echo "Installing package..."
+pip install -e .
+
+echo ""
+echo "Setup complete!"
+echo ""
+echo "All wake word models and sound files are already included."
+echo ""
+echo "Run the application:"
+echo "  python -m reachy_mini_ha_voice --name 'ReachyMini' --enable-reachy"
+echo ""
+echo "For more information, see README.md"

wakewords/alexa.json

@@ -0,0 +1,16 @@
+{
+  "type": "micro",
+  "wake_word": "Alexa",
+  "author": "Kevin Ahrendt",
+  "website": "https://www.kevinahrendt.com/",
+  "model": "alexa.tflite",
+  "trained_languages": ["en"],
+  "version": 2,
+  "micro": {
+    "probability_cutoff": 0.9,
+    "sliding_window_size": 5,
+    "feature_step_size": 10,
+    "tensor_arena_size": 22348,
+    "minimum_esphome_version": "2024.7.0"
+  }
+}

wakewords/choo_choo_homie.json

@@ -0,0 +1,18 @@
+{
+    "type": "micro",
+    "wake_word": "Choo Choo Homie",
+    "author": "Michael Hansen",
+    "website": "https://www.home-assistant.io",
+    "model": "choo_choo_homie.tflite",
+    "trained_languages": [
+        "en"
+    ],
+    "version": 2,
+    "micro": {
+        "probability_cutoff": 0.97,
+        "feature_step_size": 10,
+        "sliding_window_size": 5,
+        "tensor_arena_size": 30000,
+        "minimum_esphome_version": "2024.7.0"
+    }
+}

wakewords/hey_home_assistant.json

@@ -0,0 +1,16 @@
+{
+  "type": "micro",
+  "wake_word": "Hey Home Assistant",
+  "author": "Michael Hansen",
+  "website": "https://www.home-assistant.io",
+  "model": "hey_home_assistant.tflite",
+  "trained_languages": ["en"],
+  "version": 2,
+  "micro": {
+    "probability_cutoff": 0.97,
+    "feature_step_size": 10,
+    "sliding_window_size": 5,
+    "tensor_arena_size": 30000,
+    "minimum_esphome_version": "2024.7.0"
+  }
+}

wakewords/hey_jarvis.json

@@ -0,0 +1,16 @@
+{
+  "type": "micro",
+  "wake_word": "Hey Jarvis",
+  "author": "Kevin Ahrendt",
+  "website": "https://www.kevinahrendt.com/",
+  "model": "hey_jarvis.tflite",
+  "trained_languages": ["en"],
+  "version": 2,
+  "micro": {
+    "probability_cutoff": 0.97,
+    "feature_step_size": 10,
+    "sliding_window_size": 5,
+    "tensor_arena_size": 22860,
+    "minimum_esphome_version": "2024.7.0"
+  }
+}

wakewords/hey_luna.json

@@ -0,0 +1,16 @@
+{
+    "type": "micro",
+    "wake_word": "hey_luna",
+    "author": "adamlonsdale",
+    "website": "https://github.com/adamlonsdale",
+    "model": "hey_luna.tflite",
+    "version": 2,
+    "trained_languages": ["en"],
+    "micro": {
+      "probability_cutoff": 0.63,
+      "sliding_window_size": 5,
+      "feature_step_size": 10,
+      "tensor_arena_size": 22860,
+      "minimum_esphome_version": "2024.7.0"
+    }
+  }

wakewords/hey_mycroft.json

@@ -0,0 +1,16 @@
+{
+  "type": "micro",
+  "wake_word": "Hey Mycroft",
+  "author": "Kevin Ahrendt",
+  "website": "https://www.kevinahrendt.com/",
+  "model": "hey_mycroft.tflite",
+  "trained_languages": ["en"],
+  "version": 2,
+  "micro": {
+    "probability_cutoff": 0.95,
+    "sliding_window_size": 5,
+    "feature_step_size": 10,
+    "tensor_arena_size": 23628,
+    "minimum_esphome_version": "2024.7.0"
+  }
+}

wakewords/okay_computer.json

@@ -0,0 +1,18 @@
+{
+    "type": "micro",
+    "wake_word": "Okay Computer",
+    "author": "Michael Hansen",
+    "website": "https://www.home-assistant.io",
+    "model": "okay_computer.tflite",
+    "trained_languages": [
+        "en"
+    ],
+    "version": 2,
+    "micro": {
+        "probability_cutoff": 0.97,
+        "feature_step_size": 10,
+        "sliding_window_size": 5,
+        "tensor_arena_size": 30000,
+        "minimum_esphome_version": "2024.7.0"
+    }
+}

wakewords/okay_nabu.json

@@ -0,0 +1,16 @@
+{
+  "type": "micro",
+  "wake_word": "Okay Nabu",
+  "author": "Kevin Ahrendt",
+  "website": "https://www.kevinahrendt.com/",
+  "model": "okay_nabu.tflite",
+  "trained_languages": ["en","nl","fr","de","it","es","sv"],
+  "version": 2,
+  "micro": {
+    "probability_cutoff": 0.85,
+    "feature_step_size": 10,
+    "sliding_window_size": 5,
+    "tensor_arena_size": 37000,
+    "minimum_esphome_version": "2024.7.0"
+  }
+}

wakewords/openWakeWord/alexa_v0.1.json

@@ -0,0 +1,5 @@
+{
+  "type": "openWakeWord",
+  "wake_word": "Alexa",
+  "model": "alexa_v0.1.tflite"
+}

wakewords/openWakeWord/hey_jarvis_v0.1.json

@@ -0,0 +1,5 @@
+{
+  "type": "openWakeWord",
+  "wake_word": "Hey Jarvis",
+  "model": "hey_jarvis_v0.1.tflite"
+}

wakewords/openWakeWord/hey_mycroft_v0.1.json

@@ -0,0 +1,5 @@
+{
+  "type": "openWakeWord",
+  "wake_word": "Hey Mycroft",
+  "model": "hey_mycroft_v0.1.tflite"
+}

wakewords/openWakeWord/hey_rhasspy_v0.1.json

@@ -0,0 +1,5 @@
+{
+  "type": "openWakeWord",
+  "wake_word": "Hey Rhasspy",
+  "model": "hey_rhasspy_v0.1.tflite"
+}

wakewords/openWakeWord/ok_nabu_v0.1.json

@@ -0,0 +1,5 @@
+{
+  "type": "openWakeWord",
+  "wake_word": "Okay Nabu",
+  "model": "ok_nabu_v0.1.tflite"
+}

wakewords/stop.json

@@ -0,0 +1,16 @@
+{
+  "type": "micro",
+  "wake_word": "Stop",
+  "author": "Kevin Ahrendt",
+  "website": "https://www.kevinahrendt.com/",
+  "model": "stop.tflite",
+  "trained_languages": ["en"],
+  "version": 2,
+  "micro": {
+    "probability_cutoff": 0.5,
+    "feature_step_size": 10,
+    "sliding_window_size": 5,
+    "tensor_arena_size": 21000,
+    "minimum_esphome_version": "2024.7.0"
+  }
+}