YouDuck.ai
≡

robotctl 命令速查

最后更新

robotctl 跑在机器人上。这一页按用途分组整理常用命令。

每条命令的单独页面

这一页是分组总览。每条命令的完整说明、输出怎么读、常见误判，各有单独页面：

分类 命令
诊断 version · health · monitor
配置 configure
关节电源 robot init · robot relax
手柄 pad status · pad pair · pad forget
声音 quack · chorale
网络 net status · net scan · net connect · net forget
身份与电源 system info · system pin · system set-name · system set-pin · system reboot
更新 update status · check · apply · rollback · log · show · watch · select · pin · reset-to-golden

权限规则

  • 只读命令不需要任何权限。
  • 任何会改变机器人状态的操作都需要 sudo（或者：configd 的 --allow-user / --allow-group 名单内的用户；updater.toml 里 allow_uids / allow_gids 名单内的用户）。

诊断

robotctl version    # 各守护进程运行版本 vs 已安装版本，不一致时警告
robotctl health     # 硬件+软件健康报告，不健康时非零退出；--json 输出支持包
robotctl monitor    # 实时控制循环：请求值 vs 实际值，并说明差异原因

version 是出问题时的第一条命令。更新后守护进程仍跑旧代码，看起来和“修复没生效”完全一样。

health 非零退出可以直接用来 gate 脚本。电机过热、组件被 pin 住会被报告但不影响退出码。

monitor 的快捷键

键 作用
q 退出
↑ / ↓ 关节列表滚动（窗口不够高时）
u 角度在度和弧度之间切换
t 打开 ToF 矩阵视图
d 开关机器人 3D 姿态视图
[ / ] 或 ← / → 旋转姿态视图
p 打开手柄原始输入流

屏幕上角度显示为度。重定向或管道输出时它改为每个 tick 打印一行，> run.log 和 | grep FALLEN 都能正常工作，且这些数字始终是弧度，与屏幕设置无关。

完整状态用 JSON 输出，一行一个对象：

robotctl monitor --json --hz 50 > run.jsonl

配置

sudo robotctl configure

/etc/robot/robotd.toml 的交互式编辑器。SPACE 切换开关，ENTER 输入值，u 恢复某个键的默认值。黄色（标 •）的是这台机器人偏离默认值的键。

三个值得信任的性质：

  • 它不会和守护进程不一致——schema、默认值、校验逻辑来自 robotd 解析该文件用的同一个 crate，键列表由测试保证完整。
  • 它不会吃掉你的文件——注释、顺序、其它版本遗留的键原样保留，只写入你改动的键。恢复默认值是删除该键而不是写死默认值，所以文件始终是一份「决策清单」而非默认值副本。
  • 它不会写出让 robotd 起不来的文件——每次保存都先经过守护进程自己的加载器校验，原子写入（临时文件 + rename），失败时给出原因。

守护进程只在启动时读一次配置，所以保存后它会提示重启——只重启读了你改动内容的那些：[media] 对应 mediad，其余对应 robotd。

用自己的策略

不需要发布版本就能试一个网络。在 /etc/robot/robotd.toml 里指向板子上自己的 .onnx：

[policy]
walk = "/home/radxa/my_walking.onnx"
stand = "/home/radxa/my_stand.onnx"
sudo systemctl restart robotd

你的路径能挺过更新——发布版替换的是它自带的二进制和策略，不是这个指向别处的文件。删掉这几行就回到发布版自带的策略。

加载失败的策略会报 unhealthy，robotctl health 和 monitor 的底部边框都会说明原因。

关节电源

sudo robotctl robot init          # 上电并在约 2 秒内移动到 home 位姿
sudo robotctl robot relax --yes   # 断电，机器人会瘫倒

init 会移动每一个关节，执行前把机器人放在支架上。

守护进程没运行时，还可以用 robotd 的子命令。它要求守护进程已停止，因为一条 UART 上两个写入者会互相破坏对方的应答：

sudo systemctl stop robotd && sudo /opt/robot/daemon/current/bin/robotd init && sudo systemctl start robotd

跌倒是报告还是门禁

默认情况下跌倒是一个报告（在 monitor 里可见），不是门禁——这与原型机行为一致，所以 init 在机器人跌倒时也能执行。

robotd.toml 里设置了 [safety] fall_limp 或 fall_recover 的板子会启用门禁：跌倒的机器人会松弛，并拒绝 init / enable / 技能动作，直到被扶起来。

手柄

robotctl pad status
sudo robotctl pad pair
sudo robotctl pad pair 78:86:2E:BB:13:28
sudo robotctl pad forget 78:86:2E:BB:13:28

详见配对手柄与手柄按键对照。

声音

robotctl quack

这是区分两台鸭子最可靠的方法。每台机器人的音色库由它的 SoC 序列号生成（每次发布安装时由 sounds ensure-bank 生成），所以应答的那一台——用一个只属于它自己的声音——就是你 SSH 连着的那台。

没有声音的机器人（音频关闭，或没有音色库）会明确说出来而不是打印 🦆，所以沉默永远意味着连错了鸭子。

关掉启动问候（适合整天重启守护进程的人）：sudo robotctl configure 里设 audio.greet = false。这只关掉那一声叫，不影响触发音和麦克风——audio.enabled = false 做不到这种区分。

合唱

robotctl chorale        # 多台鸭子协同演唱，Ctrl-C 停止
robotctl chorale --off  # 停止其中一台

默认关闭（robotd.toml 里的 [chorale] accept），需要在每一台参与的鸭子上分别开启。关闭状态下它是不可见的：没有加入的鸭子不会在空中发出任何信号，而不是礼貌地拒绝。

设计上值得一提的几点：

  • 没有主控。 两台鸭子看到相同的信标，id 较小的那台指挥，所以不存在选举失败，也没有必须送达的消息。
  • 没有共享时钟。 板子没有 NTP 也没有 RTC 一致性，所以指挥的节拍计数器本身就是时基：它在 BLE 广播里每拍递增一个字节，新值的到达就是强拍。跟随者对约 25 拍的相位取平均，把无线电抖动压到合奏需要的 ±20 ms 以内。
  • 声部是算出来的，不是分配的。 最低音的鸭子唱低音部。
  • 加入不改变任何人的声部。 离开的鸭子保留自己的席位，它的声部就此空缺——就像有人中途走出合唱团。

网络

robotctl net status
robotctl net scan
sudo robotctl net connect <ssid> --psk <passphrase>
sudo robotctl net connect <ssid> --psk-stdin
sudo robotctl net forget <ssid>

身份与电源

robotctl system info
robotctl system pin
sudo robotctl system set-name <name>
sudo robotctl system set-pin <six-digits>
sudo robotctl system reboot

更新

robotctl update status
robotctl update check daemon
sudo robotctl update apply daemon
sudo robotctl update rollback daemon
robotctl update log
robotctl update show
robotctl update watch

每一次更新都是经过验证、健康门禁、可回滚的。

不下载直接切换版本：

sudo robotctl update select daemon 0.1.4
sudo robotctl update rollback daemon
sudo robotctl update reset-to-golden daemon
sudo robotctl update pin daemon 0.1.4   # 固定版本
sudo robotctl update pin daemon         # 取消固定

日志

journalctl -u configd -b --no-pager | tail -40
journalctl -u btd -f
journalctl -b -u robotd -u updaterd -u btd -u configd   # updaterd 起不来时
journalctl -b -u robot-boot-check                       # 机器人是否已自动回滚
robotctl update log
robotctl update show 42

相关