Reachy Mini Sdk

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

# create_head_pose returns a 4x4 numpy ndarray (not a HeadPose object)
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 | minjerk | ease_in_out | 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) - mini.imu is a property returning a dict, or None
data = mini.imu
if data is not None:
    accel, gyro, quat = data["accelerometer"], data["gyroscope"], data["quaternion"]

Motion Recording

mini.start_recording()
# Move robot (e.g. by hand in gravity_compensation, or via goto_target)
frames = mini.stop_recording()   # returns a list of timestamped joint frames

stop_recording() returns a list of frame dicts (there is no Motion class on v1.8.0). Replay an authored move with mini.play_move(move) / mini.async_play_move(move), or play a saved dataset move over REST: POST /api/move/play/recorded-move-dataset/{dataset_name}/{move_name}.

REST API

See references/daemon_api.md for all 85 endpoints (v1.8.0). See references/openapi_usage.md for client generation.

Direct HTTP Control

import requests

# Move via API (head_pose: x,y,z in meters; roll,pitch,yaw in radians)
requests.post("http://localhost:8000/api/move/goto", json={
    "head_pose": {"x": 0, "y": 0, "z": 0.01, "roll": 0, "pitch": 0, "yaw": 0},
    "antennas": [0.5, -0.5],
    "body_yaw": 0.2,
    "duration": 2.0,
    "interpolation": "minjerk"
})

# Get state
state = requests.get("http://localhost:8000/api/state/full").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

The mode is a path segment (/api/motors/set_mode/{mode}), not a JSON body:

# Compliant (manual movement)
requests.post("http://localhost:8000/api/motors/set_mode/disabled")

# Active control
requests.post("http://localhost:8000/api/motors/set_mode/enabled")

# Gravity compensation
requests.post("http://localhost:8000/api/motors/set_mode/gravity_compensation")

# Current mode
requests.get("http://localhost:8000/api/motors/status").json()  # {"mode": "..."}

SDK equivalents: mini.enable_motors(), mini.disable_motors(), mini.enable_gravity_compensation(), mini.disable_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 (85 endpoints, v1.8.0)
• daemon_operations.md - Operating the daemon: app lock, motor modes, media, recovery
• 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.8.0, OpenAPI v3.1.0

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