Quick Start Guide
This guide will help you quickly set up the Reachy Mini Home Assistant Voice Assistant.
Prerequisites
- Reachy Mini robot (connected and powered on)
- Home Assistant instance with ESPHome integration
- Python 3.8 or higher installed on Reachy Mini
- Network connection between Reachy Mini and Home Assistant
Step 1: Install Dependencies
# SSH into your Reachy Mini
ssh reachy@<reachy-ip>
# Clone the repository
git clone https://github.com/yourusername/reachy_mini_ha_voice.git
cd reachy_mini_ha_voice
# Create virtual environment
python -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e .
Step 2: Download Wake Word Models
# Download Okay Nabu model (default)
cd wakewords
wget https://github.com/kah0st/microWakeWord/raw/main/models/okay_nabu.tflite -O okay_nabu.tflite
cp okay_nabu.json.example okay_nabu.json
# Optional: Download Hey Jarvis model
wget https://github.com/kah0st/microWakeWord/raw/main/models/hey_jarvis.tflite -O hey_jarvis.tflite
wget https://github.com/kah0st/microWakeWord/raw/main/models/hey_jarvis.json -O hey_jarvis.json
cd ..
Step 3: Configure Audio Devices
# List available audio devices
python -m reachy_mini_ha_voice --list-input-devices
python -m reachy_mini_ha_voice --list-output-devices
# Note the device names you want to use
Step 4: Create Configuration
# Copy environment template
cp .env.example .env
# Edit .env file
nano .env
Add your configuration:
# Audio Configuration
AUDIO_INPUT_DEVICE=Reachy Microphone
AUDIO_OUTPUT_DEVICE=Reachy Speaker
AUDIO_SAMPLE_RATE=16000
AUDIO_CHANNELS=1
AUDIO_BLOCK_SIZE=1024
# Voice Configuration
WAKE_WORD=okay_nabu
WAKE_WORD_DIR=wakewords
# Motion Configuration
MOTION_ENABLED=true
SPEECH_REACTIVE=true
# ESPHome Configuration
ESPHOME_HOST=0.0.0.0
ESPHOME_PORT=6053
ESPHOME_NAME=Reachy Mini
# Robot Configuration
ROBOT_HOST=localhost
ROBOT_WIRELESS=false
# Logging
LOG_LEVEL=INFO
Step 5: Start the Application
# Start the voice assistant
python -m reachy_mini_ha_voice
# Or with custom configuration
python -m reachy_mini_ha_voice \
--name "My Reachy Mini" \
--audio-input-device "Reachy Microphone" \
--audio-output-device "Reachy Speaker" \
--wake-model okay_nabu
Step 6: Connect to Home Assistant
- Open Home Assistant
- Go to Settings → Devices & Services
- Click Add Integration
- Search for ESPHome
- Click Set up another instance of ESPHome
- Enter Reachy Mini's IP address and port (default: 6053)
- Click Submit
Step 7: Test
- Say the wake word: "Okay Nabu"
- Reachy Mini should nod to acknowledge
- Speak your command
- Reachy Mini should respond with motion and voice (if configured)
Troubleshooting
Wake Word Not Detected
- Check if the wake word model is downloaded:
ls wakewords/ - Verify the model name in configuration matches the file
- Check microphone is working:
python -m reachy_mini_ha_voice --list-input-devices - Increase microphone volume if needed
No Audio Output
- Check speaker is working:
python -m reachy_mini_ha_voice --list-output-devices - Verify audio output device name in configuration
- Check speaker volume
Cannot Connect to Home Assistant
- Verify network connectivity:
ping <home-assistant-ip> - Check ESPHome port (6053) is not blocked by firewall
- Ensure Home Assistant ESPHome integration is installed
- Check Home Assistant logs for connection errors
Motion Not Working
- Verify Reachy Mini is connected: Check if robot responds to basic commands
- Check robot host in configuration
- Ensure Reachy Mini SDK is installed:
pip show reachy-mini - Check robot is not in sleep mode
Advanced Configuration
Custom Wake Word
- Train your own wake word model (see wakewords/README.md)
- Place the model files in wakewords/ directory
- Update configuration to use your model
Multiple Wake Words
# Add additional wake word models to wakewords/ directory
# Update configuration to enable multiple wake words
Web UI
# Start with Gradio web interface
python -m reachy_mini_ha_voice --gradio
# Access at http://<reachy-ip>:7860
Wireless Reachy Mini
# For wireless version
python -m reachy_mini_ha_voice --wireless
Next Steps
- Read the full README.md for detailed documentation
- Check ARCHITECTURE.md for system architecture
- See REQUIREMENTS.md for detailed requirements
- Explore profiles/ for personality customization
Support
- GitHub Issues: https://github.com/yourusername/reachy_mini_ha_voice/issues
- Documentation: https://github.com/yourusername/reachy_mini_ha_voice#readme
- Community: Join our Discord server
Happy talking with your Reachy Mini! 🤖