Reachy Mini SDK

Programming guide for Reachy Mini - an open-source desktop humanoid robot with 6-DOF head, expressive antennas, and AI integration.

Hardware

• Head: 6-DOF Stewart platform (X,Y,Z + roll,pitch,yaw)
• Antennas: 2 servos
• Body: 360° yaw rotation
• Sensors: Camera, microphone, IMU (Wireless only)

Daemon: FastAPI on port 8000 (REST + WebSocket)

Quick Start

Installation

See references/installation.md for complete setup (uv/pip, platform-specific configs, permissions).

Basic Connection

from reachy_mini import ReachyMini

# Local
with ReachyMini() as mini:
    pass

# Remote (Wireless)
with ReachyMini(localhost_only=False) as mini:
    pass

Movement

See references/movement_control.md for complete guide (450+ lines with all patterns).

goto_target (Smooth Interpolation)

from reachy_mini.utils import create_head_pose
import numpy as np

mini.goto_target(
    head=create_head_pose(z=10, roll=15, degrees=True, mm=True),
    antennas=np.deg2rad([45, 45]),
    body_yaw=np.deg2rad(30),
    duration=2.0,
    method="minjerk"  # linear, ease, cartoon
)

set_target (Direct Control)

For high-frequency control (>30Hz):

mini.set_target(
    head=create_head_pose(z=5, mm=True),
    antennas=[0.5, -0.5]
)

Coordinates

• Head: Position in meters, orientation in radians
• Antennas: Radians (±1.5)
• Body: Radians (full 360°)

Sensors

See references/sensors.md for camera, audio, IMU details.

# Camera (BGR numpy array)
frame = mini.media.get_frame()

# Audio (16kHz stereo)
samples = mini.media.get_audio_sample()
mini.media.push_audio_sample(samples)  # Non-blocking

# IMU (Wireless only)
if hasattr(mini, 'imu'):
    data = mini.imu.get_data()

Motion Recording

mini.start_recording()
# Move robot
motion = mini.stop_recording()
motion.save("demo.pkl")

# Replay
motion.play()

REST API

See references/daemon_api.md for all 25+ endpoints. See references/openapi_usage.md for client generation.

Direct HTTP Control

import requests

# Move via API
requests.post("http://localhost:8000/api/goto", json={
    "head_pose": {"x": 0, "y": 0, "z": 0.01, "roll": 0, "pitch": 0, "yaw": 0},
    "duration": 2.0,
    "interpolation": "minjerk"
})

# Get state
state = requests.get("http://localhost:8000/api/state/full-state").json()

Generate Clients

See references/openapi_schema.json for OpenAPI v3.1.0 spec.

# Python
openapi-generator-cli generate -i openapi_schema.json -g python -o client/

# TypeScript
openapi-typescript openapi_schema.json -o types.ts

# Go, Rust, Java, etc. (50+ languages supported)

App Management

# Install app
requests.post("http://localhost:8000/api/apps/install", json={
    "name": "hand_tracker",
    "source": "hf_space",
    "space_id": "pollen-robotics/hand_tracker_v2"
})

# Start app
requests.post("http://localhost:8000/api/apps/start-app/hand_tracker")

Motor Modes

# Compliant (manual movement)
requests.post("http://localhost:8000/api/motors/set-mode", 
              json={"mode": "disabled"})

# Active control
requests.post("http://localhost:8000/api/motors/set-mode", 
              json={"mode": "enabled"})

# Gravity compensation
requests.post("http://localhost:8000/api/motors/set-mode", 
              json={"mode": "gravity_compensation"})

AI Integration

See references/ai_integration.md for LLM patterns, vision models, multimodal apps, and HuggingFace deployment.

Example: Object Detection

from transformers import pipeline

detector = pipeline("object-detection")
frame = mini.media.get_frame()
results = detector(frame)

# React to detections
for obj in results:
    if obj['label'] == 'person':
        mini.goto_target(antennas=np.deg2rad([45, 45]), duration=0.5)

Common Patterns

Greeting Sequence

def greet():
    mini.goto_target(head=create_head_pose(z=5, mm=True), duration=0.5)
    mini.goto_target(antennas=np.deg2rad([45, 45]), duration=0.5)
    for _ in range(2):
        mini.goto_target(head=create_head_pose(pitch=-10, degrees=True), duration=0.3)
        mini.goto_target(head=create_head_pose(pitch=10, degrees=True), duration=0.3)

Scanning Motion

for angle in [-60, -30, 0, 30, 60]:
    mini.goto_target(
        body_yaw=np.deg2rad(angle),
        head=create_head_pose(z=5, mm=True),
        duration=1.0
    )

Reference Files

• installation.md - Setup for Wireless/Lite/Simulation
• movement_control.md - Complete movement guide (450+ lines)
• sensors.md - Camera, microphone, IMU access
• ai_integration.md - AI models, LLMs, apps, deployment
• daemon_api.md - REST API reference (500+ lines, 25+ endpoints)
• openapi_schema.json - OpenAPI v3.1.0 spec for client generation
• openapi_usage.md - Using OpenAPI for automation
• api_quick_reference.md - Quick reference card

Platform Notes

• Wireless: Raspberry Pi, WiFi, includes IMU, use localhost_only=False from PC
• Lite: USB connection, no IMU, use localhost_only=True
• Simulation: MuJoCo-based, no hardware needed

Safety

• SDK enforces limits automatically
• Test in simulation first
• Use appropriate durations (0.5-2.0s typically)
• Always use context managers (with ReachyMini())

Version

SDK v1.2.6, OpenAPI v3.1.0

Source: https://github.com/pollen-robotics/reachy_mini/tree/1.2.6