Reachy Mini 开源桌面机器人：从组装到第一行 Python 的动手指南

Reachy Mini 开源桌面机器人：从组装到第一行 Python 的动手指南

【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini

Reachy Mini 是 Pollen Robotics 开源的桌面机器人及其 Python SDK（reachy_mini包）。它的卖点很具体：头部是一台斯图尔特平台，6 个 Dynamixel 电机给出 3 旋转 + 3 平移共 6 个自由度，再叠加 1 个身体偏航和 2 根可动天线。读完本文，你会知道这套硬件里装了什么、第一次开机要依次做哪几件事、SDK 和 daemon 怎么分工，以及电机报错时按什么顺序排查。

一、先把盒子拆开：这具身体由哪些部件组成

Reachy Mini 以套件形式出售，官方给出的组装时间是 2 到 3 小时，工具全部随箱附带；官方强烈建议把在线图文指南（每步配短视频）和纸质手册对照着看。

自由度是怎么排布的

运动全部由 Dynamixel 总线电机承担，分工如下：

• 头部：6 × XL330-M288-T，驱动斯图尔特平台的 6 个自由度；
• 底座：1 × XC330-M288-PG，负责身体偏航；
• 天线：2 × XL330-M077-T，各 1 个旋转自由度。

整机尺寸约 30 × 20 × 15.5 cm（伸展状态），质量 1.475 kg，材料为 ABS、PC、铝合金与钢。

传感器与电子系统

感知与输出集成在头部和 PCB 上：

• 4 麦克风 PDM 阵列（基于 Seeed reSpeaker XVF3800，16 kHz 采样），可计算声源方向；
• Raspberry Pi 相机 v3，120° 广角、12MP、自动对焦；
• 5W 扬声器；
• 无线版由 Raspberry Pi CM4（4GB 内存 / 16GB 存储，双频 WiFi）在机运行，电池为 6.4V 2000mAh LiFePO4，输入电压 6.8–7.6V。

二、第一次开机：连接、更新与验证

组装完成后，按官方流程依次做三件事：

1. 配网：给机器人通电，打开 Reachy Mini Control 桌面应用，点底部的 "First time connecting…"。应用会引导你先连到机器人自己的 WiFi AP，再把你的网络参数写进去。
2. 系统更新：连接成功后进入设置页的 System Updates，把机器人软件升到最新版——这一步同时会重刷电机固件，后文排错会用到它。
3. 验证：确认 daemon 在跑。daemon 是整套系统的服务端，常驻在机器人（或 Lite 版所在的电脑、仿真进程）里，负责电机 I/O、安全检查与传感器读取，并在 8000 端口暴露 REST API 和 WebSocket。浏览器打开http://reachy-mini.local:8000/docs（Wireless 版）或http://localhost:8000/docs（Lite / 仿真），看到 API 文档即说明就绪。

三、软件架构：SDK 与 daemon 如何分工

Reachy Mini 采用 Client-Server 架构，这一点决定了你写代码的方式：

• Daemon（服务端）：处理 USB/串口硬件 I/O、安全限位、传感器读取；
• SDK（客户端）：reachy_mini包通过网络连接 daemon。

这个拆分的实际好处是：AI 代码可以跑在你手头的强力电脑上，daemon 只负责在树莓派上贴住硬件，延迟和算力各归各位。ReachyMini()构造函数会自动判断走 localhost 还是网络模式，一般不用手动指定。

三种逆运动学引擎怎么选

src/reachy_mini/kinematics/下提供了三个后端，对应不同的实时性与功能取舍：

• NNKinematics：默认方案，用 ONNX 模型（iknetwork.onnx等）做推理，速度快，适合实时控制；
• PlacoKinematics：基于 Placo 的物理引擎，额外提供重力补偿模式（enable_gravity_compensation()，电机"软"着可以手拨头部），需要安装reachy-mini[placo_kinematics]并以--kinematics-engine Placo启动 daemon，出厂 Wireless 机器人不默认带上；
• AnalyticalKinematics：解析解，行为最可预测，适合教学与调试。

同时 SDK 会按物理限位自动把目标夹取到合法区间：头部俯仰/侧倾 ±40°，头部偏航 ±180°，身体偏航 ±160°，且头身偏航差最大 65°，避免自碰撞。

四、跑通第一个脚本

安装 SDK（pip install reachy-mini，需要 Python ≥ 3.11，官方推荐用uv加速安装）并确认 daemon 在运行后，新建hello.py：

from reachy_mini import ReachyMini from reachy_mini.utils import create_head_pose with ReachyMini() as mini: mini.goto_target( head=create_head_pose(z=10, roll=15, degrees=True, mm=True), duration=1.0, )

goto_target在起点和目标之间做平滑插值，可选linear、minjerk（默认）、ease_in_out、cartoon四种曲线；高频场景（如跟随轨迹）则用绕过插值的set_target。

仓库的 examples/ 目录可以直接照抄，覆盖面包括：head_tracking.py（人脸跟踪）、sound_doa.py（声源定位）、take_picture.py、recorded_moves.py（录制并回放动作）、look_at_image.py等；docs/notebooks/里还有从连接、运动到相机与音频的 Jupyter 教程。想试浏览器端应用可以看ts/下的 JavaScript SDK——网页通过 WebRTC 直接驱动机器人，使用者零安装。

五、电机报错时的排查路径

典型症状：电机闪红灯不动、无报错但不响应、出现 "Overload Error" 或 "Missing motor"。仓库在docs/troubleshooting/motors_diagnosis.md里给了一条完整路径：

1. 先停 daemon：在桌面应用设置里关闭 motor backend，再打开 Testbench 应用点 "Scan Motors"。不关 daemon 就无法扫描。
2. 全部检测到：说明物理连接正常，点 "Check all motors" 核对配置，不匹配时重启 daemon 会自动重刷固件。
3. Overload + 红灯 + 两臂朝上：大概率是电机装错槽位（如 1 号电机插在 2 号位）。拆下电机，把输出臂朝上放，检查臂上的两条刻线是否对齐，不对就松开两颗螺丝重装。
4. 头部动不到最高位：检查头内 USB 线是否留了余量，线太紧会让电机过力，可能烧坏。
5. 单个电机缺失：按组装手册复查该电机的物理连接。
6. 红灯闪且断电后转不动：怀疑硬件损坏，先更新系统软件（会重刷电机）再重启，仍不行则联系支持。

固件文件本身存放在src/reachy_mini/assets/firmware/，刷写脚本在src/reachy_mini/tools/（reflash_motors.py、scan_motors.py），需要手动操作时可以直接用。

接下来你可以做什么

• 按docs/source/platforms/reachy_mini/get_advanced所在目录下的 usage 指南装一个现成 App（对话、收音机、手追）；
• 用examples/imu_example.py读 IMU 数据（仅 Wireless 版有 IMU）；
• 没有硬件的话，reachy-mini-daemon --sim可以在 MuJoCo 里起一台仿真机器人，SDK 代码原样运行。

【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini