装依赖:把 MuJoCo 仿真带进来
没有机器人也能把整条链路跑通,这一页讲怎么装仿真依赖、起 3D 窗口、选场景,再拿同一份 Python 脚本验证动作。官方的零硬件方案基于 MuJoCo,仿真后端和真机共用 daemon 与 SDK,只有音频和依赖上有几处边界要提前知道。
先按安装页准备 Python 环境,三步是 uv python install 3.12 --default、uv venv reachy_mini_env --python 3.12,然后装带仿真扩展的包。两条命令按你用的工具二选一:
pip install "reachy-mini[mujoco]" uv pip install "reachy-mini[mujoco]"
用 uv 建的环境就跑 uv pip install,用系统 pip 或普通 venv 就跑 pip install,两条别都跑,混用会装进不同解释器,后面 import 不到。装完在 Python 里能 import 到 reachy_mini 就算依赖齐了;报缺 MuJoCo 相关模块,多半是装成了不带 [mujoco] 的纯净包,重装一次即可。装之前先确认自己处在 reachy_mini_env 这个环境里,否则包进了全局、脚本却在 venv 下跑,同样会报找不到模块。
起 3D 窗口并选场景
用仿真模式起 daemon:
reachy-mini-daemon --sim
正常会弹出 3D 窗口,里面是机器人的可交互模型。鼠标左键拖拽旋转视角,右键拖拽平移,滚轮缩放;窗口能转得动,就说明仿真后端活着。这条命令会占住当前终端,别关窗口也别按 Ctrl-C,daemon 一停脚本就断,先让它开着,另开一个终端跑脚本。macOS 上不能直接用上面那条,要改用 mjpython 调起,命令得写全:
mjpython -m reachy_mini.daemon.app.main --sim
场景用 --scene 选,两个值并列:
| 值 | 场景内容 |
|---|---|
| empty | 默认,空场地,只有机器人 |
| minimal | 加一张桌子,桌上放苹果、牛角包和鸭子 |
empty 是默认值,不写 --scene 就是它;reachy-mini-daemon --sim --scene minimal 带出摆了物件的那套,做抓取或避障类演示、看机器人和桌面物件的相对位置时比空场直观。两个场景只改画面里的物件,不改 daemon 和 SDK 的行为,切场景不用动脚本。窗口起不来先确认是不是用了 macOS 却漏了 mjpython,以及 [mujoco] 依赖有没有真的装上。
同一份脚本直接跑
仿真里的行为等同 Reachy Mini Lite 经 USB 连接:daemon 监听 localhost,前面写的 hello.py 这类 Python SDK 脚本一个字都不用改,直接 python hello.py 就能看到 3D 模型里的天线跟着摆动,脚本里不用改主机名、也不用传连接参数,构造 ReachyMini() 时按形态自动选。也正因为走 localhost,浏览器开 http://localhost:8000/docs 同样能看到 API 文档页,验证方式和真机一致;文档页打不开或脚本报连不上,先回头确认 --sim 那个终端还开着、daemon 没被关掉,以及 8000 端口没被别的服务占着。
但别把脚本不用改读成三种形态完全一样。代码不改,连接位置却不同:仿真与 Reachy Mini Lite 走 localhost,Reachy Mini Wireless 走 network 主机名;而且仿真里没有 XMOS 硬件回声消除,这块边界在音频上尤其明显。
音频与运动学引擎的两处边界
因为没有 XMOS 硬件做回声消除,仿真改用 GStreamer 的软件方案:由 webrtcdsp 加 webrtcechoprobe 在系统默认的麦克风与扬声器上完成。做语音交互、发现回声压不干净时,先想到这里是软件处理、且绑在默认设备上,换设备或改默认输入输出都会影响效果,排查时先把系统默认麦和扬声器固定下来再测;默认设备一旦被切换,这套软件处理就落不到实际用的那对设备上,回声又会冒出来。
运动学引擎方面,核心概念官方页只提到 Placo,需要额外安装并在启动时指定引擎。至于常被提到的 NN、Analytical、Placo 三套说法,在本次核到的官方页里没有列全,这里不把它写成既定结论,也不替官方补出未见于页面的细节;真要切换引擎,照核心概念页写明的方式装好 Placo 再指定即可。
macOS 上会踩到的两个坑
第一个是 mjpython 下 libgstpython.dylib 触发段错误,窗口一起就崩或根本起不来。官方仿真上手页给的处置是重命名这个插件来绕开,具体命令照该页原样执行,别自己猜路径。第二个是 macOS 上 uv 与 MuJoCo 的兼容问题,装完一跑就报兼容错误时,官方建议改用 pip 装仿真依赖,也就是回到前面 pip install "reachy-mini[mujoco]" 那条。两个坑都只在 macOS 出现,Linux 与 Windows 按通用命令走即可;在 macOS 上先认准 mjpython 启动、pip 安装这两点,能少走一大半弯路。段错误和兼容报错是两种不同症状,按上面分别对号入座,别把重命名插件当成兼容问题的解法。