如何用ZMQ把任意运动流送入人形机器人？GR00T-WholeBodyControl ZMQ协议完全参考

如何用ZMQ把任意运动流送入人形机器人GR00T-WholeBodyControl ZMQ协议完全参考【免费下载链接】GR00T-WholeBodyControlWelcome to GR00T Whole-Body Control (WBC)! This is a unified platform for developing and deploying advanced humanoid controllers. This includes: Decoupled WBC models used in NVIDIA Isaac-Gr00t, Gr00t N1.5 and N1.6 and GEAR-SONIC项目地址: https://gitcode.com/gh_mirrors/gr/GR00T-WholeBodyControlGR00T-WholeBodyControlGR00T WBC是 NVIDIA 开源的人形机器人全身控制统一平台内置了 ZMQ 流式运动接口任何能按协议发出运动帧的外部程序——动捕管线、VR 遥操作、运动生成模型、仿真桥接——都能通过一条 ZMQ 消息流实时驱动 G1 人形机器人做出跟踪动作。本文将带你完整掌握 ZMQ 运动流的线格式、四种协议版本、三个话题与常见报错排查让你快速把任意运动流接入人形机器人全身控制系统。1. ZMQ 流式接口是什么一条消息流喂动整台机器人GR00T WBC 的部署端C 推理进程支持多种输入方式其中--input-type zmq与--input-type zmq_manager专为外部运动流设计zmq模式订阅pose话题策略实时跟踪到达的运动帧——最简单的你发什么动作机器人就跟什么动作zmq_manager模式额外订阅command启停/模式切换与planner运动规划指令话题适合带步行规划器的 VR 全身遥操作。部署端通过 SUB 套接字连接到发布端默认localhost:5556机器人侧的控制管线如下图所示输入接口接收 ZMQ 运动流经运动管理器交给策略网络最终输出到机器人本体。 关键点协议是自描述的——发布端不需要任何机器人硬件也不需要和部署端约定死结构写一个按格式发消息的脚本就能驱动机器人。2. 消息线格式话题前缀 1280 字节 JSON 头 二进制载荷每条 ZMQ 消息是单段single-part消息结构如下[ topic 前缀如 pose ][ 1280 字节 JSON 头空字节补齐 ][ 按头中顺序拼接的二进制字段 ]JSON 头描述载荷的版本号、字节序、帧数、字段名/类型/形状例如{ v: 1, endian: le, count: 100, fields: [ { name: joint_pos, dtype: f32, shape: [100, 29] }, { name: body_quat, dtype: f64, shape: [100, 1, 4] } ] }自描述接收端不依赖任何带外 schema读头即可还原数组小端le字节序跨大端机器发送时头中标be即可自动换字节序单段消息天然适配 ZMQ 的CONFLATE选项——只保留最新一帧丢弃过期帧保证低延迟。消息打包的 Python 实现可以直接参考 zmq_planner_sender.pyC 接收端解析逻辑在 zmq_packed_message_subscriber.hpp文件头注释就是官方线格式文档。3. 四种协议版本v1 关节 / v2 SMPL / v3 联合 / v4 Token协议版本号写在头的v字段中决定部署端的编码模式协议编码模式必需字段适用场景v10关节joint_pos [N,29]、joint_vel [N,29]有直接 qpos/qvel 来源仿真、动捕重定向v22SMPLsmpl_joints [N,24,3]、smpl_pose [N,21,3]自定义应用仅输出 SMPL 表示v32SMPLv1 四个关节字段 v2 两个 SMPL 字段SONIC 全身遥操作主力PICO VR 即用它v4绕过编码器token_state [D]直接发送预编码的运动 token生成模型输出所有版本都要求两个公共字段body_quat [N,4]w,x,y,z 四元数与frame_index [N]单调递增帧号。几个容易踩的坑v3 中只有 6 个腕关节需要真实值IsaacLab 顺序下索引[23..28]其余 23 个关节填 0 即可v4 不携带运动帧token 直接注入策略的token_state观察位模型必须有编码器配置才生效⚠️会话中途更换协议版本会被拒绝出现Protocol version changed from X to Y during active ZMQ session!时接口会自动退回参考动作模式保平安。4. 可选字段与三个 ZMQ 话题任何协议版本都可以附带这些可选字段字段形状作用left_hand_joints/right_hand_joints[7]7 自由度 Dex3 灵巧手关节角vr_position/vr_orientation[9]/[12]VR 三点左腕、右腕、头位置与朝向catch_up标量检测到大幅帧跳变时是否重置播放默认 trueheading_increment标量每条消息的航向增量调整zmq_manager模式下发布端在同一host:port上发三个话题实现见 zmq_manager.hppcommandstart/stop/planner三个 u8 标志可选delta_headingf32控制启停与模式切换planner逐帧步态指令mode、movement [3]、facing [3]、speed、height1 秒内无消息会自动回 IDLEpose运动帧见上节协议。5. 最快上手5 分钟跑通 ZMQ 流式跟踪假设你已完成快速入门、sim2sim 回路可运行只需两条命令# 终端 1MuJoCo 仿真仓库根目录 python gear_sonic/scripts/run_sim_loop.py # 终端 2C 部署gear_sonic_deploy/ bash deploy.sh --input-type zmq --zmq-host localhost --zmq-port 5556 --zmq-topic pose sim操作步骤按]启动控制系统此时处于参考动作模式T播放、P/N切换按ENTER切到ZMQ 流式模式终端打印ZMQ STREAMING MODE: ENABLED策略开始实时跟踪你发布端发来的运动帧再按ENTER切回参考动作Q/E调整航向I重置基准四元数 任何时候按O紧急停止并退出——真机测试时请始终把手放在 O 键上。参数一览--zmq-host默认localhost、--zmq-port默认5556、--zmq-topic默认pose、--zmq-conflate只保留最新帧丢弃过期帧适合实时性要求高的场景。6. PICO VR 全身遥操作即插即用的运动流来源不想自己写发布端PICO VR 遥操作流就是官方现成的运动流生产器头戴设备 控制器做全身动捕把 SMPL 姿态经 ZMQ 发给部署端机器人实时镜像你的动作。运行第三个终端启动 PICO 流式服务带可视化便于首次调试python gear_sonic/scripts/pico_manager_thread_server.py --manager --vis_smpl --vis_vr3pt在 PICO 内确认全身追踪处于工作状态站成校准姿态后按ABXY初始化身体追踪再按AX开始发布姿态部署端按ENTER开启流式跟踪移动身体——机器人即实时跟随触发扳机可开合对应手注意 ⚠️暂停后先回到机器人当前姿态附近再恢复否则机器人会猛扑向你的位置。PICO 硬件配置细节可参考 vr_teleop_setup.mdVR 全身遥操作完整流程见 vr_wholebody_teleop.md。7. 常见报错与排查清单报错信息原因与解法Version 1 missing required fields (joint_pos, joint_vel)v1 消息缺字段检查字段名拼写Frame count mismatch between joint_pos and joint_vel各字段N维不一致对齐批量帧数Version 4 missing required field token_statev4 消息未携带 token或模型无编码器encode_mode -2导致 token 无效Protocol version changed ... during active ZMQ session!会话中途换了协议版本固定版本后重连Packed frame too small载荷不足 1280 字节头检查 JSON 头是否写满并空字节补齐画面顿挫或追不上开启--zmq-conflate只处理最新帧发布端侧的非阻塞订阅示例CONFLATE 模式见 zmq_poller.py机器人状态回传g1_debug话题msgpack 编码见 zmq_state_subscriber.py。8. 延伸阅读官方 ZMQ 流式教程含全部协议细节docs/source/tutorials/zmq.md消息打包工具pack_pose_message/build_command_message/build_planner_messagegear_sonic/utils/teleop/zmq/C 部署端输入接口ZMQ 端点与管理器gear_sonic_deploy/src/g1/g1_deploy_onnx_ref/include/input_interface/部署脚本gear_sonic_deploy/deploy.sh参考动作库T键播放的预置动作gear_sonic_deploy/reference/example/一句话总结抓住话题前缀 1280 字节自描述 JSON 头 小端二进制载荷这条线格式选对 v1–v4 协议你就能用任何语言、任何运动源把实时运动流稳定地送进 GR00T 人形机器人的全身控制大脑。【免费下载链接】GR00T-WholeBodyControlWelcome to GR00T Whole-Body Control (WBC)! This is a unified platform for developing and deploying advanced humanoid controllers. This includes: Decoupled WBC models used in NVIDIA Isaac-Gr00t, Gr00t N1.5 and N1.6 and GEAR-SONIC项目地址: https://gitcode.com/gh_mirrors/gr/GR00T-WholeBodyControl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考