ROS2 接口开发

1.1 文档适用范围与 ROS 版本

本文档适用于 EngineAI PM01 系列与 T800 系列人形机器人的 ROS2 二次开发，基于 ROS2 Humble 版本编写。

文档将原有的《ROS2 协议说明》与各示例文档内容统筹合并，按接口特性分章节阐述，开发者可按章节顺序逐步上手，也可按需跳转查阅。

1.2 开发环境搭建

EngineAI ROS2 Interface 提供一组 ROS2 消息，受益于 ROS2 生态，用户只需要一个标准 ROS2 开发环境加一些配置就能调用 EngineAI 提供的机器人服务。ROS2 仓库地址：engineai_ros2_workspace。

开发者可以通过以下两种方式搭建开发环境。

2.1 方法一：使用机器人内置开发环境（推荐）

EngineAI 在机器人应用计算单元上内置了一个 Web 集成开发环境，用户不需要配置任何环境，只需要 Web 访问服务就可以开始运行示例并开发。

连接机器人内置 WIFI（密码 e12345678），通过浏览器访问机载 Web IDE（地址通常为 http://192.168.0.162，详见机器人机身标签或产品手册）即可开始使用。

2.2 方法二：自行搭建 PC 开发环境

系统环境要求：

安装软件依赖：

sudo apt update
sudo apt install rsync sshpass openssh-client libglfw3-dev libxinerama-dev libxcursor-dev
sudo apt install ros-dev-tools ros-humble-rmw-cyclonedds-cpp ros-humble-ros-base

ROS2 通信配置：

必须正确配置以下环境变量，否则无法与机器人通信：

# 一定要匹配的 ROS_DOMAIN_ID
export ROS_DOMAIN_ID=69
# 设置多机通信
export ROS_LOCALHOST_ONLY=0
# 使用 rmw_cyclonedds_cpp
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp

可通过以下脚本一键写入 ~/.bashrc：

echo -e '\nexport ROS_DOMAIN_ID=69\nexport ROS_LOCALHOST_ONLY=0\nexport RMW_IMPLEMENTATION=rmw_cyclonedds_cpp' >> ~/.bashrc && source ~/.bashrc

2.3 访问机器人

克隆仓库：环境准备好后，可直接 clone ROS2 仓库并进入工作空间：

git clone https://github.com/engineai-robotics/engineai_ros2_workspace.git
cd engineai_ros2_workspace

硬件连接：通过机器人背后的网口连接机器人，即可通过 ROS2 多机和机器人通信。

手柄遥控提示：PM01 机身有两个 USB 插槽，手柄的 USB 接收器需插入下方接口才能正常遥控，插上方接口无效。

SSH 登录信息：机器人内置了两款计算单元，用户可通过 SSH 登录访问：

开发前确认事项：

• ROS2 Humble 环境可用，ros2 topic list 能正常列出系统话题
• engineai_ros2_workspace 已编译，interface_protocol 和 interface_example 包可被找到
• 机器人硬件接口节点已启动（可通过 ros2 topic echo /hardware/joint_state 验证）

2.4 构建与部署

安装第三方依赖：在编译节点或仿真环境前，请先运行仓库提供的第三方依赖安装脚本，否则部分消息包/示例可能缺少依赖。

# 在 engineai_ros2_workspace 根目录执行
./src/third_party/install.sh

编译 workspace（来自 ROS2 仓库）：

# 在主机上编译全部节点和示例
./scripts/build_nodes.sh example

# 编译仿真环境
./scripts/build_nodes.sh sim

# 在机器人端编译（先装第三方依赖 → 编译 → 配置环境）
./src/third_party/install.sh
./scripts/build_nodes.sh
source install/setup.bash

同步代码到机器人 Orin 主板：

./scripts/sync_src.sh orin

同步后 SSH 登录 Orin 主板，进入 workspace 目录编译即可使用，用法与主机一致。

2.5 仿真器（无需实体机器人，建议先在仿真验证后再上真机）

ROS2 仓库提供了 MuJoCo 仿真器，可以在没有实体机器人的情况下调试关节桥接模式：

# 安装第三方依赖
./src/third_party/install.sh

# 编译仿真节点
./scripts/build_nodes.sh sim
source install/setup.bash

# 启动仿真器
ros2 launch mujoco_simulator mujoco_simulator.launch.py

仿真器启动后，按手柄 [BACK, A] 进入关节透传（joint_bridge）模式，再运行示例程序。

使用仿真器时，不要连接实体机器人，或将 ROS_LOCALHOST_ONLY=1 设置为仅本地通信，防止误连实体机器人。

1.3 消息文件位置

所有自定义 ROS2 消息定义位于 interface_protocol 包中，目录结构如下：

src/interface_protocol/msg/（共 19 个，核心 9 个如下）
├── BodyVelCmd.msg
├── JointCommand.msg
├── JointMotionPlanRequest.msg
├── JointMotionPlanState.msg
├── JointOverrideCommand.msg
├── JointState.msg
├── LedControl.msg
├── MotionState.msg
└── MotionStateRequest.msg

核心消息定义源码（点击文件名可跳转 GitHub）：BodyVelCmd.msg · JointCommand.msg · JointMotionPlanRequest.msg · JointMotionPlanState.msg · JointOverrideCommand.msg · JointState.msg · LedControl.msg · MotionState.msg · MotionStateRequest.msg

其余传感器/调试消息（Alert、GamepadKeys、Heartbeat、ImuInfo、MotorCommand、MotorDebug、MotorState、ParallelParserType、PowerInfo、Tts）完整定义见 GitHub 消息目录。开发时可在代码中通过 from interface_protocol.msg import XxxMsg 引入所需消息类型。

1.4 通用约定

以下约定适用于所有接口，在各章节中不再重复说明：

1.5 接口总览

下表汇总了所有 ROS2 接口的 topic、消息类型和方向，方便快速定位：

1.6 QoS 配置参考

不同接口的 QoS 配置要求不同，配置不匹配会导致消息接收失败。下表汇总了各接口的 QoS 要求，信息来自 GitHub 示例脚本中的 QoSProfile 定义：

运动状态切换的发布者必须使用 RELIABLE，而订阅运动状态使用 BEST_EFFORT。如果 QoS 不匹配，消息将无法接收。

1.7 机型规格对比

下表对比了三款机型的关键规格差异，信息来自飞书 wiki「关于PM01」「关于T800（开发版）」「关于T800（Pro版）」页面：

1.8 关节索引对照表

关节索引从 0 开始，命名格式为 J[序号]_[部位]_[动作]_[左右]。控制接口（如 joint_indices、YAML 配置）中使用的索引为关节命名中的 J 编号，即 ROS 关节索引。下表中的「序号」列为原文档/硬件编号，可能与 J 编号不一致，使用时请以关节命名中的 J 编号为准。以下为 PM01 的完整关节索引表，来自飞书 wiki「关于PM01」页面。以下依次为 PM01、T800 开发版、T800 Pro 的完整关节索引表。

8.1 PM01 关节索引（24 自由度）

T800 开发版（25 自由度）关节索引

T800 Pro（43 自由度，含灵巧手）关节索引