reachy-mini

# Reachy Mini Robot Control ## Quick Start Use the CLI script or `curl` to control the robot. The script lives at: ``` ~/clawd/skills/reachy-mini/scripts/reachy.sh ``` Set the robot IP via `REACHY_HOST` env var or `--host` flag. Default: `192.168.8.17`. ### Common Commands ```bash reachy.sh status # Daemon status, version, IP reachy.sh state # Full robot state reachy.sh wake-up # Wake the robot reachy.sh sleep # Put to sleep reachy.sh snap # Camera snapshot → /tmp/reachy_snap.jpg reachy.sh snap /path/to/photo.jpg # Snapshot to custom path reachy.sh play-emotion cheerful1 # Play an emotion reachy.sh play-dance groovy_sway_and_roll # Play a dance reachy.sh goto --head 0.2,0,0 --duration 1.5 # Nod down reachy.sh volume-set 70 # Set speaker volume reachy.sh emotions # List all emotions reachy.sh dances # List all dances ``` ## Environment | Variable | Default | Description | |----------|---------|-------------| | `REACHY_HOST` | `192.168.8.17` | Robot IP address | | `REACHY_PORT` | `8000` | REST API port | | `REACHY_SSH_USER` | `pollen` | SSH username (for `snap` command) | | `REACHY_SSH_PASS` | `root` | SSH password (for `snap` command, uses `sshpass`) | ## Movement Guide ### Head Control (6 DoF) The head accepts pitch, yaw, roll in **radians**: - **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 ```bash # Look up reachy.sh goto --head -0.3,0,0 --duration 1.0 # Look left reachy.sh goto --head 0,0.4,0 --duration 1.0 # Tilt head right, look slightly up reachy.sh goto --head -0.1,0,-0.3 --duration 1.5 # Return to neutral reachy.sh goto --head 0,0,0 --duration 1.0 ``` ### Body Rotation (360°) Body yaw in radians. 0 = forward, positive = left, negative = right. ```bash reachy.sh goto --body 1.57 --duration 2.0 # Turn 90° left reachy.sh goto --body -1.57 --duration 2.0 # Turn 90° right reachy.sh goto --body 0 --duration 2.0 # Face forward ``` ### Antennas Two antennas [left, right] in radians. Range ~-0.5 to 0.5. ```bash reachy.sh goto --antennas 0.4,0.4 --duration 0.5 # Both up reachy.sh goto --antennas -0.3,-0.3 --duration 0.5 # Both down reachy.sh goto --antennas 0.4,-0.4 --duration 0.5 # Asymmetric ``` ### Combined Movements ```bash # Look left and turn body left with antennas up reachy.sh goto --head 0,0.3,0 --body 0.5 --antennas 0.4,0.4 --duration 2.0 ``` ### Interpolation Modes Use `--interp` with goto: - `minjerk` — Smooth, natural (default) - `linear` — Constant speed - `ease` — Ease in/out - `cartoon` — Bouncy, exaggerated ## Emotions & Dances ### Playing Emotions 80+ pre-recorded expressive animations. Select contextually appropriate ones: ```bash reachy.sh play-emotion curious1 # Curious look reachy.sh play-emotion cheerful1 # Happy expression reachy.sh play-emotion surprised1 # Surprise reaction reachy.sh play-emotion thoughtful1 # Thinking pose reachy.sh play-emotion welcoming1 # Greeting gesture reachy.sh play-emotion yes1 # Nodding yes reachy.sh play-emotion no1 # Shaking no ``` ### Playing Dances 19 dance moves, great for fun or celebration: ```bash reachy.sh play-dance groovy_sway_and_roll reachy.sh play-dance chicken_peck reachy.sh play-dance dizzy_spin ``` ### Full Lists Run `reachy.sh emotions` or `reachy.sh dances` to see all available moves. ## Motor Modes Before movement, motors must be `enabled`. Check with `reachy.sh motors`. ```bash reachy.sh motors-enable # Enable (needed for movement commands) reachy.sh motors-disable # Disable (robot goes limp) reachy.sh motors-gravity # Gravity compensation (manually pose the robot) ``` ## Volume Control ```bash reachy.sh volume # Current speaker volume reachy.sh volume-set 50 # Set speaker to 50% reachy.sh volume-test # Play test sound reachy.sh mic-volume # Microphone level reachy.sh mic-volume-set 80 # Set microphone to 80% ``` ## App Management Reachy Mini runs HuggingFace Space apps. Manage them via: ```bash reachy.sh apps # List all available apps reachy.sh apps-installed # Installed apps only reachy.sh app-status # What's running now reachy.sh app-start NAME # Start an app reachy.sh app-stop # Stop current app ``` **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. ```bash reachy.sh snap # Save to /tmp/reachy_snap.jpg reachy.sh snap /path/to/output.jpg # Custom output path ``` **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 ```bash reachy.sh doa # Direction of Arrival from mic array ``` Returns angle in radians (0=left, π/2=front, π=right) and speech detection boolean. ## Contextual Reactions (Clawdbot Integration) Use `reachy-react.sh` to trigger contextual robot behaviors from heartbeats, cron jobs, or session responses. ``` ~/clawd/skills/reachy-mini/scripts/reachy-react.sh ``` ### Reactions ```bash reachy-react.sh ack # Nod acknowledgment (received a request) reachy-react.sh success # Cheerful emotion (task done) reachy-react.sh alert # Surprised + antennas up (urgent email, alert) reachy-react.sh remind # Welcoming/curious (meeting reminder, to-do) reachy-react.sh idle # Subtle animation (heartbeat presence) reachy-react.sh morning # Wake up + greeting (morning briefing) reachy-react.sh goodnight # Sleepy emotion + sleep (night mode) reachy-react.sh patrol # Camera snapshot, prints image path reachy-react.sh doa-track # Turn head toward detected sound source reachy-react.sh celebrate # Random dance (fun moments) ``` 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 | Trigger | Reaction | Notes | |---------|----------|-------| | Morning briefing cron (6:30 AM) | `morning` | Robot wakes up and greets | | Goodnight cron (10:00 PM) | `goodnight` | Robot plays sleepy emotion, goes to sleep | | Heartbeat (periodic) | `idle` | Subtle head tilt, antenna wave, or look-around | | Heartbeat (~1 in 4) | `doa-track` | Checks for nearby speech, turns toward it | | Heartbeat (~1 in 6) | `patrol` | Camera snapshot for room awareness | | Important unread email | `alert` | Antennas up + surprised emotion | | Meeting <2h away | `remind` | Welcoming/curious emotion | | Request from Alexander | `ack` | Quick head nod | | Task completed | `success` | Random cheerful/happy emotion | | Good news or celebration | `celebrate` | Random dance move | ### 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: ```bash # Via raw command reachy.sh raw GET /api/state/full reachy.sh raw POST /api/move/goto '{"duration":1.0,"head_pose":{"pitch":0.2,"yaw":0,"roll":0}}' # Via curl directly curl -s http://192.168.8.17:8000/api/state/full | jq curl -s -X POST -H "Content-Type: application/json" \ -d '{"duration":1.5,"head_pose":{"pitch":0,"yaw":0.3,"roll":0}}' \ http://192.168.8.17:8000/api/move/goto ``` ## Reference For the complete API endpoint list, schemas (GotoModelRequest, FullBodyTarget, XYZRPYPose), and full emotion/dance catalogs, see [references/api-reference.md](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.