先认清 daemon 和 SDK 的分工
动手前先理清结构:官方是 Client-Server 架构。daemon 是服务端,管硬件 IO、安全检查和传感器,把能力以 REST 加 WebSocket 暴露在 8000 端口;Python SDK 是客户端,通过网络发指令。好处是吃算力的 AI 代码可跑在另一台强力服务器,板子只留 daemon 管硬件。Reachy Mini Lite 走 localhost:8000,Reachy Mini Wireless 走 reachy-mini.local:8000。daemon 通常不用手动起,Python SDK 也是官方支持的路径,具体见下表。
把服务起起来并确认 8000 端口通了
按形态选启动方式:
| 形态 | 怎么起 daemon |
|---|---|
| Reachy Mini Wireless | 开机自启,不用敲命令 |
| Reachy Mini Lite | 桌面应用,或 reachy-mini-daemon
|
| 仿真 |
reachy-mini-daemon --sim,macOS 用 mjpython
|
服务起没起用浏览器验:开 http://localhost:8000/docs(Lite)或 http://reachy-mini.local:8000/docs(Wireless),看到 Reachy SDK 的 API 文档页即就绪。常用端点:
| 用途 | 端点 |
|---|---|
| 应用、daemon、状态、动作 |
/api/apps /api/daemon /api/state /api/move
|
| 电机、运动学、音量、HF 认证 |
/api/motors /api/kinematics /api/volume /api/hf-auth
|
| 完整状态 |
GET /api/state/full,WebSocket /api/state/ws/full
|
| 原始接口定义 | http://localhost:8000/openapi.json |
hello.py:让天线摆一次
链路确认后存成 hello.py,官方第一个脚本:
from reachy_mini import ReachyMini
with ReachyMini() as mini:
mini.goto_target(antennas=[0.5, -0.5], duration=0.5)
mini.goto_target(antennas=[-0.5, 0.5], duration=0.5)
mini.goto_target(antennas=[0, 0], duration=0.5)
同目录执行 python hello.py。预期天线先朝一侧摆、再反向摆一次,最后回中位;没动就查 8000 文档页和 Ready 状态。with 会收好连接,别省。
ReachyMini() 构造时自动检测 Lite 或 Wireless,在 localhost 与 network 间切换;仅高级场景显式写 ReachyMini(connection_mode="network")。三种形态脚本代码可一字不改,但连接位置不同:仿真和 Lite 走 localhost,Reachy Mini Wireless 走 network,仿真也没有 XMOS 硬件回声消除,别把代码不改读成三形态完全一样。
动作前先记住限位与坐标系
发目标前记住安全限位,越界 SDK 自动 clamp 到最近合法位置:
| 关节 | 限位 |
|---|---|
| Head Pitch | [-40°, +40°] |
| Head Roll | [-40°, +40°] |
| Head Yaw | [-180°, +180°] |
| Body Yaw | core 表 [-160°, +160°];FAQ [-180°, 180°],两处官方口径并列 |
| Yaw Delta(头身差) | 最大 65° |
Body Yaw 表格里两处官方写法没统一,别挑一个当定论,以运行时 clamp 行为为准。坐标系两套:goto_target 与 set_target 用 Head Frame,look_at_world 用 World Frame,写跟踪逻辑先确认在哪一套。
电机模式与软模式
电机三种状态用方法切换:enable_motors() 硬保持位置,disable_motors() 软瘫可徒手掰动,第三种是重力补偿的软模式。软模式 API 名字官方两处不同,并列:enable_gravity_compensation()(需 Placo 后端,装 reachy-mini[placo_kinematics] 并用 --kinematics-engine Placo,Reachy Mini Wireless 出厂不带)与 make_motors_compliant(),两个名字照各自出处用,不推断是否为别名。
goto_target、set_target 与声源跟踪
goto_target 平滑插值到目标,适合摆姿势;set_target 立即刷新目标,适合实时跟踪循环。头跟着声音转用 start_head_tracking(weight=...),声源方向取 mini.media.get_DoA()。该方法有前置条件:官方示例在 media_backend="default" 下给,构造时别省,否则音频链路没起来,跟踪不生效。
media_backend 四选一
media_backend 决定摄像头和音频归谁管,四个值并列:
| 值 | 行为 |
|---|---|
| default | 自动在 LOCAL 与 WEBRTC 间选 |
| local | 走本地媒体后端 |
| webrtc | H.264 视频加 Opus 音频 |
| no_media | 释放摄像头与音频给 OpenCV、sounddevice 等外部库,退出上下文自动收回 |
选 webrtc 时客户端要装 GStreamer,macOS 和 Windows 的 wheel 自带,Linux 需手动安装。自定义视觉、音频管线或 VAD 加 LLM 加 TTS 这类 AI 集成,用 no_media 腾出设备最省事。