Rokae xMate ROS 2 使用说明

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

文档信息

版本记录

版本	日期	说明
V0.0.2	2026/04/10	基于原 `rokae ros2使用手册.md` 全文重排：章节结构、目录、表格与术语统一；添加 servej 示例代码。
V0.1.1	2026/09/07	同步软件包 v0.1.1：扩展适配机型（含工业标准机与 AR 0.8/ZY2/AR3）、PREEMPT_RT 与 FIFO 权限、双臂整机 RViz、Gazebo 仿真与轨迹开发。

适用范围与读者

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

目标读者：已掌握 ROS 2 基本概念，希望将珞石 xMate 机械臂接入自有应用的开发人员。

重要声明

本文档随开源 / 交付软件包更新，具体接口与参数以仓库内源码及 package.xml 为准。
涉及 机器人运动、真机网络与安全 的操作，须在具备资质的人员监督下进行。
更多产品说明与 ROS 2 软件包官方文档，请访问：https://docs.rokae.com/docs/ROS2

第 1 章概述

1.1 ROS 2 简介

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

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

1.2 手册目的与范围

目的

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

范围

当前版本软件包覆盖 xMate 系列协作机型（CR7、CR12、CR18、CR20、CR35、ER3、ER7、Pro3、Pro7、SR3、SR4、SR5、AR5L、AR5R、AR5R08、AR5R08ZY2、AR5L08、AR5L08ZY2、AR3R、AR3L）以及工业标准机型 XB7s、XB7h、NB25s、NB25h、NB12s、NB12h、EB4、NB4、XB4s、XB4h、NB220s；后续会适配更多机型，用户也可按相同模式自行适配新型号。

另在 rokae_description 中提供 Wheel_Robot_PD2613-0.8 双臂整机 URDF，仅用于 RViz2 渲染（不含真机控制、MoveIt、Gazebo）；详见「4.2 双臂整机 RViz 显示」。

1.3 当前适配机型

系列	机型标识（`robot_type` ）
AR	xMateAR5L、xMateAR5R、xMateAR5R08、xMateAR5R08ZY2、xMateAR5L08、xMateAR5L08ZY2、xMateAR3R、xMateAR3L
CR	xMateCR7、xMateCR12、xMateCR18、xMateCR20、xMateCR35
ER	xMateER3、xMateER7
Pro	xMatePro3、xMatePro7
SR	xMateSR3、xMateSR4、xMateSR5
工业标准	xMateXB7s、xMateXB7h、xMateNB25s、xMateNB25h、xMateNB12s、xMateNB12h、xMateEB4、xMateNB4、xMateXB4s、xMateXB4h、xMateNB220s
双臂整机（仅 RViz）	Wheel_Robot_PD2613-0.8

第 2 章安装与环境

2.1 硬件与操作系统要求

Rokae ROS 2 主要在 Ubuntu 22.04 LTS + ROS 2 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 ROS 2 与依赖包安装

安装 ROS 2 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

参考链接：ROS 2 一键安装类教程
https://blog.csdn.net/pixelprodigy/article/details/147933853

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

2.3 工作空间创建与编译

获取 最新 Rokae ROS 2 源码包。可通过 GitHub 仓库访问、浏览与下载：

仓库地址：https://github.com/RokaeRobot/rokae_ros2

打开上述链接后，可在线浏览各 ROS 2 软件包源码，也可通过页面上的 Code → Download ZIP 下载，或使用 git clone 克隆到本地。

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
git clone https://github.com/RokaeRobot/rokae_ros2.git

编译：

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。

2.4 实时内核（PREEMPT_RT）配置

真机控制器配置默认 update_rate: 1000（见 rokae_hardware/config/xMate*_real_controllers.yaml）。本机调度抖动较大时，实际 read/write 周期可能远大于 1 ms，运动时更容易出现异响或不平滑。安装带 PREEMPT_RT 的 realtime 内核，有助于提升本机调度确定性。仅换内核还不够：当前 Ubuntu 用户还需要 FIFO 实时调度权限（rtprio / memlock），ros2_control_node 才可能以 SCHED_FIFO 运行。

作用

使用 Ubuntu 官方 realtime（PREEMPT_RT）内核，降低普通任务对控制线程的干扰
配合本软件包真机 1000 Hz 控制器配置，改善实时指令下发的时间确定性
lowlatency 内核优于普通 generic，但不等于完整 PREEMPT_RT

安装步骤

(1) 安装官方实时内核元包

sudo apt update
sudo apt install ubuntu-realtime
# 或：sudo apt install linux-realtime

若镜像站无法访问，可临时改用 Ubuntu 官方源后再安装：

sudo cp -a /etc/apt/sources.list /etc/apt/sources.list.bak
sudo tee /etc/apt/sources.list >/dev/null <<'EOF'
deb http://archive.ubuntu.com/ubuntu/ jammy main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ jammy-backports main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ jammy-security main restricted universe multiverse
EOF
sudo apt update
sudo apt install ubuntu-realtime

(2) 确认已安装

dpkg -l | grep -E 'linux-image.*realtime|linux-realtime|ubuntu-realtime'
ls /boot/vmlinuz-*realtime*

(3) 重启并选择 realtime 内核

sudo reboot

注意

不要删除原有 lowlatency / generic 内核。

实时核版本可能低于当前 HWE 内核，请确认网卡等驱动可用。

(4) 可选：测控制环时将 CPU 设为性能模式

echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

验证指令与预期效果

内核是否切换成功

uname -a
# 期望：内核名含 realtime，且含 PREEMPT_RT
# 示例：Linux ... 5.15.0-1032-realtime ... PREEMPT_RT ...

cat /sys/kernel/realtime
# 期望输出：1

zgrep CONFIG_PREEMPT_RT /boot/config-$(uname -r)
# 期望：CONFIG_PREEMPT_RT=y

软件包侧确认

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash   # 按实际工作空间路径修改

ros2 launch rokae_hardware rokae_moveit_launch.py \
  robot_type:=SR5 use_fake_hardware:=false \
  robot_ip:=192.168.2.160 local_ip:=192.168.2.129

日志中可确认：

[controller_manager]: update rate is 1000 Hz

现象	说明
`uname` 含 `PREEMPT_RT`，且 `/sys/kernel/realtime` 为 `1`	实时内核已生效
`update rate is 1000 Hz`	控制器按 1000 Hz 配置运行

2.5 给当前用户添加 FIFO 权限

实时内核解决的是「内核能不能及时抢占」；本节解决的是「当前用户有没有资格把进程设成 FIFO 实时调度」。没有 rtprio 时，即使已切换 PREEMPT_RT 内核，控制节点仍可能按普通 SCHED_OTHER 运行，1000 Hz 周期仍可能抖动。

作用

允许本机用户使用 SCHED_FIFO（实时优先级，上限 99）
允许无限 memlock，避免控制线程工作内存被换出
与上一节 PREEMPT_RT 配合，改善真机 1000 Hz 指令下发的时间确定性

配置步骤

(1) 创建 realtime 组，将当前用户加入该组，并写入 limits

sudo groupadd -f realtime
sudo usermod -aG realtime "$USER"
sudo tee /etc/security/limits.d/99-realtime.conf >/dev/null <<'EOF'
@realtime soft rtprio 99
@realtime hard rtprio 99
@realtime soft memlock unlimited
@realtime hard memlock unlimited
EOF

注意

usermod -aG 与 limits.d 必须重新登录或重启后才生效（仅 source 不够）。

不要漏写 -a，否则会覆盖用户原有附加组。

(2) 重启后检查是否生效

ulimit -r
ulimit -l
groups

预期：ulimit -r 为 99，ulimit -l 为 unlimited，groups 输出中包含 realtime。若 ulimit -r 仍为 0，请重新登录后再查。

(3) 启动 ROS 程序后检查控制节点调度策略

先按真机方式启动，例如：

ros2 launch rokae_hardware rokae_moveit_launch.py \
  robot_type:=SR5 use_fake_hardware:=false \
  robot_ip:=192.168.2.160 local_ip:=192.168.2.129

再在另一个终端执行：

pid=$(pgrep -fn 'controller_manager/ros2_control_node')
echo "PID=$pid"

if [ -n "$pid" ]; then
  chrt -p "$pid"
  ps -o pid,cls,rtprio,pri,ni,psr,comm,args -p "$pid"
else
  echo "没有找到 ros2_control_node，请确认 launch 正在运行"
fi

现象	说明
`ulimit -r` 为 `99`，`ulimit -l` 为 `unlimited`	当前用户已具备 FIFO / memlock 权限
`chrt` 显示 `SCHED_FIFO`	控制节点已按实时调度运行
`chrt` 仍显示 `SCHED_OTHER`	用户权限已就绪，但进程未申请 FIFO；权限配置仍然有效，不等于启动失败

本步只检查进程实际调度策略，不保证所有机型、所有启动方式都会把 ros2_control_node 设为 FIFO。

第 3 章软件包结构

3.1 工作空间顶层目录

doc/                                    # 手册与说明
rokae_description/                      # URDF / xacro / 网格模型
rokae_hardware/                         # 硬件接口、驱动、launch、控制器配置
rokae_msgs/                             # 自定义消息与服务
rokae_xMateAR5L_moveit_config/          # 各机型 MoveIt 2 配置
rokae_xMateAR5R_moveit_config/
rokae_xMateAR5R08_moveit_config/
rokae_xMateAR5R08ZY2_moveit_config/
rokae_xMateAR5L08_moveit_config/
rokae_xMateAR5L08ZY2_moveit_config/
rokae_xMateAR3R_moveit_config/
rokae_xMateAR3L_moveit_config/
rokae_xMateCR7_moveit_config/
rokae_xMateCR12_moveit_config/
rokae_xMateCR18_moveit_config/
rokae_xMateCR20_moveit_config/
rokae_xMateCR35_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/
rokae_xMateXB7s_moveit_config/
rokae_xMateXB7h_moveit_config/
rokae_xMateNB25s_moveit_config/
rokae_xMateNB25h_moveit_config/
rokae_xMateNB12s_moveit_config/
rokae_xMateNB12h_moveit_config/
rokae_xMateEB4_moveit_config/
rokae_xMateNB4_moveit_config/
rokae_xMateXB4s_moveit_config/
rokae_xMateXB4h_moveit_config/
rokae_xMateNB220s_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 接口为 ROS 2 Service
`rokae_driver7.cpp`	七轴机型：同上
`rokae_hardware_interface.cpp`	`ros2_control` SystemInterface 实现，经 `pluginlib` 由 `controller_manager` 加载

第 4 章系统架构与入门

4.1 ROS 2 Control 架构

本软件包采用 ROS 2 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 显示（仅可视化）

轮式双臂整机模型已集成到 rokae_description，用于在 RViz2 中查看底盘、躯干与左右臂整体外观与关节联动显示。

能力边界

支持	不支持
RViz2 RobotModel 渲染	真机控制 / `ros2_control`
`joint_state_publisher_gui` 拖动关节	MoveIt 规划与执行
本地 TF / `/robot_description`	Gazebo 整机仿真、`robot_type` 启动

模型构成

项	值
整机名称	`Wheel_Robot_PD2613-0.8`
左臂	`AR5-5_08L-W4C1C9-ZY2`（单机 `robot_type:=AR5L08ZY2`）
右臂	`AR5-5_08R-W4C1C9-ZY2`（单机 `robot_type:=AR5R08ZY2`）
软件包	`rokae_description`

启动命令：

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch rokae_description display_wheel_robot.launch.py

启动后会拉起 robot_state_publisher、joint_state_publisher_gui、rviz2（加载 wheel_robot.rviz，Fixed Frame: world）。

类型	路径（相对 `rokae_description`）
URDF	`urdf/wheel_robot.urdf`（同内容 `urdf/Wheel_Robot_PD2613-0.8.urdf`）
Launch	`launch/display_wheel_robot.launch.py`
RViz 配置	`launch/wheel_robot.rviz`
Mesh	`meshes/wheel_robot/`

验收要点

RViz Fixed Frame 为 world，RobotModel 无红色报错
可见底盘 / 躯干 / 头部与左、右各 7 轴臂
滑条拖动时左右臂可联动显示（仅本地关节状态，无控制器）

已知限制

无整机 ros2_control / 控制器 yaml / MoveIt / Gazebo 配置
不提供整机 robot_type，不可用 rokae_moveit_launch.py
左右臂单机完整能力请分别使用 robot_type:=AR5L08ZY2、AR5R08ZY2

4.3 RViz + MoveIt 2 规划真机

4.3.1 前置条件

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

4.3.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

# 工业标准机 XB7h 假硬件示例
ros2 launch rokae_hardware rokae_moveit_launch.py robot_type:=XB7h use_fake_hardware:=true

# 工业标准机 XB7h 真机示例（替换 IP）
ros2 launch rokae_hardware rokae_moveit_launch.py \
  robot_type:=XB7h use_fake_hardware:=false \
  robot_ip:=192.168.21.10 local_ip:=192.168.21.101

# 工业标准机 NB220s 假硬件 / 真机（弹簧缸 NB220s-22027-22-S2）
ros2 launch rokae_hardware rokae_moveit_launch.py robot_type:=NB220s use_fake_hardware:=true
ros2 launch rokae_hardware rokae_moveit_launch.py \
  robot_type:=NB220s use_fake_hardware:=false \
  robot_ip:=192.168.21.10 local_ip:=192.168.21.101

将示例中的 robot_type 换成你的机型，例如：AR5L、AR5R、AR5R08、AR5R08ZY2、AR5L08、AR5L08ZY2、AR3R、AR3L、SR4、ER7、Pro3、Pro7、CR7、CR12、CR18、CR20、CR35、XB7s、XB7h、NB25s、NB25h、NB12s、NB12h、EB4、NB4、XB4s、XB4h、NB220s 等。

参数	含义
`robot_type`	机型简写，见上表
`robot_ip`	机器人控制器 IP
`local_ip`	本机连接控制器网卡的 IP
`use_fake_hardware`	`true`：使用 `mock_components/GenericSystem` 仿真；`false`：加载真实硬件插件

建议流程：先在 use_fake_hardware:=true 下验证 MoveIt 与控制器链路，再切换为 false 连接真机或 HMI。
真机连接时，请关注 HMI 中 RCI 相关设置 与 网络丢包率。

工业标准机型 XB7s / XB7h / NB25s / NB25h / NB12s / NB12h / EB4 / NB4 / XB4s / XB4h / NB220s：硬件层自动使用 SDK StandardRobot + RtMotionControlIndustrial<6>，无需再手动改 xMateRobot 分支。协作六轴/七轴仍走 xMateRobot / xMateErProRobot。

4.3.3 六轴 / 七轴与 SDK 机器人类型

协作机型若需改轴数，可在硬件接口源码中切换 6 轴 / 7 轴实现（工业标准机 XB7s/XB7h/NB25s/NB25h/NB12s/NB12h/EB4/NB4/XB4s/XB4h/NB220s 不适用此方式，已走 StandardRobot 分支）。涉及文件：

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.3.4 RViz 中规划操作要点

黄色模型为目标位姿，白色为当前状态，半透明灰色为起始姿态。
拖动交互标记（末端球体）或使用 MotionPlanning → Joints 修改目标关节角。
点击 Plan & Execute 生成并执行轨迹。
连续多次规划时，建议先再次拖动末端标记，刷新 Joints 面板中的目标值。
速度缩放：MotionPlanning → Planning → Options → Velocity Scaling / Accel. Scaling（比例 0–1）。修改后须重新点击 Plan 或 Plan & Execute 才会生效。
规划速度上限由各机型 rokae_xMate*_moveit_config/config/joint_limits.yaml 的 max_velocity / max_acceleration 决定，RViz 滑条在其基础上再缩放。

图 1 HMI 状态监控

图 2 RViz 可视化

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

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

4.4 基于 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.5 常用节点 / 话题 / Action

4.5.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.5.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`	控制器状态
`/position_joint_trajectory_controller/joint_trajectory`	向控制器发送轨迹命令（通常经 Action 通信）

4.5.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.6 `rokae_driver` 驱动与接口

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

4.6.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.6.2 Topic 一览

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

4.6.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

# 工业标准机
ros2 launch rokae_hardware rokae_driver.launch.py robot_ip:=192.168.21.10 local_ip:=192.168.21.101 robot_class:=standard xMate_type:=XB7s

ros2 launch rokae_hardware rokae_driver.launch.py robot_ip:=192.168.21.10 local_ip:=192.168.21.101 robot_class:=standard xMate_type:=XB7h

run 或 launch 二选一即可，注意替换为实际 IP。工业标准机将 xMate_type 换为对应机型即可。

示例：查询机器人信息

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 包；与现有机型存在差异时，以现有机型包内文件组织方式为基准对齐。

第 6 章 Gazebo 仿真与轨迹开发

说明

下文示例中工作空间路径以 ~/ros2_ws、源码目录以 ~/ros2_ws/src/rokae_ros2 为例，请按本机实际路径替换；每个新终端均建议先执行：
source ~/ros2_ws/install/setup.bash
关节命名：指令、轨迹、控制器配置统一为 joint1～joint6（六轴）或 joint1～joint7（七轴）；各轴软限位以 rokae_description/urdf/ 中对应机型（含 *_Gazebo*.urdf.xacro）的 <limit> 为准；发轨迹前务必 ros2 topic echo /joint_states 核对轴数与关节名字。

6.1 环境与场景支持

6.1.1 障碍场景一键加载

参数 gazebo_world_file:=obstacles.world 时，由 test_model.launch.py 载入 rokae_gazebo/worlds/obstacles.world。机型与场景解耦，只改 robot_type 即可。

source ~/ros2_ws/install/setup.bash
ros2 launch rokae_hardware test_model.launch.py \
  robot_type:=Pro3 gazebo_world_file:=obstacles.world gui:=true

已支持机型（如 SR3、SR4、SR5、CR7、CR12、CR18、CR20、CR35、ER3、ER7、Pro3、Pro7、AR5L、AR5R、AR5R08、AR5L08、AR3R、AR3L、NB12s 等工业标准机型）同理替换 robot_type。默认空世界为 empty.world；不加 gazebo_world_file 即空世界。

6.1.2 场景加载与保存服务

节点 scene_service（包 rokae_hardware）提供：

服务名	作用
`/load_scene`	按场景名查找 `.world`，校验路径并登记为参数
`/save_scene`	将模板 world 复制到用户目录，保存自定义场景快照

服务类型：rokae_hardware/srv/SceneService，字段 scene_name（字符串）。

终端 1 — 启动带障碍的仿真：

ros2 launch rokae_hardware test_model.launch.py \
  robot_type:=SR3 gazebo_world_file:=obstacles.world gui:=true

终端 2 — 启动场景服务：

ros2 run rokae_hardware scene_service

终端 3 — 调用服务：

ros2 service call /load_scene rokae_hardware/srv/SceneService "{scene_name: 'obstacles.world'}"
ros2 service call /save_scene rokae_hardware/srv/SceneService "{scene_name: 'my_cr7_snapshot'}"

成功时 save_scene 一般保存到 ~/.rokae_gazebo/saved_worlds/<名称>.world。若需替换已在运行的 Gazebo 世界，应先关闭 Gazebo，再用 launch 的 world 参数启动该文件。

6.1.3 碰撞检测验证

# 终端 1
ros2 launch rokae_hardware test_model.launch.py \
  robot_type:=SR5 gazebo_world_file:=obstacles.world gui:=true

# 终端 2（robot_type 须与终端 1 一致）
ros2 launch rokae_gazebo collision_test.launch.py \
  robot_type:=SR5 publish_motion:=false contact_topic:=/obstacle/bumper_contact

publish_motion:=false：不在本节点内自动发轨迹，靠滑条或外部轨迹顶障碍。
默认按 robot_collision_substring:=xMate 过滤无关接触。

6.2 ros2_control 集成与轨迹控制

6.2.1 仿真控制闭环

Gazebo 插件 libgazebo_ros2_control.so 启动 controller_manager。
test_model.launch.py 延时后通过 spawner 依次加载：
- joint_state_broadcaster：发布 /joint_states
- arm_controller（JointTrajectoryController）：订阅 /arm_controller/joint_trajectory
链路：ROS 2 轨迹话题 → 轨迹控制器 → Gazebo 关节。

6.2.2 `controll_movej.launch.py`

在 Gazebo 中加载机型 URDF、gazebo_ros2_control、joint_state_broadcaster 与 arm_controller；相对 test_model.launch.py 另可带入 MoveIt 配置，并可选 movej 演示节点。

重要：勿同时 enable_gui:=true 与 enable_movej:=true，避免多源争抢同一轨迹控制器。

模式 A — GUI 滑条：

ros2 launch rokae_hardware controll_movej.launch.py \
  robot_type:=SR3 enable_gui:=true enable_movej:=false

模式 B — movej 演示 + 终端发轨迹：

ros2 launch rokae_hardware controll_movej.launch.py \
  robot_type:=SR3 enable_gui:=false enable_movej:=true

6.2.3 验证 `/joint_states`

ros2 topic echo /joint_states --once

name 字段应为 joint1…joint6（或含 joint7），与 rokae_hardware/config/xMate{机型}_controllers.yaml 中控制器 joints 列表一致。

6.2.4 轨迹话题与 `ros2 topic pub` 示例

确认当前轨迹订阅者：

ros2 control list_controllers
ros2 topic list | grep joint_trajectory

Gazebo test_model / controll_movej 场景下，常见为 /arm_controller/joint_trajectory。
若仅 position_joint_trajectory_controller 为 active（例如单独使用 rokae_moveit_launch.py），则向 /position_joint_trajectory_controller/joint_trajectory 发布。

六轴示例：

ros2 topic pub --once /arm_controller/joint_trajectory trajectory_msgs/msg/JointTrajectory "
joint_names: [joint1, joint2, joint3, joint4, joint5, joint6]
points:
  - positions: [0.20, -0.20, 0.15, 0.00, 0.20, 0.00]
    time_from_start: {sec: 3, nanosec: 0}
  - positions: [0.20, -0.55, 0.25, 0.10, 0.30, 0.10]
    time_from_start: {sec: 6, nanosec: 0}
"

七轴须 joint_names 与每条 positions 均为 7 维。

6.2.5 各机型关节角软限位参考（弧度）

下表数值来自仓库 Gazebo xacro 中 <limit>，仅作发指令前粗查；改 URDF 后以文件为准。

机型	joint1	joint2	joint3	joint4	joint5	joint6	joint7
SR3	[-3.0543, 3.0543]	[-2.3562, 2.2689]	[-3.0543, 2.3562]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	—
SR4	[-3.0543, 3.0543]	[-2.3562, 2.3562]	[-2.3562, 2.3562]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	—
SR5	[-6.2832, 6.2832]	[-2.7925, 2.618]	[-2.9671, 2.4435]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	—
CR7	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	—
CR12	[-6.2832, 6.2832]	[-2.9671, 2.9671]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	—
CR18	[-3.0543, 3.0543]	[-2.9671, 2.9671]	[-2.8798, 2.8798]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	—
CR20	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-2.9671, 2.9671]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	[-3.0543, 3.0543]	—
CR35	[-6.2832, 6.2832]	[-6.2832, 6.2832]	[-2.8972, 2.8972]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	[-6.2832, 6.2832]	—
ER3	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-2.0944, 2.0944]	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-6.2832, 6.2832]	—
ER7	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-2.0944, 2.0944]	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-6.2832, 6.2832]	—
Pro3 / Pro7	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-6.2832, 6.2832]
AR5L / AR5R	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-1.0472, 1.0472]	[-1.0472, 1.0472]
AR5R08	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-0.8727, 0.8727]	[-0.8727, 0.8727]
AR5R08ZY2	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-1.0472, 1.0472]	[-1.0472, 1.0472]
AR5L08	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-0.8727, 0.8727]	[-0.8727, 0.8727]
AR5L08ZY2	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-1.0472, 1.0472]	[-1.0472, 1.0472]
AR3R	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-1.0472, 1.0472]	[-1.5708, 1.5708]
AR3L	[-3.1067, 3.1067]	[-2.0944, 2.0944]	[-3.1067, 3.1067]	[-1.0472, 2.5307]	[-3.1067, 3.1067]	[-1.0472, 1.0472]	[-1.5708, 1.5708]
XB7s / XB7h	[-2.9671, 2.9671]	[-1.6755, 2.3562]	[-3.4034, 1.1345]	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-6.2832, 6.2832]	—
NB25s	[-3.1416, 3.1416]	[-1.7279, 2.7227]	[-3.4907, 1.3090]	[-3.1416, 3.1416]	[-2.3562, 2.3562]	[-6.2832, 6.2832]	—
NB25h	[-3.1416, 3.1416]	[-1.7279, 2.7227]	[-3.4907, 1.3090]	[-3.7525, 3.7525]	[-3.9270, 3.9270]	[-7.8540, 7.8540]	—
NB12s	[-2.9671, 2.9671]	[-1.8326, 2.5307]	[-3.6652, 1.2217]	[-4.7124, 4.7124]	[-2.3562, 2.3562]	[-6.2832, 6.2832]	—
NB12h	[-3.1416, 3.1416]	[-1.7453, 2.6180]	[-3.4907, 1.5708]	[-3.1416, 3.1416]	[-3.1416, 3.1416]	[-6.2832, 6.2832]	—
EB4 / XB4s / XB4h	[-2.9671, 2.9671]	[-1.3963, 2.5133]	[-3.3859, 0.9425]	[-2.9671, 2.9671]	[-2.0769, 2.0769]	[-6.2832, 6.2832]	—
NB4	[-2.9671, 2.9671]	[-1.5708, 2.2689]	[-3.4907, 0.9599]	[-2.9671, 2.9671]	[-2.0944, 2.0944]	[-6.2832, 6.2832]	—
NB220s	[-3.2289, 3.2289]	[-1.1345, 1.4835]	[-3.5779, 1.3963]	[-3.4907, 3.4907]	[-2.2689, 2.2689]	[-6.2832, 6.2832]	—

6.3 一键 launch（仿真 / 真机）

6.3.1 入口与内部链路

ros2 launch rokae_hardware gazebo_moveit.launch.py ...

条件	子 launch	作用
`mode:=sim`	`controll_movej.launch.py`	Gazebo + `gazebo_ros2_control`；`world` → 子 launch 的 `gazebo_world_file`；可选 `enable_gui` / `enable_movej`
`mode:=real`	`real_moveit.launch.py`	本机 `ros2_control_node` + 真机 IP，加载 `xMate{机型}_real_controllers.yaml`；不启动 Gazebo

6.3.2 参数约束

mode:=real 时 use_sim_time:=false（真机用系统时钟）。
mode:=sim 时不可同时 enable_gui:=true 与 enable_movej:=true。
mode:=real 必须同时提供 robot_ip 与 local_ip。

6.3.3 仿真模式示例

# 空世界 + 滑条（SR3）
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=SR3 world:=empty.world enable_gui:=true enable_movej:=false

# 障碍世界（CR7 / CR35）
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=CR7 world:=obstacles.world enable_gui:=true enable_movej:=false
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=CR35 world:=obstacles.world enable_gui:=true enable_movej:=false

# 工业标准机 NB12s / NB12h / NB25s / NB25h / NB220s
ros2 launch rokae_hardware test_model.launch.py robot_type:=NB12s gazebo_world_file:=empty.world gui:=true
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=NB12s world:=empty.world enable_gui:=true enable_movej:=false
ros2 launch rokae_hardware test_model.launch.py robot_type:=NB220s gazebo_world_file:=empty.world gui:=true
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=NB220s world:=empty.world enable_gui:=true enable_movej:=false

# 开 movej 演示、关 GUI
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=CR7 world:=empty.world enable_gui:=false enable_movej:=true

# 七轴 AR 系列（AR5L08 / AR5R08 / AR5R08ZY2 / AR5L08ZY2 / AR3L / AR3R）
ros2 launch rokae_hardware test_model.launch.py robot_type:=AR5L08 gazebo_world_file:=empty.world gui:=false
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=AR5L08 world:=empty.world enable_gui:=true enable_movej:=false
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=AR5R08ZY2 world:=empty.world enable_gui:=true enable_movej:=false
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=AR3L world:=empty.world enable_gui:=true enable_movej:=false

6.3.4 真机模式示例

# CR7 / CR35 真机（无 Gazebo）
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=real robot_type:=CR7 \
  robot_ip:=192.168.2.160 local_ip:=192.168.2.162 \
  enable_moveit:=false use_sim_time:=false

# 工业标准机 XB7h（MoveIt + ros2_control 一体）
ros2 launch rokae_hardware rokae_moveit_launch.py \
  robot_type:=XB7h use_fake_hardware:=false \
  robot_ip:=192.168.21.10 local_ip:=192.168.21.101

另开终端发关节轨迹（六轴，控制器为 arm_controller 时）：

ros2 topic pub --once /arm_controller/joint_trajectory trajectory_msgs/msg/JointTrajectory "
joint_names: [joint1, joint2, joint3, joint4, joint5, joint6]
points:
  - positions: [0.10, -0.20, 0.15, 0.00, 0.20, 0.00]
    time_from_start: {sec: 3, nanosec: 0}
  - positions: [0.20, -0.35, 0.25, 0.10, 0.30, 0.10]
    time_from_start: {sec: 6, nanosec: 0}
"

6.4 仿真数据录制与回放

6.4.1 脚本说明

rokae_hardware/scripts/record_sim.sh
- 用法：bash .../record_sim.sh [bag输出目录] [robot_type可选]
- 默认在 ~/rosbags/<robot小写>_sim_日期时间> 创建；等待轨迹话题出现后再 ros2 bag record
rokae_hardware/scripts/replay_sim.sh
- 用法：bash .../replay_sim.sh <bag目录> [倍速rate] [with_clock true|false]
- 默认 rate=1.0；第三参数为 true 时增加 ros2 bag play --clock

6.4.2 推荐流程（三终端）

以 robot_type:=CR7、bag 目录 ~/rosbags/cr7_sim0002 为例：

# 终端 1 — 启动仿真
ros2 launch rokae_hardware gazebo_moveit.launch.py \
  mode:=sim robot_type:=CR7 world:=empty.world enable_gui:=false enable_movej:=false

# 终端 2 — 开始录制
bash ~/ros2_ws/src/rokae_ros2/rokae_hardware/scripts/record_sim.sh ~/rosbags/cr7_sim0002 CR7
# 结束：Ctrl+C

# 终端 3 — 录制过程中下发轨迹
ros2 topic pub --once /arm_controller/joint_trajectory trajectory_msgs/msg/JointTrajectory "
joint_names: [joint1, joint2, joint3, joint4, joint5, joint6]
points:
  - positions: [0.10, -0.20, 0.15, 0.00, 0.20, 0.00]
    time_from_start: {sec: 3, nanosec: 0}
  - positions: [0.30, -0.35, 0.25, 0.10, 0.30, 0.10]
    time_from_start: {sec: 6, nanosec: 0}
"

6.4.3 检查与回放

ros2 bag info ~/rosbags/cr7_sim0002

# 原速回放（终端 1 先启动与录制时相同的仿真）
bash ~/ros2_ws/src/rokae_ros2/rokae_hardware/scripts/replay_sim.sh ~/rosbags/cr7_sim0002

# 二倍速 / 带 --clock
bash ~/ros2_ws/src/rokae_ros2/rokae_hardware/scripts/replay_sim.sh ~/rosbags/cr7_sim0002 2.0
bash ~/ros2_ws/src/rokae_ros2/rokae_hardware/scripts/replay_sim.sh ~/rosbags/cr7_sim0002 1.0 true

6.4.4 使用注意

回放前 robot_type、URDF、关节轴数须与录制时一致。
用 ros2 control list_controllers 确认轨迹控制器为 active。
回放异常时检查 use_sim_time、bag 是否含 /clock、以及 replay_sim.sh 第三参数。

附录 A 术语表

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

附录 B 反馈与支持

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

文档信息​

版本记录​

适用范围与读者​

重要声明​

目录​

第 1 章 概述​

1.1 ROS 2 简介​

1.2 手册目的与范围​

1.3 当前适配机型​

第 2 章 安装与环境​

2.1 硬件与操作系统要求​

2.2 ROS 2 与依赖包安装​

2.3 工作空间创建与编译​

2.4 实时内核（PREEMPT_RT）配置​

作用​

安装步骤​

验证指令与预期效果​

2.5 给当前用户添加 FIFO 权限​

作用​

配置步骤​

第 3 章 软件包结构​

3.1 工作空间顶层目录​

3.2 rokae_hardware 包结构​

3.3 rokae_hardware/src 源文件说明​

第 4 章 系统架构与入门​

4.1 ROS 2 Control 架构​

4.2 双臂整机 RViz 显示（仅可视化）​

4.3 RViz + MoveIt 2 规划真机​

4.3.1 前置条件​

4.3.2 启动示例​

4.3.3 六轴 / 七轴与 SDK 机器人类型​

4.3.4 RViz 中规划操作要点​

4.4 基于 MoveIt 的 movej 示例​

4.5 常用节点 / 话题 / Action​

4.5.1 节点​

4.5.2 话题​

4.5.3 Action​

4.6 rokae_driver 驱动与接口​

4.6.1 Service 一览​

4.6.2 Topic 一览​

4.6.3 启动命令​

第 5 章 扩展与定制​

5.1 适配新机型​

第 6 章 Gazebo 仿真与轨迹开发​

说明​

6.1 环境与场景支持​

6.1.1 障碍场景一键加载​

6.1.2 场景加载与保存服务​

6.1.3 碰撞检测验证​

6.2 ros2_control 集成与轨迹控制​

6.2.1 仿真控制闭环​

6.2.2 controll_movej.launch.py​

6.2.3 验证 /joint_states​

6.2.4 轨迹话题与 ros2 topic pub 示例​

6.2.5 各机型关节角软限位参考（弧度）​

6.3 一键 launch（仿真 / 真机）​

6.3.1 入口与内部链路​

6.3.2 参数约束​

6.3.3 仿真模式示例​

6.3.4 真机模式示例​

6.4 仿真数据录制与回放​

6.4.1 脚本说明​

6.4.2 推荐流程（三终端）​

6.4.3 检查与回放​

6.4.4 使用注意​

附录 A 术语表​

附录 B 反馈与支持​