命令与资料速查
最后更新
这一栏放的是查阅型内容——不需要从头读，需要时直接跳到对应条目。
三套工具，先搞清楚该用哪个
这是新手最容易搞混的地方：Microduck 有三个命令行工具，跑在不同的地方，解决不同的问题。
| 工具 | 跑在哪 | 什么时候用 |
|---|---|---|
robotctl |
机器人上 | 日常一切：诊断、配置、驱动、更新。发布版里就有它。 |
duckctl |
你的笔记本上 | 机器人没有网络、或你不想 ssh 时。走蓝牙 LE。 |
scripts/dev-push.sh |
你的笔记本上 | 改了机器人的代码，想跳过 CI 直接装上去。 |
三条判断规则：
- 能 ssh 上机器人 → 用
robotctl。 - 机器人从没连过 wifi → 只能用
duckctl（wifi connect走无线电，不需要网络）。这是先有鸡还是先有蛋问题的唯一解。 - 不要在机器人上装
duckctl—— 发布版里没有任何东西依赖它。
按问题找命令
| 你想干什么 | 去哪 |
|---|---|
| 查状态、配置、驱动、更新机器人 | robotctl 命令速查 |
| 给一台没联网的机器人配 wifi | duckctl |
| 看懂七个守护进程谁管什么 | 系统架构 |
| 找官方一手资料 | 官方资料入口 |
| 查一个英文术语的中文意思 | 中英术语对照 |
| 把本机构建装到板子上 | 本机构建装上板子 |
| dev 通道、候选版、更新后重启陷阱 | 开发板速查 |
一条通用规则：权限
- 只读命令不需要任何权限。
- 任何改变机器人状态的操作都需要
sudo，或者在configd的--allow-user/--allow-group、updater.toml的allow_uids/allow_gids名单里。
出问题时的固定三步
不管什么症状，这三条命令都值得先跑：
robotctl version # 跑的版本和装的版本是否一致
robotctl health # 有没有 unhealthy，原因是什么
robotctl monitor # 请求 vs 实际，并说明为什么被钳制version 排第一的原因：更新后守护进程仍跑旧代码，和“修复没生效”的表现完全一样。
如果这块板子是开发板，还有一条容易忽略的：robotctl health 的 units 块会逐个列出每个守护进程是从哪个发布版启动的，并在与已安装版本不一致时点名警告。详见开发板速查里的重启陷阱。
本栏目录
- Microduck 官方资料入口
Pollen Robotics 官方仓库、文档、产品页与媒体资料的集中入口，按"要解决什么问题"分组。
- robotctl version
对比各守护进程正在运行的版本与已安装的版本，不一致时告警。
- sim2real 是什么，为什么它是最难的一步
sim2real 指把仿真里训练的策略迁移到真机。仿真里走得好、上机就摔，是这类项目最常见的失败。
- 中英术语对照
Microduck 文档与命令输出里的英文术语对照，含每个词在这个项目里的具体含义。
- BAM 执行器模型
Rhoban 的舵机物理模型。把舵机当理想力矩源，是 sim2real 失败最常见的根因。
- robotctl health
硬件与软件健康状况合并成一份报告，异常时以非零码退出。
- robotctl 命令速查
Microduck 机上命令行工具 robotctl 的全部命令，按用途分组，含权限要求。
- Microduck 系统架构
七个守护进程各自负责什么、为什么这样切分，以及它们之间怎么通信。
- robotctl monitor
实时对比客户端请求值与实际执行值，并说明两者不同的原因。
- 域随机化
训练时随机化物理参数，让策略对真实世界的参数分布鲁棒。它和加观测噪声是两回事。
- duckctl：从笔记本控制机器人，不需要网络和 ssh
通过蓝牙 LE 找到机器人、配 wifi、开控制台、装更新——机器人从没连过网也能用。
- sudo robotctl configure
robotd.toml 的交互式编辑器，保存前经守护进程自己的加载器校验。
- 齿隙建模，以及编码器在哪一侧
齿轮传动的空程。Microduck 建模为每个舵机 ±1°，关键在于编码器装在齿隙的输出侧。
- 61 维观测契约
所有策略共享同一份观测格式，这是运行时能在行走、恢复、特技之间热切换的前提。
- sudo robotctl robot init
给关节上电并在约两秒内移动到 home 位姿。
- 本机构建，一分钟装上板子
跳过 push 和 CI，从克隆直接交叉编译、签名、经 ssh 装到机器人上。
- deadman：为什么没有停止键
一段时间没收到新指令就把速度归零。手柄进程挂掉时机器人停下靠的就是它。
- sudo robotctl robot relax
切断关节电力。没有支撑时机器人会直接瘫倒。
- 开发板速查
只在开发板上有意义的命令，以及更新之后最容易咬人的那些重启陷阱。
- golden：开机恢复网的兜底版本
golden 是始终保持稳定的兜底发布版。分支构建永远不会成为 golden。
- robotctl pad status
分两行报告手柄连接状态与 padd 驱动状态。
- sudo robotctl pad pair
扫描处于配对模式的手柄并完成绑定，一台手柄只需一次。
- 控制平面与数据平面
所有守护进程共用一套 JSON-RPC 控制契约，但传感器数据不走它。
- sudo robotctl pad forget
删除机器人一侧的手柄绑定关系。
- 投影重力：机器人怎么知道自己倒了
数据流上唯一的 IMU 量。站立时约为 [0, 0, -1]，跌倒判定由它得出。
- robotctl quack
让机器人发出叫声。区分两台鸭子最可靠的方法。
- 策略热切换
运行时在行走、恢复、特技策略之间即时切换，不重启不停机。
- robotctl chorale
多台鸭子协同演唱四声部。默认关闭。
- 健康门禁与自动回滚
每次更新后都做健康检查，不通过就自动退回。这是机器人不会被更新变砖的原因。
- robotctl net status
报告当前 SSID、信号强度与地址。
- 音色库：每台鸭子的声音都不一样
音色由 SoC 序列号生成，所以声音可以用来确认你连的是哪一台。
- robotctl net scan
让机器人扫描周围的无线网络。
- sudo robotctl net connect
让机器人加入一个无线网络。
- sudo robotctl net forget
删除一个已保存的无线网络。
- robotctl system info
报告机器人的名字、序列号与运行时长。
- robotctl system pin
显示这台机器人的配对 PIN。
- sudo robotctl system set-name
给机器人改名，以及什么时候必须改——序列号留空的板子会重名。
- sudo robotctl system set-pin
设置六位配对 PIN。
- sudo robotctl system reboot
重启机器人——以及为什么大多数“重启试试”的场景都有更精确的做法。
- robotctl update status
报告当前版本、可用更新与更新系统状态。
- robotctl update check
查询有没有可用的新版本，不安装。
- sudo robotctl update apply
安装更新。每一次都经签名校验、健康门禁和自动回滚。
- sudo robotctl update rollback
主动退回上一个版本。
- robotctl update log
列出更新历史——机器人可能已经自己回滚过，而只有这里会记。
- robotctl update show
查看某一次更新的详细信息。
- robotctl update watch
实时跟随一次正在进行的更新。
- sudo robotctl update select
切换到一个已下载的版本，不重新下载。
- sudo robotctl update pin
把机器人固定在某个版本，或取消固定。
- sudo robotctl update reset-to-golden
回到 golden 版本——开机恢复网的兜底。