先按目的挑一条路
同一台机器人可以有三种完全不同的驱动方式:写 Python 脚本直连、做浏览器里的 Web 应用、或者用任意语言发 HTTP 请求。三者共用同一个 daemon,区别在客户端跑在哪、要不要拿音视频、以及各自的前置条件,按手头要做的事选一条能跑起来的就行。官方对新应用给出的推荐是走 web、JS 静态页经 WebRTC 驱动这一条。
| 路径 | 形态 | 前置条件 | 适合做什么 |
|---|---|---|---|
| Python SDK | 脚本直连 daemon,装 reachy-mini 包后用 with ReachyMini() as mini
|
本机装好包;要接管媒体时设 media_backend
|
重计算、离线 LAN、常驻无人值守、Home Assistant |
| JS WebRTC | 浏览器静态页经 WebRTC 驱动,官方推荐的新应用路径 | npm 包 @pollen-robotics/reachy-mini-sdk 并 pin 到最新稳定版;客户端装 GStreamer |
新写的 Web、JS 交互应用 |
| REST 加 HTTP | 任意语言 HTTP 客户端直接打 daemon 的 8000 端口 | 能访问 daemon 的 8000 端口,先确认 8000/docs 打得开 |
接 AI 应用、生成任意语言客户端、甚至做自己的 MCP server |
Python SDK 路径:把媒体后端选对
脚本路径最常用的前置是 media_backend,它决定摄像头和音频归谁管,四个取值行为不同:
| 取值 | 行为 | 什么时候用 |
|---|---|---|
default |
自动在 LOCAL 与 WEBRTC 之间选 | 不确定时先用它 |
local |
走本地媒体后端 | 脚本和机器在同一台电脑上 |
webrtc |
H.264 视频加 Opus 音频,经 WebRTC 传输 | 远端或浏览器客户端要拿音视频 |
no_media |
把摄像头和音频释放给 OpenCV、sounddevice 等外部库,退出上下文自动收回 | 自己接管媒体管线 |
选 webrtc 时客户端要装 GStreamer:macOS 和 Windows 随 wheel 自带,Linux 需要手动安装,装不齐最典型的症状是视频流起不来。选 no_media 时 SDK 不碰摄像头和麦克风,可以把它们交给 OpenCV、sounddevice 这类库自己读,退出 with 上下文后资源会自动收回,不用手动还。
动作控制上,goto_target 平滑插值到目标,set_target 立即刷新目标适合实时跟踪,还有 start_head_tracking(weight=...) 做头部跟随、mini.media.get_DoA() 取声源方向。要接 AI 的话,官方 Conversation Demo 是 VAD 加 LLM 加 TTS 的组合;想换成自己的视觉或音频管线,就把 media_backend 设成 no_media,由外部库接管采集。核心概念官方页里只提到 Placo 这一种可选运动学引擎,需要额外装 reachy-mini[placo_kinematics] 并在启动时用 --kinematics-engine Placo 指定;至于把运动学引擎归纳成好几套的说法,冻结的官方页面里没有列全,这里不据此下结论。
JS WebRTC 路径:状态机与建连过程
做浏览器应用,先装 npm 包 @pollen-robotics/reachy-mini-sdk,官方要求 pin 到 npm 的最新稳定版,别用浮动版本。客户端状态机是 disconnected → connected → streaming 三段,autoConnect() 一键把 auth、connect、选机、建立 session、唤醒这几步串完;卡在中间某一状态时,对着这三段看停在哪一段,比整段重跑好定位。
WebRTC 的建连过程是分两段的:
| 阶段 | 路径 | 做什么 |
|---|---|---|
| 信令 | 浏览器到 HF Space 的 SSE、HTTP | 在 HF Space 上校验 HF OAuth token,商量怎么建连 |
| 建连后 | 浏览器到机器人的点对点 | 视频、音频、指令直接点对点传,信令服务器不再在路径上 |
REST 路径:端点与调试入口
REST 由 FastAPI 加 pydantic 实现,官方明确说可以用它生成任意语言客户端、接 AI 应用,甚至做自己的 MCP server。常用端点挂在这些前缀下:
/api/apps/api/daemon/api/state/api/move/api/motors/api/kinematics/api/volume/api/hf-auth
调试时先在浏览器打开 http://localhost:8000/docs 看 Swagger UI,能列出所有接口并直接试请求;要机器可读的描述取 http://localhost:8000/openapi.json 这份原始 OpenAPI。全量状态用 GET /api/state/full,需要持续推送就订阅 WebSocket 的 /api/state/ws/full 路径,例如 ws://localhost/api/state/ws/full。在 Reachy Mini Wireless 上把 localhost 换成 reachy-mini.local。如果 8000/docs 打不开,说明 daemon 没起来或端口没通,先回到起服务那一步,别在客户端里反复改代码。
国内网络与 HF 服务
访问 Hugging Face 服务受限时,官方 FAQ 给的做法是用镜像 https://hf-mirror.com/,并在环境里设 export HF_ENDPOINT=https://hf-mirror.com/。官方同时提示 PyPI 与 GitHub 可能也需要各自配置镜像。这些是 FAQ 里有据的条目,照着配即可;超出这几条的联网方案官方没有给出,这里不自行扩展。