reachy-mini

majiayu000 的头像作者 majiayu000

用于控制 Reachy Mini 机器人的完整 SDK - 头部运动、天线、摄像头、音频、运动记录/回放。涵盖架构(守护程序/客户端)、部署模式(USB、无线、模拟、Pi 上)和应用程序分发。还包括高级应用程序模式:运动管理器、分层运动、音频反应运动、面部跟踪、LLM 工具系统和 OpenAI 实时集成。使用场合:(1) 编写代码来控制 Reachy Mini,(2) 移动机器人头部或天线, (3) 访问摄像头/视频,(4) 播放/录制音频,(5) 记录或回放动作,(6) 查看图像或世界空间中的点,(7) 了解机器人功能,(8) 连接到真实或模拟机器人,(9) 构建对话式 AI 应用程序,(10) 与 LLM/OpenAI 集成,(11) 将应用程序部署到机器人,(12) 使用 Reachy Mini 执行任何机器人任务。

📖 中文导读:用于控制 Reachy Mini 机器人的完整 SDK - 头部运动、天线、摄像头、音频、运动记录/回放。涵盖架构(守护程序/客户端)、部署模式(USB、无线、模拟、Pi 上)和应用程序分发。还包括高级应用程序模式:运动管理器、分层运动、音频反应运动、面部跟踪、LLM 工具系统和 OpenAI 实时集成。使用场合:(1) 编写代码来控制 Reachy Mini,(2) 移动机器人头部或天线, (3) 访问摄像头/视频,(4) 播放/录制音频,(5) 记录或回放动作,(6) 查看图像或世界空间中的点,(7) 了解机器人功能,(8) 连接到真实或模拟机器人,(9) 构建对话式 AI 应用程序,(10) 与 LLM/OpenAI 集成,(11) 将应用程序部署到机器人,(12) 使用 Reachy Mini 执行任何机器人任务。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: reachy-mini description: | Complete SDK for controlling Reachy Mini robot - head movement, antennas, camera, audio, motion recording/playback. Covers architecture (daemon/client), deployment modes (USB, wireless, simulation, on-Pi), and app distribution. Also includes advanced application patterns: MovementManager, layered motion, audio-reactive movement, face tracking, LLM tool systems, and OpenAI realtime integration. Use when: (1) Writing code to control Reachy Mini, (2) Moving the robot head or antennas, (3) Accessing camera/video, (4) Playing/recording audio, (5) Recording or playing back motions, (6) Looking at points in image or world space, (7) Understanding robot capabilities, (8) Connecting to real or simulated robot, (9) Building conversational AI apps, (10) Integrating with LLMs/OpenAI, (11) Deploying apps to robot, (12) Any robotics task with Reachy Mini.

Reachy Mini SDK

Quick Start

from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose
import numpy as np

with ReachyMini() as robot:
    robot.wake_up()

    # Move head
    pose = create_head_pose(x=0, y=0, z=0, roll=0, pitch=10, yaw=20, degrees=True)
    robot.goto_target(head=pose, antennas=[0.3, -0.3], duration=1.0)

    # Get camera frame
    frame = robot.media.get_frame()  # Returns BGR numpy array

    robot.goto_sleep()

Connection Options

# Local USB connection (default)
ReachyMini()

# Network discovery
ReachyMini(localhost_only=False)

# Simulation mode
ReachyMini(use_sim=True)

# Auto-spawn daemon
ReachyMini(spawn_daemon=True)

# Full options
ReachyMini(
    robot_name="reachy_mini",       # Robot identifier
    localhost_only=True,            # True=local daemon, False=network discovery
    spawn_daemon=False,             # Auto-spawn daemon process
    use_sim=False,                  # Use MuJoCo simulation
    timeout=5.0,                    # Connection timeout (seconds)
    automatic_body_yaw=True,        # Auto body yaw in IK
    log_level="INFO",               # "DEBUG", "INFO", "WARNING", "ERROR"
    media_backend="default"         # "default", "gstreamer", "webrtc", "no_media"
)

Head & Antenna Control

Creating Poses

from reachy_mini.utils import create_head_pose

# By position and rotation (degrees by default)
pose = create_head_pose(x=0, y=0, z=0, roll=0, pitch=15, yaw=-10, degrees=True)

# In radians
pose = create_head_pose(pitch=0.26, yaw=-0.17, degrees=False)

# Position in millimeters
pose = create_head_pose(x=50, y=0, z=30, mm=True)

Moving the Robot

from reachy_mini.motion.goto_move import InterpolationTechnique

# Immediate position (no interpolation)
robot.set_target(head=pose, antennas=[0.5, -0.5], body_yaw=0.1)

# Smooth motion with duration
robot.goto_target(
    head=pose,
    antennas=[0.5, -0.5],  # [right, left] in radians
    duration=1.0,
    method=InterpolationTechnique.MIN_JERK,
    body_yaw=0.0
)

Interpolation methods:

  • LINEAR - Linear interpolation
  • MIN_JERK - Default, smoothest motion
  • EASE_IN_OUT - Smooth start and end
  • CARTOON - Exaggerated animation style

Look-At Functions

# Look at pixel coordinates in camera image
robot.look_at_image(u=320, v=240, duration=0.5)

# Look at 3D world point (meters from robot origin)
robot.look_at_world(x=0.5, y=0.1, z=0.3, duration=0.5)

# Get pose without moving
pose = robot.look_at_image(u=320, v=240, perform_movement=False)

Antenna Values

Antennas are [right_angle, left_angle] in radians:

  • 0.0 = antennas down/closed
  • Positive = antennas up/open
  • Typical range: -0.5 to 1.0 radians

State Queries

# Current head pose (4x4 matrix)
pose = robot.get_current_head_pose()

# Joint positions
head_joints, antenna_joints = robot.get_current_joint_positions()
# head_joints: 7 values (body_rotation + 6 stewart platform)
# antenna_joints: 2 values [right, left]

# Antenna positions only
antennas = robot.get_present_antenna_joint_positions()  # [right, left]

Motor Control

# Enable/disable all motors
robot.enable_motors()
robot.disable_motors()

# Specific motors
robot.enable_motors(ids=["right_antenna", "left_antenna"])
robot.disable_motors(ids=["body_rotation"])

Motor IDs: "body_rotation", "stewart_1" through "stewart_6", "right_antenna", "left_antenna"

# Gravity compensation (requires Placo kinematics)
robot.enable_gravity_compensation()
robot.disable_gravity_compensation()

Behaviors

robot.wake_up()     # Wake animation + sound
robot.goto_sleep()  # Sleep position + sound

Camera

# Get frame (BGR numpy array, or None if unavailable)
frame = robot.media.get_frame()

# Camera properties
width, height = robot.media.camera.resolution
fps = robot.media.camera.framerate
K = robot.media.camera.K  # 3x3 intrinsic matrix
D = robot.media.camera.D  # Distortion coefficients

# Change resolution
from reachy_mini.media.camera.camera_constants import CameraResolution
robot.media.camera.set_resolution(CameraResolution.R1920x1080at30fps)

Common resolutions: R1280x720at30fps, R1280x720at60fps, R1920x1080at30fps, R1920x1080at60fps, R3840x2160at30fps

Audio

# Play sound file
robot.media.play_sound("wake_up.wav")

# Record audio
robot.media.start_recording()
sample = robot.media.get_audio_sample()  # numpy array
robot.media.stop_recording()

# Stream audio output
robot.media.start_playing()
robot.media.push_audio_sample(audio_data)
robot.media.stop_playing()

# Audio specs
sample_rate = robot.media.get_input_audio_samplerate()  # 16000 Hz
channels = robot.media.get_input_channels()  # 2

# Direction of Arrival (ReSpeaker only)
angle, valid = robot.media.get_DoA()  # angle in radians (0=left, pi/2=front, pi=right)

Motion Recording & Playback

Recording

robot.start_recording()
# ... perform motions manually or via code ...
recorded_data = robot.stop_recording()
# Returns list of dicts with timestamps, poses, joint positions

Playing Recorded Moves

from reachy_mini.motion.recorded_move import RecordedMoves

# Load move library from HuggingFace
moves = RecordedMoves("pollen-robotics/reachy-mini-dances-library")

# List available moves
print(moves.list_moves())

# Play a move
move = moves.get("dance_name")
robot.play_move(move, initial_goto_duration=1.0, sound=True)

# Async playback
await robot.async_play_move(move)

Kinematics

Three engines available:

Engine Install Speed Features
AnalyticalKinematics Default Fast Always available
PlacoKinematics pip install reachy_mini[placo_kinematics] Medium Collision checking, gravity compensation
NNKinematics pip install reachy_mini[nn_kinematics] Very fast Neural network based
# Direct kinematics access
from reachy_mini.kinematics.analytical import AnalyticalKinematics

kin = AnalyticalKinematics()
joint_angles = kin.ik(pose, body_yaw=0.0)  # Inverse kinematics: pose -> joints
pose = kin.fk(joint_angles)                 # Forward kinematics: joints -> pose

Simulation

# Start with simulation
robot = ReachyMini(use_sim=True)

# Or via daemon CLI
# reachy-mini-daemon --sim

Common Patterns

Face Tracking

# Detect face, get center coordinates (u, v)
robot.look_at_image(u=face_center_x, v=face_center_y, duration=0.3)

Expressive Movements

# Happy - antennas up
robot.goto_target(antennas=[0.8, 0.8], duration=0.3)

# Sad - antennas down
robot.goto_target(antennas=[-0.3, -0.3], duration=0.5)

# Curious tilt
pose = create_head_pose(roll=15, pitch=10, degrees=True)
robot.goto_target(head=pose, duration=0.4)

Idle Animation Loop

import time
while True:
    robot.goto_target(head=create_head_pose(yaw=10, degrees=True), duration=2.0)
    time.sleep(2.0)
    robot.goto_target(head=create_head_pose(yaw=-10, degrees=True), duration=2.0)
    time.sleep(2.0)

Reference Documentation

  • Architecture & Deployment - Daemon/client split, deployment modes (USB, wireless, simulation), running code, app distribution
  • API Reference - Complete method signatures, all parameters and return types
  • Motion Reference - Interpolation details, Move classes, GotoMove, RecordedMove
  • Media Reference - All camera resolutions, audio specs, backend options
  • Application Patterns - Advanced patterns: MovementManager, layered motion, audio-reactive movement, face tracking, LLM tool systems, OpenAI realtime integration