3.11 MoveIt Setup Assistant 配置自定义机械臂
一、Setup Assistant 简介
1.1 什么是 MoveIt Setup Assistant
MoveIt Setup Assistant 是一个图形化配置工具，用于为任何机器人生成 MoveIt 所需的配置文件。
它的主要功能是生成 SRDF（Semantic Robot Description Format） 文件，该文件描述了机器人的语义信息，包括：
- 规划组（Planning Groups）：定义哪些关节属于"手臂"、哪些属于"夹爪"
- 末端执行器（End Effectors）：标记机器人的工具端
- 自碰撞矩阵：哪些链接对不需要检测碰撞
- 预设姿态（Robot Poses）：如
home、ready等常用位置 - 虚拟关节（Virtual Joints）：将机器人连接到世界坐标系
URDF vs SRDF：
- URDF：描述机器人的物理结构（关节、链接、惯性、碰撞体等）
- SRDF：描述机器人的语义信息（哪些是手臂、哪些是夹爪、哪些链接不会碰撞）
MoveIt 需要同时使用 URDF 和 SRDF 才能正常工作。
1.2 配置包的作用
Setup Assistant 会生成一个完整的 ROS2 包（*_moveit_config），一般包含：
episode1_urdf_student_moveit/
├── CMakeLists.txt # CMake 构建配置
├── config/
│ ├── episode1_urdf_1113.ros2_control.xacro # ros2_control 硬件接口定义
│ ├── episode1_urdf_1113.srdf # 语义描述文件（规划组、碰撞矩阵等）
│ ├── episode1_urdf_1113.urdf.xacro # URDF 入口文件（包含 ros2_control）
│ ├── initial_positions.yaml # 初始关节位置
│ ├── joint_limits.yaml # 关节限位（位置、速度、加速度）
│ ├── joint_limits_ompl.yaml # OMPL 规划器专用关节限位
│ ├── joint_limits_pilz.yaml # Pilz 规划器专用关节限位
│ ├── kinematics.yaml # 运动学求解器配置（KDL/IKFast等）
│ ├── moveit_controllers.yaml # MoveIt 控制器配置
│ ├── moveit.rviz # RViz 界面布局配置
│ ├── pilz_cartesian_limits.yaml # Pilz 笛卡尔空间限制
│ ├── pilz_industrial_motion_planner_planning.yaml # Pilz 工业运动规划器配置
│ ├── ros2_controllers.yaml # ROS2 控制器配置
│ └── sensors_3d.yaml # 3D 传感器配置（点云/深度图）
├── launch/
│ ├── demo.launch.py # 演示启动（含模拟控制器 + RViz）
│ ├── demo_with_perception.launch.py # 演示启动（含 3D 感知）
│ ├── move_group.launch.py # MoveIt 核心节点启动
│ ├── moveit_rviz.launch.py # 仅启动 RViz
│ ├── rsp.launch.py # Robot State Publisher 启动
│ ├── setup_assistant.launch.py # 重新打开配置助手
│ ├── spawn_controllers.launch.py # 启动 ROS2 控制器
│ ├── static_virtual_joint_tfs.launch.py # 发布虚拟关节的静态 TF
│ └── warehouse_db.launch.py # MoveIt 数据库（存储场景/轨迹）
└── package.xml # ROS2 包描述文件
有了这个配置包，你就可以：
- 在 RViz 中可视化和交互式规划
- 使用 MoveIt Python/C++ API 编程控制机械臂
- 进行运动规划、碰撞检测等高级功能
1.3 配置流程概览
Setup Assistant 的配置流程分为 14 个步骤：
| 步骤 | 名称 | 说明 | Episode1 适用 |
|---|---|---|---|
| 1 | Start | 加载 URDF 文件 | ✓ |
| 2 | Self-Collisions | 生成自碰撞矩阵 | ✓ |
| 3 | Virtual Joints | 添加虚拟关节 | ✓ |
| 4 | Planning Groups | 定义规划组 | ✓ |
| 5 | Robot Poses | 添加预设姿态 | ✓ |
| 6 | End Effectors | 标记末端执行器 | ✗ (无夹爪) |
| 7 | Passive Joints | 添加被动关节 | ✗ (无被动关节) |
| 8 | ros2_control | URDF 控制接口修改 | 讲解原理 |
| 9 | ROS 2 Controllers | 配置 ROS2 控制器 | ✓ |
| 10 | MoveIt Controllers | 配置 MoveIt 控制器 | ✓ |
| 11 | Perception | 3D 感知配置 | ✗ (暂不使用) |
| 12 | Launch Files | 预览启动文件 | ✓ |
| 13 | Author Information | 作者信息 | ✓ |
| 14 | Configuration Files | 生成配置包 | ✓ |
二、配置前的准备
2.1 确认 URDF 文件位置
在开始配置之前，确保你已经有 Episode1 机械臂的 URDF 文件。
- 将下载好的 Episode1 ROS2 包中的 URDF 包
episode1_urdf_1113复制进我们的课程文件夹~/ros2_ws/src。 -
# 目录效果 ./src ├── episode1_urdf_1113 ├── py_episode ├── robot_arm_interfaces └── urdf_test
2.2 理解 Episode1 的关节结构
在配置之前，了解机械臂的关节结构非常重要：
world (虚拟)
└── base_link (基座)
└── joint1 → link1
└── joint2 → link2
└── joint3 → link3
└── joint4 → link4
└── joint5 → link5
└── joint6 → link6 (末端法兰)
Episode1 关节信息：
| 关节名称 | 类型 | 说明 |
|---|---|---|
joint1 |
revolute | 基座旋转 |
joint2 |
revolute | 肩部俯仰 |
joint3 |
revolute | 肘部俯仰 |
joint4 |
revolute | 腕部旋转 |
joint5 |
revolute | 腕部俯仰 |
joint6 |
revolute | 末端旋转 |
2.3 启动 Setup Assistant
确保已安装 MoveIt2，然后启动 Setup Assistant：
# 进入课程文件夹~/ros2_ws
# source，否则找不到URDF
source install/setup.bash
# 启动 Setup Assistant
ros2 launch moveit_setup_assistant setup_assistant.launch.py
QT_QPA_PLATFORM=xcb ros2 launch moveit_setup_assistant setup_assistant.launch.py
启动后会看到欢迎界面：
三、配置流程
3.1 Step 1: 加载 URDF（Start）
-
在欢迎界面，点击 Create New MoveIt Configuration Package
-
点击 Browse 按钮，导航到 Episode1 的 URDF 文件：
~/ros2_ws/src/episode1_urdf_1113/urdf/episode1_urdf_1113.urdf -
选择文件后，点击 Load Files
-
等待加载完成，你会看到机械臂的 3D 模型显示在右侧
3.2 Step 2: 生成自碰撞矩阵（Self-Collisions）
► 影响文件：
config/episode1_urdf_1113.srdf（<disable_collisions>标签）
作用：自碰撞矩阵用于优化运动规划性能。它会预先计算哪些链接对：
- 永远不会碰撞（距离太远）
- 总是碰撞（相邻链接）
- 默认姿态下碰撞
这样在运动规划时，就不需要检测这些"安全"的链接对，大大提高规划速度。
配置步骤：
-
点击左侧的 Self-Collisions 面板
-
调整 Sampling Density（采样密度）：
- 默认采样 10,000 个随机位置
- 建议使用较高值以获得更准确的结果
-
点击 Generate Collision Matrix 按钮
-
等待计算完成（几秒钟），结果会显示在表格中
理解表格：表格中显示了被禁用碰撞检测的链接对及原因（如 "Adjacent Links"、"Never in Collision" 等）。你可以手动调整，但通常自动生成的结果就足够了。
3.3 Step 3: 添加虚拟关节（Virtual Joints）
► 影响文件：
config/episode1_urdf_1113.srdf（<virtual_joint>标签）
作用：虚拟关节用于将机器人的基座连接到世界坐标系。对于固定基座的机械臂，使用 fixed 类型的虚拟关节表示基座不会移动。
扩展知识：对于移动机器人（如移动机械臂），可以使用
planar或floating类型的虚拟关节来描述底盘的运动。
配置步骤：
-
点击左侧的 Virtual Joints 面板
-
点击 Add Virtual Joint
-
填写以下参数：
参数 值 Virtual Joint Name virtual_jointChild Link base_linkParent Frame Name worldJoint Type fixed -
点击 Save
3.4 Step 4: 添加规划组（Planning Groups）
► 影响文件：
config/episode1_urdf_1113.srdf（<group>标签）config/kinematics.yaml（运动学求解器配置）config/joint_limits.yaml（关节限位，从 URDF 提取）config/joint_limits_ompl.yaml/joint_limits_pilz.yaml（规划器专用限位）
作用：规划组是 MoveIt 中最重要的概念之一。它定义了机器人的哪些部分应该一起规划运动。例如：
arm组：包含手臂的所有关节gripper组：包含夹爪的关节
对于 Episode1，我们只需要定义一个手臂组。
配置步骤：
-
点击左侧的 Planning Groups 面板
-
点击 Add Group
-
填写基本信息：
参数 值 说明 Group Name episode_arm规划组名称 Kinematic Solver kdl_kinematics_plugin/KDLKinematicsPlugin运动学求解器 Group Default Planner RRTConnectOMPL 默认规划器（推荐） Kin. Search Resolution 保持默认 IK 搜索分辨率 Kin. Search Timeout 保持默认 IK 搜索超时时间 关于运动学求解器：
- KDL：MoveIt 默认的求解器，基于数值迭代方法，适用于大多数机械臂
- IKFast：解析求解器，速度更快但需要针对特定机械臂生成
- pick_ik：新一代求解器，性能和鲁棒性更好
本课程使用默认的 KDL 求解器。
关于 OMPL 规划器选择：
- RRTConnect（推荐）：双向快速随机树算法，速度快、成功率高，是最通用的选择
- RRT*：路径质量更优但规划时间更长
- PRM：适合需要在同一环境多次规划的场景
对于 Episode1 机械臂的日常使用，RRTConnect 是最佳选择。
-
添加关节到规划组（两种方式任选其一）：
方式一：Add Kin. Chain（推荐）
点击 Add Kin. Chain 按钮，指定运动链的起点和终点：
参数 值 说明 Base Link base_link运动链起点 Tip Link link6运动链终点（末端法兰） 系统会自动找到从
base_link到link6之间的所有关节。这种方式适合串联机械臂，无需手动逐个选择关节。
方式二：Add Joints（手动选择）
点击 Add Joints 按钮，在左侧列表中选择以下关节（按住 Shift 可以多选）：
virtual_jointjoint1joint2joint3joint4joint5joint6
点击 > 按钮将选中的关节添加到右侧。
-
点击 Save 保存规划组
3.5 Step 5: 添加预设姿态（Robot Poses）
► 影响文件：
config/episode1_urdf_1113.srdf（<group_state>标签）config/initial_positions.yaml（初始关节位置）
作用：预设姿态让你可以定义机械臂的常用位置，如"准备姿态"、"归零姿态"等。之后可以通过 MoveIt API 一行代码让机械臂移动到这些位置。
配置步骤：
-
点击左侧的 Robot Poses 面板
-
点击 Add Pose
-
添加
home姿态（归零位置）：参数 值 Pose Name homePlanning Group episode_arm -
使用滑块或直接输入调整各关节角度（弧度制）：
全部为0注意：MoveIt 内部使用弧度制。如果你习惯角度制，可以用公式转换：弧度 = 角度 × π / 180
-
点击 Save
-
重复上述步骤，添加
test1姿态：参数 值 Pose Name readyPlanning Group episode1_arm关节角度 自己随意拉一个角度
提示：在这一步，拖动各关节滑块可以检查 URDF 中的关节限位是否正确。如果某个关节无法移动或范围异常，说明 URDF 可能有问题。
3.6 Step 6: 标记末端执行器（End Effectors）
► 影响文件：
config/episode1_urdf_1113.srdf（<end_effector>标签）
作用：末端执行器（End Effector）通常指机械臂末端的工具，如夹爪、吸盘等。将一个规划组标记为末端执行器后，MoveIt 可以对其进行特殊操作，如：
- 在抓取任务中将物体"附着"到末端执行器
- 单独控制夹爪的开合
Episode1 配置：
⏭️ 跳过此步骤：Episode1 机械臂末端为法兰盘，夹爪暂未加入 URDF 模型。
关于末端执行器控制：
实际上，夹爪和吸盘的控制非常简单，通常只需要：
- 夹爪：开 / 合（控制一个舵机或气缸）
- 吸盘：吸 / 放（控制电磁阀或气泵开关）
这类简单的开关控制不需要借助 MoveIt 的运动规划能力，直接通过 GPIO、串口或 CAN 发送指令即可。MoveIt 中配置末端执行器主要是为了：
- 在规划时考虑夹爪的碰撞体积
- 支持"附着物体"功能（模拟抓取后物体跟随夹爪移动）
关于 Episode1 夹爪的 URDF 建模：
Episode1 配套的夹爪采用平行四边形连杆机构，这是一种闭环运动链。然而，URDF 只支持树状结构（开环），无法直接描述闭环机构，因此暂未将夹爪加入模型。
机构类型 特点 URDF 支持 开环（树状） 每个链接只有一个父链接 ✓ 闭环（平行四边形等） 形成封闭环路 ✗ 如需在 URDF 中添加夹爪，可采用 Mimic Joint（从动关节） 或 简化模型 方式处理。
3.7 Step 7: 添加被动关节（Passive Joints）
► 影响文件：
config/episode1_urdf_1113.srdf（<passive_joint>标签）
作用：被动关节是指无法直接控制的关节，例如：
- 某些夹爪的从动手指（通过连杆机构被动运动）
- 平衡配重关节
- 弹簧悬挂关节
指定被动关节后，运动规划器会知道不应该为这些关节规划轨迹。
Episode1 配置：
⏭️ 跳过此步骤：Episode1 是标准的六轴串联机械臂，所有关节都是主动关节，没有被动关节。
3.8 Step 8: ros2_control URDF 修改（定义硬件能力）
► 影响文件：
config/episode1_urdf_1113.ros2_control.xacro（硬件接口定义）config/episode1_urdf_1113.urdf.xacro（URDF 入口文件，包含 ros2_control）
作用：在 URDF 中声明每个关节支持什么类型的硬件接口。
通俗理解：这一步是在"登记硬件能力"——告诉系统："我的 joint1 可以接收位置命令，也能反馈当前位置和速度"。
<!-- 这段代码会被添加到 URDF 中 -->
<ros2_control name="episode1_arm" type="system">
<joint name="joint1">
<command_interface name="position"/> <!-- 可以接收位置命令 -->
<state_interface name="position"/> <!-- 可以反馈当前位置 -->
<state_interface name="velocity"/> <!-- 可以反馈当前速度 -->
</joint>
<!-- joint2 ~ joint6 类似 -->
</ros2_control>
配置步骤：
-
点击左侧的 ros2_control URDF Modification 面板
-
保持默认设置：
- Command Interface:
position - State Interface:
position,velocity
- Command Interface:
-
点击 Add Interfaces
⚠️ 说明：Episode1 机械臂实际使用自定义的 CAN 通信控制，不使用标准的
ros2_control框架。但为了让 MoveIt 的 Demo 演示模式正常工作（使用模拟控制器），我们仍需配置这一步。
3.9 Step 9: 配置 ROS2 控制器（选择控制软件）
► 影响文件：
config/ros2_controllers.yaml
作用：配置实际运行的控制器软件，告诉系统用什么控制器来执行轨迹。
通俗理解：Step 8 登记了硬件能力，这一步是"选择控制软件"——告诉系统："请用 JointTrajectoryController 这个控制器来控制我的机械臂"。
Step 8 vs Step 9 的区别：
| 对比项 | Step 8: ros2_control URDF | Step 9: ROS2 Controllers |
|---|---|---|
| 层级 | 硬件层（底层） | 软件层（上层） |
| 定义什么 | 关节支持什么接口（位置/速度/力矩） | 用什么控制器软件来控制 |
| 类比 | 声明"我的手可以握东西" | 选择"用哪种方式握"（抓、捏、托） |
| 生成文件 | *.ros2_control.xacro |
ros2_controllers.yaml |
什么是"控制器"？
在机器人领域，"控制器"（Controller）这个词容易混淆，因为它可以指硬件也可以指软件：
| 类型 | 含义 | 举例 |
|---|---|---|
| 硬件控制器 | 物理电路板，执行底层电机控制 | 电机驱动板、PLC、单片机 |
| 软件控制器 | 运行在计算机上的程序，实现控制算法 | ROS2 的 JointTrajectoryController |
这里的 ROS2 Controllers 是软件控制器，它们的作用是：
MoveIt 规划的轨迹（一系列位置点）
↓
软件控制器（JointTrajectoryController）
- 接收轨迹
- 按时间插值
- 发送位置命令给硬件
↓
硬件控制器（电机驱动板）
- 接收位置命令
- 控制电机转动
常用控制器类型：
| 控制器类型 | 作用 | 通俗理解 |
|---|---|---|
JointTrajectoryController |
接收一条轨迹，按时间顺序执行每个路点 | "轨迹播放器" |
GripperActionController |
控制夹爪的开合动作 | "夹爪开关" |
DiffDriveController |
控制差速驱动底盘的左右轮速度 | "底盘驾驶员" |
配置步骤：
-
点击左侧的 ROS 2 Controllers 面板
-
点击 Add Controller
-
填写控制器信息：
参数 值 Controller Name episode_arm_controllerController Type joint_trajectory_controller/JointTrajectoryController
-
点击 Add Planning Group Joints
-
选择
episode1_arm组，点击 > 添加 -
点击 Save
3.10 Step 10: 配置 MoveIt 控制器（告诉 MoveIt 如何发送轨迹）
► 影响文件：
config/moveit_controllers.yaml
作用：告诉 MoveIt 应该把规划好的轨迹发送给谁、用什么方式发送。
Step 9 vs Step 10 的区别：
| 对比项 | Step 9: ROS2 Controllers | Step 10: MoveIt Controllers |
|---|---|---|
| 配置什么 | 控制器本身（执行轨迹的软件） | MoveIt 的"发送设置" |
| 类比 | 快递员（负责送货） | 寄件人填写的快递单（写清楚送给谁） |
| 生成文件 | ros2_controllers.yaml |
moveit_controllers.yaml |
通俗理解：
Step 9: 雇佣一个快递员（JointTrajectoryController）
↓
Step 10: 填写快递单，告诉 MoveIt：
- 收件人：episode_arm_controller（Step 9 配置的控制器名）
- 送货方式：FollowJointTrajectory Action
为什么需要两步？
因为 MoveIt 和 ROS2 控制器是独立的系统，它们通过 ROS2 的 Action 接口通信：
+-----------+ +-------------------------+
| MoveIt | FollowJointTrajectory Action | JointTrajectoryController|
+-----------+ --------------------------------> +-------------------------+
| | send: trajectory | |
| (Planner) | <-------------------------------- | (Executor) |
| | feedback: progress/done | |
+-----------+ +-------------------------+
| |
Step 10 Step 9
配置步骤：
-
点击左侧的 MoveIt Controllers 面板
-
点击 Add Controller
-
填写控制器信息：
参数 值 Controller Name episode_arm_controllerController Type FollowJointTrajectory重要：控制器名称必须与 Step 9 中配置的 ROS2 控制器名称一致
-
点击 Add Planning Group Joints
-
选择
episode1_arm组 -
点击 Save
3.11 Step 11: 3D 感知配置（Perception）
► 影响文件：
config/sensors_3d.yaml
作用：感知配置用于集成 3D 传感器（如深度相机、激光雷达），让 MoveIt 能够：
- 感知环境中的障碍物
- 动态避障规划
- 构建 OctoMap 八叉树地图
支持的传感器类型：
- Point Cloud：点云数据（如 RealSense、Kinect）
- Depth Image：深度图像
Episode1 配置：
⏭️ 跳过此步骤：本章节暂不配置 3D 感知。
- 点击左侧的 Perception 面板
- 选择 None
3.12 Step 12: 预览启动文件（Launch Files）
► 影响文件：
launch/目录下所有.launch.py文件，以及config/moveit.rviz
作用：查看将要生成的启动文件列表。
- 点击左侧的 Launch Files 面板
- 查看将生成的文件列表，点击每个文件可以看到其功能说明
主要启动文件：
| 文件 | 功能 |
|---|---|
demo.launch.py |
启动 RViz 演示，包含模拟控制器 |
move_group.launch.py |
启动 MoveIt 核心节点 |
setup_assistant.launch.py |
重新打开 Setup Assistant 修改配置 |
static_virtual_joint_tfs.launch.py |
发布虚拟关节的 TF |
spawn_controllers.launch.py |
启动控制器 |
通常保持默认选项即可。
3.13 Step 13: 填写作者信息（Author Information）
► 影响文件：
package.xml、CMakeLists.txt
作用：ROS2 包的 package.xml 需要作者信息，这是发布包的必要字段。
-
点击左侧的 Author Information 面板
-
填写你的信息：
- Name：你的名字
- Email：你的邮箱
3.14 Step 14: 生成配置包（Configuration Files）
► 影响文件：生成整个配置包的所有文件
作用：生成完整的 MoveIt 配置包。
配置步骤：
-
点击左侧的 Configuration Files 面板
-
点击 Browse 选择输出目录
-
导航到你的工作空间
src目录：~/ros2_ws/src/ -
点击 Create Folder，创建文件夹：
episode1_urdf_student_moveit -
点击 Open 确认
-
点击 Generate Package 按钮
-
等待生成完成，查看 "Files to be generated" 列表中的所有文件
提示：如果之前已经生成过配置包，Setup Assistant 会提示是否覆盖。
四、编译与验证
4.1 编译配置包
# 进入工作空间
cd ~/ros2_ws
# 编译（只编译新生成的配置包）
colcon build --packages-select episode1_urdf_student_moveit
# 或编译所有包
colcon build
# 加载环境
source install/setup.bash
4.2 启动 Demo
ros2 launch episode1_urdf_student_moveit demo.launch.py
一切正常的话，你会看到 RViz 界面，显示 Episode1 机械臂模型：
可能你的 moveit 窗口无法缩放，如果这样，可以下载我的文件覆盖
src/episode1_urdf_student_moveit/config/moveit.rviz
4.3 在 RViz 中测试
-
拖拽目标位置：
- 在 RViz 中找到机械臂末端的交互标记（橙色球和圆环）
- 拖拽到目标位置
-
规划轨迹：
- 在左侧 MotionPlanning 面板中，点击 Plan 按钮
- MoveIt 会计算一条从当前位置到目标位置的轨迹
- 轨迹会以动画形式预览
-
执行轨迹：
- 点击 Execute 按钮执行规划好的轨迹
- 或点击 Plan & Execute 一键完成规划和执行
-
移动到预设姿态：
- 在 MotionPlanning 面板的 "Planning" 标签页
- 在 "Goal State" 下拉框中选择
home或ready - 点击 Plan & Execute
注意：Demo 模式使用模拟控制器，机械臂只在 RViz 中运动，不会控制真实机械臂。下一章节我们会讲解如何连接真实机械臂。
五、常见问题
5.1 加载 URDF 失败
可能原因：
- URDF 文件路径错误
- URDF 语法错误（缺少闭合标签等）
- 缺少依赖的 mesh 文件
解决方法：
# 检查 URDF 语法
check_urdf episode1_urdf_1113.urdf
5.2 规划失败
可能原因：
- 目标位置超出工作空间
- 目标位置存在碰撞
- 运动学求解器无法找到解
解决方法：
- 选择一个更合理的目标位置
- 检查自碰撞矩阵配置
- 尝试增加规划时间（在 MotionPlanning 面板中调整）
还有一种可能情况是配置文件数值问题，比如
src/episode1_urdf_student_moveit/config/joint_limits.yamljoint_limits: joint1: has_velocity_limits: false max_velocity: 0 has_acceleration_limits: false max_acceleration: 0 joint2: has_velocity_limits: false max_velocity: 0 has_acceleration_limits: false max_acceleration: 0需要加速度和加速度限制，比如改成（所有关节都需要改）：
joint_limits: joint1: has_velocity_limits: true max_velocity: 3.14 has_acceleration_limits: true max_acceleration: 5.0 joint2: has_velocity_limits: true max_velocity: 3.14 has_acceleration_limits: true max_acceleration: 5.0
5.3 想要修改配置
如果需要修改之前的配置（如添加新的预设姿态），可以重新打开 Setup Assistant：
ros2 launch episode1_urdf_student_moveit setup_assistant.launch.py
这会加载现有配置，允许你进行修改后重新生成。