文章目录Ubuntu 24.04 ROS 2 Jazzy 下使用 MoveIt Setup Assistant 配置机械臂1. MSA 是什么2. 前置环境3. Ubuntu 24.04 注意点Wayland 问题4. MSA 配置整体流程5. Start加载机器人模型6. Self-Collisions生成自碰撞矩阵7. Virtual Joints配置虚拟关节8. Planning Groups配置规划组9. Kinematics配置 IK 解算器10. Robot Poses配置命名姿态11. End Effectors 和 Passive Joints12. ROS 2 Controllers配置 ros2_control 控制器13. MoveIt Controllers配置 MoveIt 到控制器的映射14. Configuration Files生成配置包15. MoveIt 配置包启动后的数据流16. 常见问题和排查16.1 MSA 打不开或 3D 窗口黑屏16.2 RViz 中没有机器人模型16.3 RViz 有模型但不能规划16.4 能规划但不能执行16.5 pose 目标失败但 joint/name 成功16.6 修改 kinematics.yaml 后没有变化17. 配置时的关键一致性18. 总结Ubuntu 24.04 ROS 2 Jazzy 下使用 MoveIt Setup Assistant 配置机械臂本文记录一个机械臂 MoveIt 2 配置包的生成流程重点放在 MoveIt Setup AssistantMSA的概念、配置步骤和常见注意点。文中不展开真实 URDF 内容只说明配置思路。1. MSA 是什么MoveIt Setup Assistant简称 MSA是 MoveIt 官方提供的图形化配置工具。它的作用不是建模也不是写控制器而是根据已有的机器人模型生成 MoveIt 所需的配置包。可以把流程理解成URDF / Xacro 机器人模型 ↓ MoveIt Setup Assistant ↓ 生成 *_moveit_config 配置包 ↓ move_group 读取配置 ↓ RViz / API / 测试节点可以进行规划与执行MSA 主要生成或辅助生成这些内容配置文件作用*.srdfMoveIt 语义描述例如规划组、虚拟关节、命名姿态、自碰撞矩阵kinematics.yaml指定 IK 解算器例如 KDL、TRAC-IK、BioIKjoint_limits.yaml关节速度、加速度、位置限制ompl_planning.yamlOMPL 规划器配置moveit_controllers.yaml告诉 MoveIt 轨迹应该发给哪个控制器ros2_controllers.yamlros2_control 控制器配置demo.launch.py启动 move_group、RViz、robot_state_publisher 等节点2. 前置环境本文环境Ubuntu 24.04 ROS 2 Jazzy MoveIt 2安装 MoveIt 和 MSAsudoaptupdatesudoaptinstallros-jazzy-moveit ros-jazzy-moveit-setup-assistant加载 ROS 环境source/opt/ros/jazzy/setup.bash启动 MSAros2 run moveit_setup_assistant moveit_setup_assistant如果模型是 Xacro也可以先生成临时 URDF 再导入 MSAros2 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注销当前 Ubuntu 桌面会话。回到登录界面后先选择用户名。点击右下角齿轮图标。选择Ubuntu on Xorg。输入密码登录。重新打开终端再启动 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 / XorgMSA 只是读取模型不负责修复模型。如果模型本身 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 Namevirtual_jointParent FrameworldChild Linkbase_linkTypefixed含义是world ↓ fixed virtual joint base_link ↓ 机械臂运动链如果是移动机器人底盘虚拟关节可能会使用planar或floating。但固定机械臂一般用fixed。8. Planning Groups配置规划组规划组是 MSA 中最关键的一步。MoveIt 不会默认知道“我要规划哪几个关节”。规划组就是告诉 MoveIt这一组 joint / link 构成一条可规划的机械臂本项目中的规划组可以理解为参数示例Group NameikBase Linkbase_linkTip Linklink5Kinematic Solverkdl_kinematics_plugin/KDLKinematicsPlugin这表示MoveIt 对 base_link 到 link5 这条链进行运动规划为什么规划组名字叫ik因为后续 API 测试节点中使用了req.group_nameik所以这里的名字必须和代码、RViz MotionPlanning 插件中的 Planning Group 保持一致。如果 MSA 中规划组叫arm代码里却写ikMoveIt 会找不到规划组规划请求会失败。9. Kinematics配置 IK 解算器MSA 会根据 Planning Group 生成kinematics.yaml。默认常用 KDLik:kinematics_solver:kdl_kinematics_plugin/KDLKinematicsPluginkinematics_solver_search_resolution:0.005kinematics_solver_timeout:0.05含义字段说明ik规划组名称kinematics_solver当前规划组使用的 IK 插件kinematics_solver_timeout单次 IK 求解超时时间kinematics_solver_search_resolution数值搜索分辨率如果要换成 TRAC-IKik:kinematics_solver:trac_ik_kinematics_plugin/TRAC_IKKinematicsPluginkinematics_solver_timeout:0.05solve_type:Speedepsilon:0.00001注意kinematics.yaml 是 move_group 启动时加载的所以修改 IK 插件后必须colcon buildsourceinstall/setup.bash ros2 launch four_dof_arm_moveit_config demo.launch.py只改文件但不重启move_group新的 IK 配置不会生效。10. Robot Poses配置命名姿态命名姿态是给一组关节值起名字。常见姿态姿态名作用home初始位置通常所有关节为 0pose_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常用positionstate interface至少需要position示例结构controller_manager:ros__parameters:update_rate:100joint_state_broadcaster:type:joint_state_broadcaster/JointStateBroadcasterik_controller:type:joint_trajectory_controller/JointTrajectoryControllerik_controller:ros__parameters:joints:-joint1-joint2-joint3-joint4-joint5command_interfaces:-positionstate_interfaces:-position-velocity13. MoveIt Controllers配置 MoveIt 到控制器的映射moveit_controllers.yaml用于告诉move_group规划成功后把轨迹发给哪个 FollowJointTrajectory action示例moveit_controller_manager:moveit_simple_controller_manager/MoveItSimpleControllerManagermoveit_simple_controller_manager:controller_names:-ik_controllerik_controller:type:FollowJointTrajectoryaction_ns:follow_joint_trajectorydefault:truejoints:-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 buildsourceinstall/setup.bash启动 demoros2 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_TYPEUbuntu 24.04 下建议使用Ubuntu on Xorg不要优先使用 Wayland。16.2 RViz 中没有机器人模型检查ros2 topicecho/robot_description ros2 topicecho/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|grepfollow_joint_trajectory重点看JointTrajectoryController 是否 active moveit_controllers.yaml 控制器名是否正确 控制器 action namespace 是否正确 关节列表是否一致16.5 pose 目标失败但 joint/name 成功这通常说明运动规划链路是通的 控制器执行链路是通的 问题集中在 IK 求解或目标位姿可达性排查顺序确认 tip link 是否正确 确认 pose 的 frame_id 是否正确 确认目标是否超出工作空间 确认姿态约束是否过紧 换不同 seed 测试 对比 KDL / TRAC-IK / BioIK16.6 修改 kinematics.yaml 后没有变化原因通常是move_group没重启。正确流程colcon buildsourceinstall/setup.bash ros2 launch four_dof_arm_moveit_config demo.launch.pyMoveIt 的 IK 插件是在move_group启动时加载的不是每次请求动态读取。17. 配置时的关键一致性MoveIt 配置最怕“名字不一致”。需要重点检查名称必须一致的位置Planning GroupSRDF、kinematics.yaml、代码中的group_name、RViz 选择项Base LinkURDF 根链路、Virtual Joint、Planning GroupTip LinkPlanning Group、IK 请求中的ik_link_nameJoint NamesURDF、SRDF、controller yaml、测试代码Controller Nameros2_controllers.yaml、moveit_controllers.yaml、启动文件Frame IDRViz Fixed Frame、pose 请求、TF 树本项目中需要特别保持一致的是规划组ik 规划链base_link - link5 控制器ik_controller 目标末端link5 参考坐标系base_link18. 总结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 名称的一致性。