Reachy Mini 机器人控制

快速开始

使用 CLI 脚本或 curl 控制机器人。脚本路径为：

~/clawd/skills/reachy-mini/scripts/reachy.sh

通过环境变量 REACHY_HOST 或命令行参数 --host 设置机器人 IP 地址。默认值：192.168.8.17。

常用命令

reachy.sh status                    # 守护进程状态、版本号、IP 地址
reachy.sh state                     # 完整机器人状态
reachy.sh wake-up                   # 唤醒机器人
reachy.sh sleep                     # 进入休眠状态
reachy.sh snap                      # 拍摄相机快照 → /tmp/reachy_snap.jpg
reachy.sh snap /path/to/photo.jpg   # 将快照保存至自定义路径
reachy.sh play-emotion cheerful1    # 播放一种情绪动画
reachy.sh play-dance groovy_sway_and_roll  # 播放一支舞蹈
reachy.sh goto --head 0.2,0,0 --duration 1.5  # 点头（俯仰角下倾）
reachy.sh volume-set 70             # 设置扬声器音量
reachy.sh emotions                  # 列出所有可用情绪动画
reachy.sh dances                    # 列出所有可用舞蹈动作

运行环境

运动控制指南

头部控制（6 自由度）

头部接受以弧度为单位的俯仰角（pitch）、偏航角（yaw）、翻滚角（roll）：

• 俯仰角（抬头/低头）：-0.5（抬头）至 0.5（低头）
• 偏航角（向左/向右看）：-0.8（向右）至 0.8（向左）
• 翻滚角（侧向倾斜）：-0.5 至 0.5

# 抬头
reachy.sh goto --head -0.3,0,0 --duration 1.0

# 向左看
reachy.sh goto --head 0,0.4,0 --duration 1.0

# 向右倾斜并略微抬头
reachy.sh goto --head -0.1,0,-0.3 --duration 1.5

# 回到中立位
reachy.sh goto --head 0,0,0 --duration 1.0

躯干旋转（360°）

躯干偏航角以弧度表示。0 表示正前方，正值表示向左转，负值表示向右转。

reachy.sh goto --body 1.57 --duration 2.0   # 左转 90°
reachy.sh goto --body -1.57 --duration 2.0  # 右转 90°
reachy.sh goto --body 0 --duration 2.0      # 面向前方

天线控制

两个天线 [左, 右]，单位为弧度，范围约为 -0.5 至 0.5。

reachy.sh goto --antennas 0.4,0.4 --duration 0.5    # 同时上扬
reachy.sh goto --antennas -0.3,-0.3 --duration 0.5   # 同时下压
reachy.sh goto --antennas 0.4,-0.4 --duration 0.5    # 不对称姿态

组合运动

# 向左看 + 躯干左转 + 天线上扬
reachy.sh goto --head 0,0.3,0 --body 0.5 --antennas 0.4,0.4 --duration 2.0

插值模式

在 goto 命令中使用 --interp 参数指定运动插值方式：

• minjerk — 平滑自然（默认）
• linear — 匀速运动
• ease — 缓入缓出
• cartoon — 弹跳夸张效果

情绪动画与舞蹈动作

播放情绪动画

预置 80+ 种富有表现力的动画，可根据上下文选择合适的情绪：

reachy.sh play-emotion curious1       # 好奇表情
reachy.sh play-emotion cheerful1      # 开心表情
reachy.sh play-emotion surprised1     # 惊讶反应
reachy.sh play-emotion thoughtful1    # 思考姿态
reachy.sh play-emotion welcoming1     # 欢迎手势
reachy.sh play-emotion yes1           # 点头表示肯定
reachy.sh play-emotion no1            # 摇头表示否定

播放舞蹈动作

共 19 种舞蹈动作，适合娱乐或庆祝场景：

reachy.sh play-dance groovy_sway_and_roll
reachy.sh play-dance chicken_peck
reachy.sh play-dance dizzy_spin

完整列表

运行 reachy.sh emotions 或 reachy.sh dances 查看全部可用动作。

电机模式

执行运动前，需先将电机设为 enabled 状态。可使用 reachy.sh motors 检查当前状态。

reachy.sh motors-enable     # 启用电机（运动类命令必需）
reachy.sh motors-disable    # 关闭电机（机器人进入松弛状态）
reachy.sh motors-gravity    # 启用重力补偿（可手动调整机器人姿态）

音量控制

reachy.sh volume            # 当前扬声器音量
reachy.sh volume-set 50     # 将扬声器音量设为 50%
reachy.sh volume-test       # 播放测试音效
reachy.sh mic-volume        # 当前麦克风增益
reachy.sh mic-volume-set 80 # 将麦克风增益设为 80%

应用管理

Reachy Mini 运行 HuggingFace Space 应用。可通过以下命令进行管理：

reachy.sh apps              # 列出所有可用应用
reachy.sh apps-installed    # 仅列出已安装的应用
reachy.sh app-status        # 查看当前正在运行的应用
reachy.sh app-start NAME    # 启动指定应用
reachy.sh app-stop          # 停止当前运行的应用

重要提示：同一时间仅允许一个应用运行。启动新应用会自动停止当前运行的应用。部分应用可能独占机器人控制权 —— 若机器人无响应，请先执行 reachy.sh app-stop，再发送手动运动指令。

相机快照

通过 WebRTC 从机器人相机（IMX708 广角镜头）捕获 JPEG 图片 —— 此操作不会中断正在运行的守护进程。

reachy.sh snap                        # 保存至 /tmp/reachy_snap.jpg
reachy.sh snap /path/to/output.jpg    # 自定义输出路径

前提条件：需具备机器人 SSH 访问权限（依赖 sshpass 工具及 REACHY_SSH_PASS 环境变量，默认值：root）。

工作原理：连接至守护进程的 WebRTC 信令服务器（端口 8443），在机器人端使用 GStreamer 的 webrtcsrc 插件接收视频流，解码一帧 H264 图像，并保存为 JPEG 格式。整个过程无需重启守护进程，也不会干扰电机运行。

注意：机器人必须处于唤醒状态（头部抬起）才能获取有效图像；若处于休眠状态，相机会朝向机身内部。请先运行 reachy.sh wake-up。

音频感知

reachy.sh doa               # 从麦克风阵列获取声源方向（Direction of Arrival）

返回角度（单位：弧度，0=左侧，π/2=正前方，π=右侧）以及语音检测布尔值。

上下文响应（Clawdbot 集成）

使用 reachy-react.sh 脚本，可基于心跳信号、定时任务（cron job）或会话响应触发上下文相关的机器人行为。

~/clawd/skills/reachy-mini/scripts/reachy-react.sh

响应类型

reachy-react.sh ack           # 点头确认（已接收到请求）
reachy-react.sh success       # 开心情绪动画（任务完成）
reachy-react.sh alert         # 惊讶表情 + 天线上扬（紧急邮件、告警）
reachy-react.sh remind        # 欢迎/好奇表情（会议提醒、待办事项）
reachy-react.sh idle          # 微妙动画（心跳存在感）
reachy-react.sh morning       # 唤醒 + 问候（晨间简报）
reachy-react.sh goodnight     # 困倦情绪 + 进入休眠（夜间模式）
reachy-react.sh patrol        # 拍摄相机快照，并打印图片路径
reachy-react.sh doa-track     # 转动头部朝向检测到的声音来源
reachy-react.sh celebrate     # 随机舞蹈（欢乐时刻）

添加 --bg 参数可在后台非阻塞地运行。

内置行为策略

• 静音时段（美东时间 22:00–06:29）：除 morning、goodnight 和 patrol 外，其余响应均被静默跳过。
• 自动唤醒：所有响应逻辑均确保机器人处于唤醒状态后再执行（必要时自动启动守护进程并唤醒）。
• 容错机制：若机器人不可达，响应脚本将干净退出，不抛出错误。

集成触发点

DOA（声源方向）追踪

doa-track 响应利用机器人 4 麦克风阵列检测语音方向，并驱动头部转向说话者。DOA 角度（0=左侧，π/2=正前方，π=右侧）被映射为头部偏航角。仅当检测到活跃语音时才会触发该响应。

相机巡检

patrol 响应会拍摄一张快照并打印图像路径。可在心跳信号中定期调用，实现房间状态检查。结合图像分析，可用于检测活动或环境变化。

直接 API 访问

对于 CLI 未覆盖的功能，可使用 curl 或 raw 命令直接调用 REST API：

# 使用 raw 命令
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}}'

# 直接使用 curl
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

参考文档

完整的 API 接口列表、数据结构定义（如 GotoModelRequest、FullBodyTarget、XYZRPYPose）以及完整的情绪/舞蹈目录，请参阅 references/api-reference.md。

故障排查

• 机器人无动作：检查 reachy.sh motors 输出 —— 必须为 enabled。请运行 reachy.sh motors-enable。
• 无任何响应：检查 reachy.sh status 输出 —— 状态应为 running。若非如此，请运行 reachy.sh reboot-daemon。
• 运动指令被忽略：可能有应用正在独占控制权。请先运行 reachy.sh app-stop。
• 网络不可达：使用 ping $REACHY_HOST 验证机器人 IP 是否可达；检查 reachy.sh wifi-status 网络状态。
• 快照显示黑屏：机器人很可能处于休眠状态（头部下垂）。请先运行 reachy.sh wake-up。
• 快照因 SSH 错误失败：请确认已安装 sshpass，且 REACHY_SSH_PASS 环境变量设置正确。