Ubuntu 24.04 + ROS 2 Jazzy 下使用 MoveIt Setup Assistant 配置机械臂

本文记录一个机械臂 MoveIt 2 配置包的生成流程，重点放在 MoveIt Setup Assistant（MSA）的概念、配置步骤和常见注意点。文中不展开真实 URDF 内容，只说明配置思路。

---

1. MSA 是什么

MoveIt Setup Assistant，简称 MSA，是 MoveIt 官方提供的图形化配置工具。

它的作用不是建模，也不是写控制器，而是根据已有的机器人模型生成 MoveIt 所需的配置包。

可以把流程理解成：

URDF / Xacro 机器人模型
    ↓
MoveIt Setup Assistant
    ↓
生成 *_moveit_config 配置包
    ↓
move_group 读取配置
    ↓
RViz / API / 测试节点可以进行规划与执行

MSA 主要生成或辅助生成这些内容：

配置文件	作用
*.srdf	MoveIt 语义描述，例如规划组、虚拟关节、命名姿态、自碰撞矩阵
kinematics.yaml	指定 IK 解算器，例如 KDL、TRAC-IK、BioIK
joint_limits.yaml	关节速度、加速度、位置限制
ompl_planning.yaml	OMPL 规划器配置
moveit_controllers.yaml	告诉 MoveIt 轨迹应该发给哪个控制器
ros2_controllers.yaml	ros2_control 控制器配置
demo.launch.py	启动 move_group、RViz、robot_state_publisher 等节点

---

2. 前置环境

本文环境：

Ubuntu 24.04
ROS 2 Jazzy
MoveIt 2

安装 MoveIt 和 MSA：

sudo apt update
sudo apt install ros-jazzy-moveit ros-jazzy-moveit-setup-assistant

加载 ROS 环境：

source /opt/ros/jazzy/setup.bash

启动 MSA：

ros2 run moveit_setup_assistant moveit_setup_assistant

如果模型是 Xacro，也可以先生成临时 URDF 再导入 MSA：

ros2 run xacro xacro path/to/robot.urdf.xacro > /tmp/robot.urdf

然后在 MSA 中选择 /tmp/robot.urdf。

---

3. Ubuntu 24.04 注意点：Wayland 问题

Ubuntu 24.04 默认可能使用 Wayland，而 MSA 内部嵌入了 RViz 的 3D 渲染窗口。在 Wayland 下，有时会出现模型加载后 3D 窗口无法创建的问题。

常见报错包括：

RenderingAPIException: Invalid parentWindowHandle
Unable to create the rendering window after 100 tries

检查当前会话类型：

echo $XDG_SESSION_TYPE

如果输出是：

wayland

建议切换到 Xorg：

1. 注销当前 Ubuntu 桌面会话。
2. 回到登录界面后，先选择用户名。
3. 点击右下角齿轮图标。
4. 选择 Ubuntu on Xorg。
5. 输入密码登录。
6. 重新打开终端，再启动 MSA。

切换后再次检查：

echo $XDG_SESSION_TYPE

如果输出：

x11

一般就可以正常打开 MSA 的 3D 预览窗口。

---

4. MSA 配置整体流程

MSA 左侧通常会有这些步骤：

Start
Self-Collisions
Virtual Joints
Planning Groups
Robot Poses
End Effectors
Passive Joints
ROS 2 Controllers
MoveIt Controllers
Perception
Author Information
Configuration Files

一个基础机械臂项目通常至少需要完成：

加载模型
    ↓
生成自碰撞矩阵
    ↓
配置虚拟关节
    ↓
配置规划组
    ↓
配置命名姿态
    ↓
配置 IK 解算器
    ↓
配置控制器
    ↓
生成 moveit_config 包

---

5. Start：加载机器人模型

在 Start 页面中选择：

Create New MoveIt Configuration Package

然后加载机器人 URDF。

这里需要注意：

检查项	说明
Link / Joint 是否完整	MSA 需要从 URDF 中解析运动链
Mesh 路径是否正确	推荐使用 package:// 路径
Joint limit 是否合理	尤其是 prismatic joint 的上下限
根 link 是否明确	后面配置 Virtual Joint 时会用到
3D 预览是否正常	如果不显示，优先检查 Wayland / Xorg

MSA 只是读取模型，不负责修复模型。如果模型本身 link、joint、mesh 路径有问题，后续 MoveIt 配置也会出问题。

---

6. Self-Collisions：生成自碰撞矩阵

自碰撞矩阵用于告诉 MoveIt：哪些 link pair 需要检查碰撞，哪些可以忽略。

操作：

Self-Collisions
    ↓
Generate Collision Matrix
    ↓
保持默认采样数即可

生成后会写入 SRDF。

作用是：

减少不必要的碰撞检测
避免相邻 link 因模型接触被误判
提高规划效率

注意点：

注意点	说明
不要随意全禁用碰撞	否则避障规划失去意义
如果模型尺寸改了	需要重新生成自碰撞矩阵
如果 collision mesh 太粗糙	可能导致误判碰撞

---

7. Virtual Joints：配置虚拟关节

虚拟关节用于把机器人根 link 连接到世界坐标系。

固定底座机械臂通常配置为：

参数	示例
Virtual Joint Name	virtual_joint
Parent Frame	world
Child Link	base_link
Type	fixed

含义是：

world
    ↓ fixed virtual joint
base_link
    ↓
机械臂运动链

如果是移动机器人底盘，虚拟关节可能会使用 planar 或 floating。但固定机械臂一般用 fixed。

---

8. Planning Groups：配置规划组

规划组是 MSA 中最关键的一步。

MoveIt 不会默认知道“我要规划哪几个关节”。规划组就是告诉 MoveIt：

这一组 joint / link 构成一条可规划的机械臂

本项目中的规划组可以理解为：

参数	示例
Group Name	ik
Base Link	base_link
Tip Link	link5
Kinematic Solver	kdl_kinematics_plugin/KDLKinematicsPlugin

这表示：

MoveIt 对 base_link 到 link5 这条链进行运动规划

为什么规划组名字叫 ik？

因为后续 API 测试节点中使用了：

req.group_name = 'ik'

所以这里的名字必须和代码、RViz MotionPlanning 插件中的 Planning Group 保持一致。

如果 MSA 中规划组叫 arm，代码里却写 ik，MoveIt 会找不到规划组，规划请求会失败。

---

9. Kinematics：配置 IK 解算器

MSA 会根据 Planning Group 生成 kinematics.yaml。

默认常用 KDL：

ik:
  kinematics_solver: kdl_kinematics_plugin/KDLKinematicsPlugin
  kinematics_solver_search_resolution: 0.005
  kinematics_solver_timeout: 0.05

含义：

字段	说明
ik	规划组名称
kinematics_solver	当前规划组使用的 IK 插件
kinematics_solver_timeout	单次 IK 求解超时时间
kinematics_solver_search_resolution	数值搜索分辨率

如果要换成 TRAC-IK：

ik:
  kinematics_solver: trac_ik_kinematics_plugin/TRAC_IKKinematicsPlugin
  kinematics_solver_timeout: 0.05
  solve_type: Speed
  epsilon: 0.00001

注意：

kinematics.yaml 是 move_group 启动时加载的

所以修改 IK 插件后，必须：

colcon build
source install/setup.bash
ros2 launch four_dof_arm_moveit_config demo.launch.py

只改文件但不重启 move_group，新的 IK 配置不会生效。

---

10. Robot Poses：配置命名姿态

命名姿态是给一组关节值起名字。

常见姿态：

姿态名	作用
home	初始位置，通常所有关节为 0
pose_1	测试规划用的目标姿态

命名姿态会写入 SRDF。

后续可以在 RViz 中直接选择，也可以在代码里等价使用一组关节值。

概念上：

named target
    ↓
一组 joint values
    ↓
MoveIt 规划到该关节目标

注意：

命名姿态不是末端 pose。它本质上仍然是关节空间目标。

---

11. End Effectors 和 Passive Joints

如果只是单臂规划，没有夹爪或工具，可以不配置 End Effectors。

如果有夹爪，可以单独建一个 gripper planning group，再在 End Effectors 中把它挂到机械臂末端 link 上。

Passive Joints 用于声明“不主动规划但会被动运动”的关节。一般简单机械臂项目中可以不配置。

---

12. ROS 2 Controllers：配置 ros2_control 控制器

MoveIt 规划出来的是轨迹，但真正执行轨迹需要控制器。

在 ROS 2 中，常见执行链路是：

MoveIt RobotTrajectory
    ↓
JointTrajectoryController
    ↓
ros2_control
    ↓
真实硬件 / 仿真硬件 / mock hardware

控制器配置中需要保证：

项目	要求
控制器类型	通常是 joint_trajectory_controller/JointTrajectoryController
控制器关节列表	必须包含规划组里的所有运动关节
joint 顺序	建议和规划组、代码中的关节顺序一致
command interface	常用 position
state interface	至少需要 position

示例结构：

controller_manager:
  ros__parameters:
    update_rate: 100

    joint_state_broadcaster:
      type: joint_state_broadcaster/JointStateBroadcaster

    ik_controller:
      type: joint_trajectory_controller/JointTrajectoryController

ik_controller:
  ros__parameters:
    joints:
      - joint1
      - joint2
      - joint3
      - joint4
      - joint5
    command_interfaces:
      - position
    state_interfaces:
      - position
      - velocity

---

13. MoveIt Controllers：配置 MoveIt 到控制器的映射

moveit_controllers.yaml 用于告诉 move_group：

规划成功后，把轨迹发给哪个 FollowJointTrajectory action

示例：

moveit_controller_manager: moveit_simple_controller_manager/MoveItSimpleControllerManager

moveit_simple_controller_manager:
  controller_names:
    - ik_controller

  ik_controller:
    type: FollowJointTrajectory
    action_ns: follow_joint_trajectory
    default: true
    joints:
      - joint1
      - joint2
      - joint3
      - joint4
      - joint5

这里最容易出错的是控制器名字。

必须保证这些地方一致：

ros2_controllers.yaml 中的控制器名
moveit_controllers.yaml 中的控制器名
启动文件中加载的控制器名

例如都叫：

ik_controller

如果名字不一致，MoveIt 可能能规划成功，但执行阶段失败。

---

14. Configuration Files：生成配置包

最后在 MSA 的 Configuration Files 页面选择输出目录。

推荐命名：

<robot_name>_moveit_config

例如：

four_dof_arm_moveit_config

放到工作空间：

~/moveit_ws/src/four_dof_arm_moveit_config

点击：

Generate Package

生成后编译：

cd ~/moveit_ws
colcon build
source install/setup.bash

启动 demo：

ros2 launch four_dof_arm_moveit_config demo.launch.py

如果 RViz 中能看到机器人模型，并且 MotionPlanning 面板可以选择规划组，说明配置包基本可用。

---

15. MoveIt 配置包启动后的数据流

配置包生成后，运行 demo.launch.py 时，整体数据流是：

URDF / SRDF / YAML
    ↓
robot_state_publisher 发布 TF
    ↓
move_group 加载 RobotModel、PlanningScene、IK、OMPL、Controller
    ↓
RViz 或 API 发送规划请求
    ↓
如果是 pose 目标，先调用 IK
    ↓
OMPL 搜索可行路径
    ↓
生成 RobotTrajectory
    ↓
MoveItSimpleControllerManager 找到 ik_controller
    ↓
JointTrajectoryController 执行轨迹
    ↓
joint_state_broadcaster 发布 /joint_states
    ↓
RViz 根据 /joint_states + TF 更新显示

简化理解：

模型配置解决“机器人是什么”
规划组解决“规划哪几个关节”
IK 配置解决“pose 怎么变成 joint”
OMPL 解决“怎么从起点走到终点”
controller 配置解决“轨迹发给谁执行”

---

16. 常见问题和排查

16.1 MSA 打不开或 3D 窗口黑屏

优先检查：

echo $XDG_SESSION_TYPE

Ubuntu 24.04 下建议使用：

Ubuntu on Xorg

不要优先使用 Wayland。

16.2 RViz 中没有机器人模型

检查：

ros2 topic echo /robot_description
ros2 topic echo /joint_states
ros2 run tf2_tools view_frames

常见原因：

URDF 没有正确加载
robot_state_publisher 没启动
joint_state_broadcaster 没启动
TF 树断开
fixed frame 选错

16.3 RViz 有模型，但不能规划

检查：

Planning Group 是否选对
SRDF 中是否有对应 group
kinematics.yaml 中 group 名是否一致
joint_limits 是否合理
起点是否碰撞
目标是否超出关节范围

16.4 能规划，但不能执行

检查：

ros2 control list_controllers
ros2 action list | grep follow_joint_trajectory

重点看：

JointTrajectoryController 是否 active
moveit_controllers.yaml 控制器名是否正确
控制器 action namespace 是否正确
关节列表是否一致

16.5 pose 目标失败，但 joint/name 成功

这通常说明：

运动规划链路是通的
控制器执行链路是通的
问题集中在 IK 求解或目标位姿可达性

排查顺序：

确认 tip link 是否正确
确认 pose 的 frame_id 是否正确
确认目标是否超出工作空间
确认姿态约束是否过紧
换不同 seed 测试
对比 KDL / TRAC-IK / BioIK

16.6 修改 kinematics.yaml 后没有变化

原因通常是 move_group 没重启。

正确流程：

colcon build
source install/setup.bash
ros2 launch four_dof_arm_moveit_config demo.launch.py

MoveIt 的 IK 插件是在 move_group 启动时加载的，不是每次请求动态读取。

---

17. 配置时的关键一致性

MoveIt 配置最怕“名字不一致”。

需要重点检查：

名称	必须一致的位置
Planning Group	SRDF、kinematics.yaml、代码中的 group_name、RViz 选择项
Base Link	URDF 根链路、Virtual Joint、Planning Group
Tip Link	Planning Group、IK 请求中的 ik_link_name
Joint Names	URDF、SRDF、controller yaml、测试代码
Controller Name	ros2_controllers.yaml、moveit_controllers.yaml、启动文件
Frame ID	RViz Fixed Frame、pose 请求、TF 树

本项目中需要特别保持一致的是：

规划组：ik
规划链：base_link -> link5
控制器：ik_controller
目标末端：link5
参考坐标系：base_link

---

18. 总结

MSA 的本质是把一个已有机器人模型转化为 MoveIt 能使用的配置包。

完整配置链路可以总结为：

URDF / Xacro
    ↓
MSA 加载模型
    ↓
生成 SRDF、规划组、自碰撞矩阵、命名姿态
    ↓
配置 IK、OMPL、joint limits
    ↓
配置 ros2_control 和 MoveIt controller
    ↓
启动 demo.launch.py
    ↓
RViz / API 调用 move_group 进行规划执行

MSA 能解决的是 MoveIt 配置问题，但不替代 URDF 建模，也不替代控制器调试。

在 Ubuntu 24.04 上，最值得提前注意的是 Wayland 图形环境问题；在 MoveIt 配置本身，最值得反复检查的是规划组、link、joint、controller 名称的一致性。