robot-console-cli

WorkBuddy「机器人控制台」连接器的 CLI 执行体。通过 DDS 在本地局域网控制人形 / 四足机器人，不经云端。

安装

一条命令，无需 C 编译器、无需访问 GitHub：

python -m pip install robot-console-cli

会自动带上 DDS 绑定 cyclonedds（PyPI 有各平台预编译包）。 Unitree 官方机器人驱动已内嵌在包内（robot_console/_vendor/unitree_sdk2py，BSD-3）， 因此不需要另行安装 SDK。

覆盖平台：macOS（Intel / Apple Silicon）、Linux（x86_64）、Windows（x86_64）。

想接官方仿真器 unitree_mujoco 或低层开发，才需要额外装官方 SDK——本连接器不需要。

命令

所有命令支持 --json 输出。

全局参数

三层通信与 status 输出

status 会分层报告，一眼看出卡在哪一层：

G1-01（G1）：在线，姿态 站立就绪
通信层：dds_lowstate√，rpc√

无真机验证

有两条路，互补覆盖。

路一：纯逻辑验证（--backend mock，零依赖）

robot-console --backend mock bind --auto
robot-console --backend mock pose --robot G1-01 --pose stand
robot-console --backend mock estop --robot G1-01

从源码目录直接跑时，才需要 PYTHONPATH=src（Windows：set PYTHONPATH=src）。

mock 后端的状态只存在于单次进程内，不跨命令持久化；因此每次调用看到的是全新的模拟状态。

路二：本地假机器人（--backend sim，真 DDS，走真机后端代码）

在单机内实现 sport / arm / voice 三个 RPC 服务端 + 遥测发布， 走的是 backends/unitree.py 这份真机后端代码，只差 DDS 域号。

robot-console sim --start --model G1        # 起假机器人（DDS 域 1）
robot-console --backend sim bind --auto
robot-console --backend sim status --robot G1-01
robot-console --backend sim pose --robot G1-01 --pose stand
robot-console --backend sim say  --robot G1-01 --text "大家好"
robot-console --backend sim action --robot G1-01 --name wave
robot-console --backend sim estop --robot G1-01
robot-console verify --contract g1-v1       # 核对实际发出的报文
robot-console sim --stop

故障注入（真机上几乎无法稳定复现）：

robot-console sim --start --fault 7101=7302
robot-console --backend sim pose --robot G1-01 --pose stand
# → 错误：[7302] 无效的 FSM ID

一键全量验证

python tests/offline_e2e.py --model G1
python tests/offline_e2e.py --model GO2

会依次完成：起桩 → 发现绑定 → 三层状态 → 按契约跑全部命令 → 契约核对 → 护栏校验（拦截 / 限速 / 幂等 / 标定）→ 故障注入 → doctor，最后给出通过率。

也支持官方仿真器 unitree_mujoco

同一个 --backend sim 也能连官方仿真器（域 1 + 回环），无需改配置：

cd unitree_mujoco/simulate_python && python3 unitree_mujoco.py
robot-console --backend sim bind --auto      # L1/L2 通过

官方仿真器只仿低层（rt/lowcmd / rt/lowstate），不实现内置高层服务， 因此 pose / say / action 会返回 3104 超时或 3203 未实现——这是预期行为。 高层语义请用上面的本地假机器人验证。

真机注意

• FSM 编号与动作 ID 已逐行对照官方源码定案，见 src/robot_console/constants.py。
• 不同固件的 FSM 编号可能漂移（社区实测 G1 的"站立"出现过 4 与 500）。 现场用 config --set-fsm G1:stand=4 标定即可，不需要改代码。
• 机器人若处于调试模式，内置运控退出，高层接口会失效。
• ChannelFactory 是进程级单例，一个进程只能连一个 DDS 域； 要同时连真机（域 0）与仿真器（域 1），必须拆成两个进程。

目录与安全

• 配置、审计日志默认落在 ~/.robot-console/（可用 ROBOT_CONSOLE_CONFIG_DIR 覆盖）。
• 所有控制指令写入 audit.jsonl，敏感字段自动脱敏。
• 硬约束：duration 0.5–3 s，线速度 ≤0.5 m/s，角速度 ≤0.5 rad/s，越界直接拒绝而非截断。
• 高风险命令（move / action）带幂等键，避免重试造成重复动作。
• 全部通信在本地局域网内完成，不经云端。