Reachy Mini Robot Control

Quick Start

Use the CLI script or curl to control the robot. The script lives at:
CODEBLOCK0

Set the robot IP via REACHY_HOST env var or --host flag. Default: 192.168.8.17.

Common Commands

Environment

Movement Guide

Head Control (6 DoF)

• - Pitch (look up/down): -0.5 (up) to 0.5 (down)
• Yaw (look left/right): -0.8 (right) to 0.8 (left)
• Roll (tilt sideways): -0.5 to 0.5

CODEBLOCK2

Body Rotation (360°)

Antennas

Combined Movements

Interpolation Modes

• - minjerk — Smooth, natural (default)
• INLINECODE17 — Constant speed
• INLINECODE18 — Ease in/out
• INLINECODE19 — Bouncy, exaggerated

Emotions & Dances

Playing Emotions

Playing Dances

Full Lists

Motor Modes

Before movement, motors must be enabled. Check with reachy.sh motors.

CODEBLOCK8

Volume Control

App Management

Reachy Mini runs HuggingFace Space apps. Manage them via:
CODEBLOCK10

Important: Only one app runs at a time. Starting a new app stops the current one. Apps may take exclusive control of the robot — stop the running app before sending manual movement commands if the robot doesn't respond.

Camera Snapshots

Capture JPEG photos from the robot's camera (IMX708 wide-angle) via WebRTC — non-disruptive to the running daemon.

CODEBLOCK11

Requirements: SSH access to the robot (uses sshpass + REACHY_SSH_PASS env var, default: root).

How it works: Connects to the daemon's WebRTC signalling server (port 8443) using GStreamer's webrtcsrc plugin on the robot, captures one H264-decoded frame, and saves as JPEG. No daemon restart, no motor disruption.

Note: The robot must be awake (head up) for a useful image. If asleep, the camera faces into the body. Run reachy.sh wake-up first.

Audio Sensing

reachy.sh doa               # Direction of Arrival from mic array

Contextual Reactions (Clawdbot Integration)

Use reachy-react.sh to trigger contextual robot behaviors from heartbeats, cron jobs, or session responses.

CODEBLOCK13

Reactions

Pass --bg to run in background (non-blocking).

Built-in Behaviors

• - Quiet hours (22:00–06:29 ET): All reactions except morning, goodnight, and patrol are silently skipped.
• Auto-wake: Reactions ensure the robot is awake before acting (starts daemon + wakes if needed).
• Fault-tolerant: If robot is unreachable, reactions exit cleanly without errors.

Integration Points

DOA (Direction of Arrival) Tracking

The doa-track reaction uses the robot's 4-mic array to detect speech direction and turn the head toward the speaker. The DOA angle (0=left, π/2=front, π=right) is mapped to head yaw. Only triggers when speech is actively detected.

Camera Patrol

The patrol reaction captures a snapshot and prints the image path. Use this during heartbeats to check the room periodically. Combine with image analysis to detect activity or changes.

Direct API Access

For anything not covered by the CLI, use curl or the raw command:
CODEBLOCK15

Reference

For the complete API endpoint list, schemas (GotoModelRequest, FullBodyTarget, XYZRPYPose), and full emotion/dance catalogs, see references/api-reference.md.

Troubleshooting

• - Robot doesn't move: Check reachy.sh motors — must be enabled. Run reachy.sh motors-enable.
• No response: Check reachy.sh status. State should be running. If not, run reachy.sh reboot-daemon.
• Movements ignored: An app may have exclusive control. Run reachy.sh app-stop first.
• Network unreachable: Verify the robot IP with ping $REACHY_HOST. Check reachy.sh wifi-status.
• Snap shows black image: Robot is likely asleep (head down). Run reachy.sh wake-up first.
• Snap fails with SSH error: Ensure sshpass is installed and REACHY_SSH_PASS is set correctly.