reachy-mini-sdk

name	reachy-mini-sdk
description	Programming guide for Reachy Mini robot using Python SDK v1.2.6 and REST API. Use when controlling Reachy Mini robots, programming movements (head/antennas/body), accessing sensors (camera/microphone/IMU), recording motions, building AI applications, deploying to Hugging Face, or using the daemon REST API. Covers SDK patterns, coordinate systems, interpolation methods, app management, and OpenAPI client generation.
license	MIT (see LICENSE.txt)

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