Rokae xMate ROS2 使用说明

项目	说明
文档名称	Rokae xMate ROS2 使用说明
适用产品	珞石 xMate 系列协作 / 工业机器人（见下文「适配机型」）
适用平台	Ubuntu 22.04 LTS，x86_64
适用发行版	ROS2 Humble
文档版本	V0.0.2(适配v0.0.2ROS2软件包)
发布日期	2026/04/10

文档信息

版本记录

版本	日期	说明
V0.0.2	2026/04/10	基于原 `rokae ros2使用手册.md` 全文重排：章节结构、目录、表格与术语统一；添加servej示例代码。

适用范围与读者

本手册说明如何在 ROS2 Humble 环境下获取、编译与运行 Rokae ROS2（rokae_ros2） 软件包，并完成 ros2_control + MoveIt 2 下的仿真与真机联调入门流程。

目标读者：已掌握 ROS2 基本概念（工作空间、节点、话题、服务、launch），希望将珞石 xMate 机械臂接入自有应用的开发人员。

重要声明

本文档随开源 / 交付软件包更新，具体接口与参数以仓库内源码及 package.xml 为准。
涉及 机器人运动、真机网络与安全 的操作，须在具备资质的人员监督下进行。

第 1 章概述

1.1 ROS2 简介

ROS2（Robot Operating System 2）是面向机器人系统的开源中间件套件，在 ROS 1 基础上强化了 实时性、安全性、生命周期管理 与 跨平台构建 能力。与 ROS 1 相比，常见差异包括：

去中心化通信：基于 DDS 的发现与数据传输，弱化对中央 roscore 的依赖。
节点生命周期：标准化 configure / activate / ... 状态机，便于工业现场集成。
构建系统：采用 ament + colcon，替代 catkin 工作流。

1.2 手册目的与范围

目的

本手册提供 Rokae ROS2 软件包的 安装、编译、环境配置 说明，并给出 仿真与真机 下的 MoveIt 2 + ros2_control 入门操作步骤。

范围

当前版本软件包覆盖 xMate 系列下列机型（后续版本可能扩展；用户亦可按相同模式自行适配新型号）：

1.3 当前适配机型

系列	机型标识（`robot_type` 等）
AR	xMateAR5L、xMateAR5R
CR	xMateCR7、xMateCR12、xMateCR18、xMateCR20
ER	xMateER3、xMateER7
Pro	xMatePro3、xMatePro7
SR	xMateSR3、xMateSR4、xMateSR5

第 2 章安装与环境

2.1 硬件与操作系统要求

Rokae ROS2 主要在 Ubuntu 22.04 LTS + ROS2 Humble 上开发与验证；其它发行版或 ROS 版本可能存在不兼容情况。

组件	最低 / 建议配置	备注
CPU	64 位 Intel i5 / i7 或同级 AMD；建议 8 核及以上	1000 Hz 实时模式对算力敏感
内存	8 GB；建议 16 GB	MoveIt 2 与 RViz2 占用较高
磁盘	≥ 20 GB 可用空间	SSD 可显著缩短编译与启动时间
GPU	支持 CUDA 的 NVIDIA GPU（可选）	非必须

2.2 ROS2 与依赖包安装

安装 ROS2 Humble（略，请参考官方安装文档）。
安装本软件包常用依赖（示例）：

sudo apt update
sudo apt install ros-humble-moveit
sudo apt install ros-humble-controller-manager
sudo apt install ros-humble-joint-state-broadcaster
sudo apt install \
  ros-humble-joint-state-publisher \
  ros-humble-forward-command-controller \
  ros-humble-effort-controllers \
  ros-humble-velocity-controllers \
  ros-humble-position-controllers \
  ros-humble-joint-trajectory-controller

若仍有缺失依赖，请按报错信息使用 sudo apt install ros-humble-<package> 补全。

source /opt/ros/humble/setup.bash

参考链接（第三方）：ROS2 一键安装类教程（示例）
https://blog.csdn.net/pixelprodigy/article/details/147933853

ROS2 Control 参考
https://control.ros.org/rolling/doc/getting_started/getting_started.html

2.3 工作空间创建与编译

从珞石获取 最新 Rokae ROS2 源码包，解压至工作空间 src 目录。
编译：

mkdir -p ~/ros2_ws/src
# 将 rokae_ros2 等包复制到 ~/ros2_ws/src
cd ~/ros2_ws
colcon build

配置环境变量（建议写入 ~/.bashrc）：

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/local_setup.sh
source ~/ros2_ws/install/setup.bash

提示：在文件管理器中按 Ctrl + H 可显示隐藏文件 .bashrc。

第 3 章软件包结构

3.1 工作空间顶层目录

doc/                              # 手册与说明
rokae_description/                # URDF / xacro / 网格模型
rokae_hardware/                   # 硬件接口、驱动、launch、控制器配置
rokae_msgs/                       # 自定义消息与服务
rokae_xMateAR5L_moveit_config/    # 各机型 MoveIt 2 配置
rokae_xMateAR5R_moveit_config/
rokae_xMateCR12_moveit_config/
rokae_xMateCR18_moveit_config/
rokae_xMateCR20_moveit_config/
rokae_xMateCR7_moveit_config/
rokae_xMateER3_moveit_config/
rokae_xMateER7_moveit_config/
rokae_xMatePro3_moveit_config/
rokae_xMatePro7_moveit_config/
rokae_xMateSR3_moveit_config/
rokae_xMateSR4_moveit_config/
rokae_xMateSR5_moveit_config/

3.2 `rokae_hardware` 包结构

CMakeLists.txt
config/                 # 控制器 YAML 配置
include/                # 硬件接口头文件
launch/                 # 启动文件
package.xml
rokae_hardware_interface.xml   # ros2_control 插件描述
sdk/                    # 厂商 SDK 头文件与库
src/                    # 实现源码（见下节）

3.3 `rokae_hardware/src` 源文件说明

文件	说明
`connect_test.cpp`	网络性能分析测试（未注册为节点；编译后在 build 目录查找可执行文件）
`movej_client.cpp`	`movej` 客户端示例，与 `rokae_driver`（服务端）配合
`movej_moveit_test.cpp`	基于 MoveIt 规划的 `movej` 示例
`rokae_driver.cpp`	六轴机型：封装部分 xCore 接口为 ROS2 Service
`rokae_driver7.cpp`	七轴机型：同上
`rokae_hardware_interface.cpp`	`ros2_control` SystemInterface 实现，经 `pluginlib` 由 `controller_manager` 加载

第 4 章系统架构与入门

4.1 ROS2 Control 架构

本软件包采用 ROS2 Control 标准架构。典型需要关注的三类文件为：

类别	路径 / 位置	作用
控制器参数	`rokae_hardware/config/*.yaml`	声明 `joint_state_broadcaster`、`joint_trajectory_controller` 等
机器人描述	`rokae_description/urdf/*.xacro`	通过 `<ros2_control>` 声明关节与硬件插件参数
硬件接口插件	`rokae_hardware/src/rokae_hardware_interface.cpp`	调用厂商 SDK，实现 `read` / `write` 等接口

4.2 RViz + MoveIt 2 规划真机

4.2.1 前置条件

已正确安装 MoveIt 2、ros2_control 与本仓库各功能包。
控制器与上位机网络互通，robot_ip、local_ip 配置正确。

4.2.2 启动示例

ros2 launch rokae_hardware rokae_moveit_launch.py \
  robot_type:=SR4 \
  use_fake_hardware:=true \
  robot_ip:=192.168.2.160 \
  local_ip:=192.168.2.1

参数	含义
`robot_type`	机型简写，如 `SR4`、`CR7`、`AR5L`、`AR5R`、`ER7`、`Pro7` 等
`robot_ip`	机器人控制器 IP
`local_ip`	本机连接控制器网卡的 IP
`use_fake_hardware`	`true`：使用 `mock_components/GenericSystem` 仿真；`false`：加载真实硬件插件

建议流程：先在 use_fake_hardware:=true 下验证 MoveIt 与控制器链路，再切换为 false 连接真机或 HMI。
真机连接时，请关注 HMI 中 RCI 相关设置 与 网络丢包率。
说明：旧版手册中出现的「rt」多为笔误或简写，现场请以 HMI 中的 RCI（实时控制接口） 与网络诊断为准。

4.2.3 六轴 / 七轴与 SDK 机器人类型（重要）

部分机型为七轴，需在硬件接口源码中选择与轴数一致的 SDK 机器人类型。涉及文件：

rokae_hardware/src/rokae_hardware_interface.cpp
rokae_hardware/include/rokae_hardware/rokae_hardware_interface.h

示例（以源码注释为准，按现场机型取消注释 / 切换）：

/* rokae_hardware_interface.cpp */
robot_ = std::make_shared<rokae::xMateRobot>(robot_ip_, local_ip_);   // 六轴机型
// robot_ = std::make_shared<rokae::xMateErProRobot>(robot_ip_, local_ip_);  // 七轴机型

/* rokae_hardware_interface.h */
std::shared_ptr<rokae::xMateRobot> robot_;
// std::shared_ptr<rokae::xMateErProRobot> robot_;

4.2.4 RViz 中规划操作要点

黄色模型为目标位姿，白色为当前状态，半透明灰色为起始姿态。
拖动交互标记（末端球体）或使用 MotionPlanning → Joints 修改目标关节角。
点击 Plan & Execute 生成并执行轨迹。
连续多次规划时，建议先再次拖动末端标记，刷新 Joints 面板中的目标值。
速度缩放：MotionPlanning → Planning → Options → VelocityScaling（0–1）。

图 1 HMI 状态监控

图 2 RViz 可视化

MotionPlanning 的 Joints
图 3 通过 MotionPlanning → Joints 修改目标位置

修改目标位置
图 4 RViz 目标姿态与当前姿态

4.3 基于 MoveIt 的 `movej` 示例

在上一节 launch 正常运行前提下，可启动：

ros2 launch rokae_hardware controll_movej.launch.py robot_type:=SR4

源码修改要点（movej_moveit_test.cpp）：

/* 约第 149 行：设置规划参考坐标系（需与对应机型 SRDF 中 base 名称一致） */
arm.setPoseReferenceFrame("AR5-5_07R-W4C4A2_base");  // 其它机型请替换为 xxx_base

/* 约第 158 行：目标关节向量维度须与自由度一致 */
std::vector<double> joint_target = {0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5};

/* 约第 284 行：MoveGroup 名称须与 SRDF 中 `<group name="...">` 一致 */
auto move_group = std::make_shared<moveit::planning_interface::MoveGroupInterface>(node, "AR5R_arm");
// xMate 系列默认规划组名多为 rokae_arm

4.4 常用节点 / 话题 / Action

4.4.1 节点

ros2 node list
ros2 node info /<node_name>

节点	说明
`/controller_manager`	`ros2_control` 控制器管理器
`/joint_state_broadcaster`	将硬件关节状态发布到 `/joint_states`
`/joint_state_publisher`	无真实硬件时辅助发布关节状态
`/move_group`	MoveIt 2 规划核心节点
`/moveit_simple_controller_manager`	MoveIt 与轨迹控制器之间的桥接
`/position_joint_trajectory_controller`	关节轨迹跟踪控制器
`/robot_state_publisher`	根据 URDF 与 `/joint_states` 发布 TF
`/rviz2`	RViz2 可视化

4.4.2 话题

ros2 topic list
ros2 topic info /<topic_name>
ros2 topic echo /<topic_name>

话题	说明
`/joint_states`	全关节状态
`/display_planned_path`	规划路径插值点
`/position_joint_trajectory_controller/controller_state`	控制器状态

4.4.3 Action

ros2 action list
ros2 action info /<action_name>

Action	说明
`/execute_trajectory`	执行已规划轨迹
`/move_action`	MoveIt 规划并执行
`/position_joint_trajectory_controller/follow_joint_trajectory`	轨迹跟踪（与 MoveIt 对接）

4.5 `rokae_driver` 驱动与接口

rokae_driver / rokae_driver7 将部分 xCore API 封装为 ROS2 Service 与 Topic，便于二次开发。

4.5.1 Service 一览

服务定义位于 rokae_msgs/srv。

服务	说明	类型
`/rokae_driver/get_robot_info`	查询型号、SDK 版本等	`GetRobotInfo`
`/rokae_driver/jog_control`	Jog	`JogCon`
`/rokae_driver/drag_control`	拖动示教模式开关	`DragCon`
`/rokae_driver/calculate_fk`	正解	`CalculateFK`
`/rokae_driver/calculate_ik`	逆解	`CalculateIK`
`/rokae_driver/get_di` / `set_di`	数字输入	`GetDI` / `SetDI`
`/rokae_driver/get_do` / `set_do`	数字输出	`GetDO` / `SetDO`
`/rokae_driver/movej`	MoveJ	`MoveJ`
`/rokae_driver/movel`	MoveL	`MoveL`
`/rokae_driver/movec`	MoveC	`MoveC`
`/rokae_driver/read_register` / `write_register`	寄存器读写	`ReadRegister` / `WriteRegister`

七轴版本可执行文件为 rokae_driver7，对应服务命名空间一般为 /rokae_driver7/...（以 launch 为准）。

4.5.2 Topic 一览

话题	说明	类型
`/rokae_driver/joint_states`	关节角状态	`sensor_msgs/msg/JointState`
`/rokae_driver/cartesian_pose`	笛卡尔位姿（实现中读取法兰系）	`geometry_msgs/msg/PoseStamped`

4.5.3 启动命令

ros2 run rokae_hardware rokae_driver --ros-args \
  -p robot_ip:=192.168.2.160 -p local_ip:=192.168.2.100

ros2 launch rokae_hardware rokae_driver.launch.py \
  robot_ip:=192.168.2.160 local_ip:=192.168.2.100

二者择一即可，注意替换为实际 IP。

示例：查询机器人信息

ros2 service call /rokae_driver/get_robot_info rokae_msgs/srv/GetRobotInfo

第 5 章扩展与定制

5.1 适配新机型

在 rokae_description 中新增 URDF / xacro、网格、碰撞模型，可参考现有机型目录结构。
修改 rokae_description/urdf/xMate.urdf.xacro 与 xMate_macro.xacro，为新机型增加分支与宏调用；并编写对应的 *.ros2_control.xacro。
使用 MoveIt Setup Assistant 生成新型号的 *_moveit_config 包；与现有机型存在差异时，以现有机型包内文件组织方式为基准对齐。

附录 A 术语表

术语	说明
`robot_type`	launch 传入的机型简写，用于选择 URDF、控制器 YAML、MoveIt 配置包名等
`use_fake_hardware`	是否使用仿真用 `GenericSystem` 插件
`flangeInBase`	SDK 坐标类型：法兰相对基坐标系
`endInRef`	SDK 坐标类型：末端（工具 / 工件语义）相对参考系

附录 B 反馈与支持

若文档与代码不一致，请以仓库最新版本为准，并将 ROS2 发行版、Ubuntu 版本、机型、robot_type、完整 launch 命令与终端日志 一并反馈，以便快速定位问题。

文档信息​

版本记录​

适用范围与读者​

重要声明​

目录​

第 1 章 概述​

1.1 ROS2 简介​

1.2 手册目的与范围​

1.3 当前适配机型​

第 2 章 安装与环境​

2.1 硬件与操作系统要求​

2.2 ROS2 与依赖包安装​

2.3 工作空间创建与编译​

第 3 章 软件包结构​

3.1 工作空间顶层目录​

3.2 rokae_hardware 包结构​

3.3 rokae_hardware/src 源文件说明​

第 4 章 系统架构与入门​

4.1 ROS2 Control 架构​

4.2 RViz + MoveIt 2 规划真机​

4.2.1 前置条件​

4.2.2 启动示例​

4.2.3 六轴 / 七轴与 SDK 机器人类型（重要）​

4.2.4 RViz 中规划操作要点​

4.3 基于 MoveIt 的 movej 示例​

4.4 常用节点 / 话题 / Action​

4.4.1 节点​

4.4.2 话题​

4.4.3 Action​

4.5 rokae_driver 驱动与接口​

4.5.1 Service 一览​

4.5.2 Topic 一览​

4.5.3 启动命令​

第 5 章 扩展与定制​

5.1 适配新机型​

附录 A 术语表​

附录 B 反馈与支持​