Python Development Framework for Reachy Mini Robot
A clean, well-documented Python framework for controlling Reachy Mini robots with basic motion and audio interfaces.
ไธญๆๆๆกฃ | English
- ๐ฏ Unified Configuration - Configure once, use everywhere
- ๐ฎ Complete Demos - Audio control, body rotation, head motions, video streaming
- ๐ Comprehensive Docs - Full API reference and usage guides in EN/CN
- ๐ Ready for AI - Extensible interfaces for Agent and LLM integration
reachy-mini-starter/
โโโ src/ # Core library
โ โโโ connection.py # Connection management
โ โโโ config.py # Configuration management
โ โโโ logger.py # Logging system
โ โโโ utils.py # Utility functions
โโโ demos/ # Basic control demos
โ โโโ config_loader.py # Config loader
โ โโโ robot_config.yaml.template # Config template
โ โโโ 01_basic_audio_control/ # ๐ Audio control
โ โโโ 02_basic_body_rotation/ # ๐ Body rotation
โ โโโ 03_basic_nod_head/ # ๐ซก Nod head motion
โ โโโ 04_basic_shake_head/ # ๐ข Shake head motion
โ โโโ 05_webrtc_video_stream/ # ๐น WebRTC video streaming
โ โโโ 06_zenoh_basic_control/ # โก Zenoh protocol control
โ โโโ 07_audio_player/ # ๐ต Local audio player
โ โโโ 08_audio_stream_api/ # ๐ถ REST API audio streaming service
โ โโโ 09_mic_stream_to_pc/ # ๐๏ธ Microphone stream to PC
โ โโโ 10_vision_algorithms/ # ๐๏ธ OpenCV vision algorithms (face/motion/edge/color/corner detection)
โ โโโ 11_yolo_robot_control/ # ๐ค YOLO detection + Zenoh robot control
โ โโโ 12_antenna_angle_monitoring/ # ๐ก Antenna servo angle monitoring
โ โโโ 13_head_look_around/ # ๐ Head look around motion
โ โโโ 14_head_track_red_object/ # ๐ฏ Track red object with head
โ โโโ 15_web_realtime_control/ # ๐ Web-based real-time control
โ โโโ 16_bidirectional_audio/ # ๐๏ธ๐ Bidirectional audio service
โ โโโ 17_web_remote_camera/ # ๐ Web-based remote camera control
โ โโโ 18_webrtc_to_http_stream/ # ๐ก WebRTC to MJPEG video streaming
โโโ docs/ # Documentation
โ โโโ API_REFERENCE.md # API reference (EN)
โ โโโ USAGE_GUIDE.md # Usage guide (EN)
โ โโโ NETWORK_GUIDE.md # Network guide (EN)
โ โโโ GSTREAMER.md # GStreamer installation (EN)
โ โโโ API_REFERENCE_CN.md # API reference (ไธญๆ)
โ โโโ USAGE_GUIDE_CN.md # Usage guide (ไธญๆ)
โ โโโ NETWORK_GUIDE_CN.md # Network guide (ไธญๆ)
โ โโโ GSTREAMER_CN.md # GStreamer ๅฎ่ฃ
ๆๅ (ไธญๆ)
โโโ configs/ # Configuration files
โโโ scripts/ # Utility scripts
โโโ requirements.txt # Dependencies
- Python 3.7+
- Reachy Mini robot (connected to same network)
# Clone the repository
git clone https://github.com/yourusername/reachy-mini-starter.git
cd reachy-mini-starter
# Install dependencies
pip install -r requirements.txt
# Create configuration file
cp demos/robot_config.yaml.template demos/robot_config.yaml
# Edit the configuration with your robot's IP
# vim demos/robot_config.yaml (or use your preferred editor)Configuration file (demos/robot_config.yaml):
robot:
ip: "10.42.0.75" # Change to your robot's IP
port: 8000# ๐ต Audio Control - Speaker/microphone volume
python demos/01_basic_audio_control/test_audio_control.py
# ๐ Body Rotation - Base left/right rotation (ยฑ160ยฐ)
python demos/02_basic_body_rotation/test_body_rotation.py
# ๐ซก Nod Head - Head up/down motion
python demos/03_basic_nod_head/test_nod_head.py
# ๐ข Shake Head - Head left/right motion
python demos/04_basic_shake_head/test_shake_head.py
# ๐น WebRTC Video Stream - Receive video/audio from robot
python3 demos/05_webrtc_video_stream/05.py --signaling-host 10.42.0.75
# โก Zenoh Control - Low-latency control via Zenoh protocol
python3 demos/06_zenoh_basic_control/test_zenoh_control.py
# ๐ต Audio Player - Play local/online audio files (runs on robot)
python3 demos/07_audio_player/audio_player.py --file /path/to/audio.wav
# ๐ถ Audio Stream API - Start REST API service (runs on robot)
python3 demos/08_audio_stream_api/audio_stream_server.py
# ๐๏ธ Microphone Stream - Stream mic audio to PC (server on robot)
# Step 1: Start server on Reachy Mini
python3 demos/09_mic_stream_to_pc/bidirectional_audio_server.py
# Step 2: Receive stream on PC
python3 demos/09_mic_stream_to_pc/receive_mic_stream.py
# ๐๏ธ Vision Algorithms - OpenCV vision algorithms on video stream
python3 demos/10_vision_algorithms/10.py --signaling-host 10.42.0.75
# ๐ค YOLO + Robot Control - YOLO detection with Zenoh robot control
python3 demos/11_yolo_robot_control/11.py --signaling-host 10.42.0.75
# ๐ก Antenna Angle Monitoring - Query antenna servo angles via REST API
python demos/12_antenna_angle_monitoring/test_antenna_rest.py
# ๐ Head Look Around - Look around with head motion
python demos/13_head_look_around/13.py
# ๐ฏ Track Red Object - Track red object with head motion
python demos/14_head_track_red_object/14.py
# ๐๏ธ๐ Bidirectional Audio - Stream mic audio from robot to PC (server on robot)
# Step 1: Start server on Reachy Mini
python3 demos/16_bidirectional_audio/bidirectional_audio_server.py
# Step 2: Receive stream on PC
python3 demos/16_bidirectional_audio/receive_mic_stream.py
# ๐ Web Remote Camera - Control robot head via browser
python3 demos/17_web_remote_camera/server.py
# ๐ก WebRTC to MJPEG Stream - Watch robot video in browser
python3 demos/18_webrtc_to_http_stream/18.py --signaling-host 10.42.0.75All demos share demos/robot_config.yaml - configure once and use globally.
The configuration file is included in .gitignore to protect your private information.
| Endpoint | Method | Description | Demo |
|---|---|---|---|
/move/goto |
POST | Smooth motion to target | Body Rotation, Nod Head, Shake Head |
/move/set_target |
POST | Set target immediately | - |
/move/goto_joint_positions |
POST | Joint space motion | - |
/move/stop |
POST | Stop motion | All motion demos |
/motors/set_mode/{mode} |
POST | Set motor mode | All motion demos |
/volume/current |
GET | Get speaker volume | Audio Control |
/volume/set |
POST | Set speaker volume | Audio Control |
/volume/test-sound |
POST | Play test sound | Audio Control |
/volume/microphone/current |
GET | Get mic gain | Audio Control |
/volume/microphone/set |
POST | Set mic gain | Audio Control |
/state/present_antenna_joint_positions |
GET | Get antenna angles | Antenna Monitoring |
/state/full |
GET | Get full state | Antenna Monitoring |
/ws/signaling |
WS | WebRTC signaling | Video Stream |
| Endpoint | Description | Demo |
|---|---|---|
/move/ws/set_target |
Real-time control (60Hz+) | โณ Planned |
/state/ws/full |
State streaming | โณ Planned |
/move/ws/updates |
Motion events | โณ Planned |
| Topic | Description | Demo |
|---|---|---|
reachy_mini/command |
Command interface | Zenoh Control |
| Command | Description | Demo |
|---|---|---|
| PIN verification | Authentication | โณ Planned |
| Status query | Get device status | โณ Planned |
| Hotspot reset | Reset network | โณ Planned |
Note: This is a community-developed ROS2 middleware that converts native APIs to ROS2 topics, not an official interface.
| Topic | Message Type | Description | Demo |
|---|---|---|---|
/reachy_mini/head_command |
geometry_msgs/PoseStamped |
Head pose command | โณ Planned |
/reachy_mini/joint_command |
sensor_msgs/JointState |
Joint position command | โณ Planned |
/reachy_mini/joint_states |
sensor_msgs/JointState |
Current joint states | โณ Planned |
/reachy_mini/audio/play |
std_msgs/String |
Audio file to play | โณ Planned |
/reachy_mini/audio/volume |
std_msgs/UInt8 |
Speaker volume (0-100) | โณ Planned |
| Demo | Description | API Endpoints |
|---|---|---|
| ๐ Audio Control | Speaker/microphone volume & testing | /api/volume/* |
| ๐ Body Rotation | Base rotation (ยฑ160ยฐ) | /api/move/goto, /api/motors/* |
| ๐ซก Nod Head | Head pitch motion | /api/move/goto, /api/motors/* |
| ๐ข Shake Head | Head yaw motion | /api/move/goto, /api/motors/* |
| ๐น WebRTC Video | Real-time video/audio streaming | /ws/signaling |
| โก Zenoh Control | Low-latency protocol control | reachy_mini/command |
| ๐ต Audio Player | Play local/online audio files (on robot) | N/A (runs on robot) |
| ๐ถ Audio Stream API | REST API for remote audio control & streaming | Custom API (port 8001) |
| ๐๏ธ Mic Stream | Stream mic audio from robot to PC | WebSocket (port 8002) |
| ๐๏ธ Vision Algorithms | OpenCV algorithms (face/motion/edge/color/corner) | N/A (PC only) |
| ๐ค YOLO + Control | YOLO detection + Zenoh robot control | reachy_mini/command |
| ๐ก Antenna Monitor | Query antenna servo angles via REST API | /api/state/* |
| ๐ Head Look Around | Head look around motion | /api/move/goto |
| ๐ฏ Track Red Object | Track red object with head motion | /api/move/goto |
| ๐๏ธ๐ Bidirectional Audio | Bidirectional audio service via WebSocket | WebSocket (port 8002) |
| ๐ Web Real-time Control | Web-based real-time robot head control | WebSocket + REST API |
| ๐ Web Remote Camera | Web-based head control via browser | WebSocket + REST API |
| ๐ก WebRTC to MJPEG | Watch robot video stream in browser | MJPEG HTTP stream |
- ๐ API Reference Guide - Complete REST API reference
- ๐ Usage and Debugging Guide - Detailed usage instructions
- ๐ Network Configuration Guide - Network setup steps
- ๐บ GStreamer Installation Guide - WebRTC video streaming setup
- ๐ API ๆฅๅฃๅผๅๆๅ - ๅฎๆด็ REST API ๅ่ๆๆกฃ
- ๐ ไฝฟ็จไฟฎๆนๆๅ - ่ฏฆ็ป็ไฝฟ็จ่ฏดๆๅ่ฐ่ฏๆนๆณ
- ๐ ่ฟๆฅ้ ็ฝๆๅ - ็ฝ็ป่ฟๆฅ้ ็ฝฎๆญฅ้ชค
- ๐บ GStreamer ๅฎ่ฃ ๆๅ - WebRTC ่ง้ขๆตๅฎ่ฃ ้ ็ฝฎ
Current version provides basic control interfaces. Future plans:
- ๐๏ธ Vision System - Camera-based visual recognition
- ๐ค YOLO Integration - Object detection with robot control
- ๐ก State Monitoring - Antenna servo angle monitoring
- ๐ค Agent Integration - AI Agent for intelligent decision-making
- ๐ง LLM Integration - Natural language interaction
- ๐ค Voice Interaction - Speech recognition and synthesis
- ๐ Emotional Expression - Emotion-based motion expressions
This project is licensed under the MIT License - see LICENSE for details.
Contributions are welcome! Please feel free to submit a Pull Request.
Built with โค๏ธ for the Reachy Mini community
Powered by Seeed Studio