手把手 2 / 4
在 Gazebo 里从零搭一台六轴臂,让它听你的话
URDF → gz-sim → gz_ros2_control → MoveIt 2,一条链走通,约 6 小时
做完这件事,你手上会有
一条 6 轴臂在 Gazebo 里动起来,能被 MoveIt 2 规划并执行到指定位姿;换个末端、加个障碍都不用重来。
这是机械臂方向唯一必须亲手走一遍的链路。走通之后,任何一台陌生型号的臂,你都能在两天内接起来——因为流程完全一样,只有参数不同。
开工前
| 需要什么 | 版本 / 说明 |
|---|---|
| Ubuntu 24.04 + ROS 2 Jazzy | 官方配套 |
| Gazebo Harmonic(gz-sim 8) | ros-jazzy-ros-gz |
| gz_ros2_control | ros-jazzy-gz-ros2-control |
| MoveIt 2 | ros-jazzy-moveit |
目录
- 装环境:先确认版本能配上
- 建包:先定目录,后面不用挪文件
- 写 URDF:六个关节 + 惯性参数,一个都不能省
- 加 ros2_control 标签:让仿真认识你的关节
- 起 Gazebo,把机器人塞进去
- 加载控制器:先广播状态,再控轨迹
- 发第一条轨迹:让它真的动
- MoveIt Setup Assistant:生成配置,不要手写
- 在 RViz 里规划并执行
- 加相机与障碍:这才是「工程化」的开始
- 验收:不看界面,只看这四条
装环境:先确认版本能配上
ROS 2 Jazzy 官方配套的是 Gazebo Harmonic(gz-sim 8),别去装 Gazebo Classic,网上大半教程会把你带偏。四条命令装完,先验证再往下走。
sudo apt update
sudo apt install -y ros-jazzy-desktop ros-jazzy-ros-gz \
ros-jazzy-ros2-control ros-jazzy-ros2-controllers \
ros-jazzy-gz-ros2-control ros-jazzy-moveit ros-jazzy-xacro
gz sim --versions
ros2 pkg list | grep -E 'gz_ros2_control|moveit_core'看到这个就算过
`gz sim --versions` 打印出 8.x;两条 grep 都有输出。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| `gz: command not found` | 装的是 ros_gz 但没装 gz 本体 | `sudo apt install -y gz-harmonic`,或直接用 `ros2 run ros_gz_sim gz_sim` 启动 |
| gz 是 7.x(Garden) | 系统里残留旧版,PATH 先找到它 | `sudo apt remove gz-garden` 后重装;或固定用 `ros2 run ros_gz_sim gz_sim` |
建包:先定目录,后面不用挪文件
一个包放模型、配置、launch。目录一次分好:urdf 放 xacro,config 放控制器与 MoveIt 配置,launch 放启动文件,worlds 放场景。
mkdir -p ~/arm_ws/src && cd ~/arm_ws/src
ros2 pkg create --build-type ament_cmake arm6 \
--dependencies rclcpp urdf xacro
mkdir -p arm6/{urdf,config,launch,worlds}
cd ~/arm_ws && colcon build && source install/setup.bash看到这个就算过
colcon build 无报错;`ros2 pkg prefix arm6` 打印出 install 路径。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| `package not found` | 忘了 source | 每次新开终端都要 `source ~/arm_ws/install/setup.bash` |
写 URDF:六个关节 + 惯性参数,一个都不能省
先写到「能被 gz 加载」为止:base_link 固定,六个 revolute 关节,每个 link 必须有 inertial(质量 + 惯量),否则 gz 里会飘、会穿模。惯量用盒子公式近似就够,误差在 20% 以内不影响控制调试。
cat > ~/arm_ws/src/arm6/urdf/arm6.urdf.xacro <<'EOF'
<?xml version="1.0"?>
<robot name="arm6" xmlns:xacro="http://ros.org/wiki/xacro">
<xacro:property name="PI" value="3.14159265358979"/>
<link name="base_link">
<visual><geometry><cylinder radius="0.08" length="0.06"/></geometry></visual>
<collision><geometry><cylinder radius="0.08" length="0.06"/></geometry></collision>
<inertial><mass value="2.0"/>
<inertia ixx="0.0060" iyy="0.0060" izz="0.0064" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<!-- link1: 竖直段 0.15 m -->
<joint name="j1" type="revolute">
<parent link="base_link"/><child link="link1"/>
<origin xyz="0 0 0.06" rpy="0 0 0"/>
<axis xyz="0 0 1"/>
<limit lower="-3.14" upper="3.14" effort="80" velocity="2.0"/>
<dynamics damping="1.0" friction="0.5"/>
</joint>
<link name="link1">
<visual><origin xyz="0 0 0.075"/><geometry><cylinder radius="0.05" length="0.15"/></geometry></visual>
<collision><origin xyz="0 0 0.075"/><geometry><cylinder radius="0.05" length="0.15"/></geometry></collision>
<inertial><origin xyz="0 0 0.075"/><mass value="1.5"/>
<inertia ixx="0.0036" iyy="0.0036" izz="0.0019" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<!-- link2: 大臂 0.45 m -->
<joint name="j2" type="revolute">
<parent link="link1"/><child link="link2"/>
<origin xyz="0 0 0.15" rpy="0 0 0"/>
<axis xyz="0 1 0"/>
<limit lower="-2.0" upper="2.0" effort="120" velocity="1.8"/>
<dynamics damping="1.2" friction="0.6"/>
</joint>
<link name="link2">
<visual><origin xyz="0 0 0.225"/><geometry><box size="0.06 0.06 0.45"/></geometry></visual>
<collision><origin xyz="0 0 0.225"/><geometry><box size="0.06 0.06 0.45"/></geometry></collision>
<inertial><origin xyz="0 0 0.225"/><mass value="3.0"/>
<inertia ixx="0.0513" iyy="0.0513" izz="0.0018" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<!-- link3: 小臂 0.40 m -->
<joint name="j3" type="revolute">
<parent link="link2"/><child link="link3"/>
<origin xyz="0 0 0.45" rpy="0 0 0"/>
<axis xyz="0 1 0"/>
<limit lower="-2.6" upper="2.6" effort="80" velocity="2.2"/>
<dynamics damping="0.9" friction="0.4"/>
</joint>
<link name="link3">
<visual><origin xyz="0 0 0.20"/><geometry><box size="0.05 0.05 0.40"/></geometry></visual>
<collision><origin xyz="0 0 0.20"/><geometry><box size="0.05 0.05 0.40"/></geometry></collision>
<inertial><origin xyz="0 0 0.20"/><mass value="2.0"/>
<inertia ixx="0.0270" iyy="0.0270" izz="0.00083" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<!-- 腕部三轴:j4 绕 z、j5 绕 y、j6 绕 z -->
<joint name="j4" type="revolute">
<parent link="link3"/><child link="link4"/>
<origin xyz="0 0 0.40" rpy="0 0 0"/><axis xyz="0 0 1"/>
<limit lower="-3.14" upper="3.14" effort="30" velocity="3.0"/>
</joint>
<link name="link4">
<visual><origin xyz="0 0 0.04"/><geometry><cylinder radius="0.04" length="0.08"/></geometry></visual>
<collision><origin xyz="0 0 0.04"/><geometry><cylinder radius="0.04" length="0.08"/></geometry></collision>
<inertial><origin xyz="0 0 0.04"/><mass value="1.2"/>
<inertia ixx="0.0011" iyy="0.0011" izz="0.0010" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<joint name="j5" type="revolute">
<parent link="link4"/><child link="link5"/>
<origin xyz="0 0 0.08" rpy="0 0 0"/><axis xyz="0 1 0"/>
<limit lower="-2.2" upper="2.2" effort="20" velocity="3.0"/>
</joint>
<link name="link5">
<visual><origin xyz="0 0 0.03"/><geometry><cylinder radius="0.035" length="0.06"/></geometry></visual>
<collision><origin xyz="0 0 0.03"/><geometry><cylinder radius="0.035" length="0.06"/></geometry></collision>
<inertial><origin xyz="0 0 0.03"/><mass value="0.8"/>
<inertia ixx="0.0005" iyy="0.0005" izz="0.0005" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
<joint name="j6" type="revolute">
<parent link="link5"/><child link="tool0"/>
<origin xyz="0 0 0.06" rpy="0 0 0"/><axis xyz="0 0 1"/>
<limit lower="-3.14" upper="3.14" effort="10" velocity="3.0"/>
</joint>
<link name="tool0">
<visual><geometry><sphere radius="0.015"/></geometry></visual>
<collision><geometry><sphere radius="0.015"/></geometry></collision>
<inertial><mass value="0.3"/>
<inertia ixx="2.7e-5" iyy="2.7e-5" izz="2.7e-5" ixy="0" ixz="0" iyz="0"/>
</inertial>
</link>
</robot>
EOF
xacro ~/arm_ws/src/arm6/urdf/arm6.urdf.xacro > /tmp/arm6.urdf
echo $?看到这个就算过
最后打印 0,/tmp/arm6.urdf 里有 7 个 link、6 个 joint。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| xacro 报 `Invalid parameter` | xacro 里用了未定义的属性 | 属性必须写在最前面;<xacro:property> 在第一次引用之前 |
| gz 里臂松垮垮地栽倒 | 某个 link 缺 inertial | 每个 link 都要有 <inertial>;空着会按 0 质量处理 |
加 ros2_control 标签:让仿真认识你的关节
在 xacro 末尾加两段:一段声明每个关节的 command/state 接口,一段挂上 gz_ros2_control 插件并指向控制器配置文件。插件名写错是最常见的失败点。
cat >> ~/arm_ws/src/arm6/urdf/arm6.urdf.xacro <<'EOF'
<ros2_control name="arm6_system" type="system">
<hardware>
<plugin>gz_ros2_control/GazeboSimSystem</plugin>
</hardware>
<xacro:macro name="jif" params="jname">
<joint name="${jname}">
<command_interface name="position"/>
<state_interface name="position"/>
<state_interface name="velocity"/>
<state_interface name="effort"/>
</joint>
</xacro:macro>
<xacro:jif jname="j1"/><xacro:jif jname="j2"/><xacro:jif jname="j3"/>
<xacro:jif jname="j4"/><xacro:jif jname="j5"/><xacro:jif jname="j6"/>
</ros2_control>
<gazebo>
<plugin filename="gz_ros2_control-system"
name="gz_ros2_control::GazeboSimROS2ControlPlugin">
<parameters>$(find arm6)/config/controllers.yaml</parameters>
</plugin>
</gazebo>
</robot>
EOF
cat > ~/arm_ws/src/arm6/config/controllers.yaml <<'EOF'
controller_manager:
ros__parameters:
update_rate: 500
joint_state_broadcaster:
type: joint_state_broadcaster/JointStateBroadcaster
arm_controller:
type: joint_trajectory_controller/JointTrajectoryController
arm_controller:
ros__parameters:
joints: [j1, j2, j3, j4, j5, j6]
command_interfaces: [position]
state_interfaces: [position, velocity]
allow_partial_joints_goal: false
constraints:
goal_time: 0.5
EOF看到这个就算过
两个文件都在;xacro 仍然能展开(`xacro ... | wc -l` 有输出)。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| 启动后 `No hardware components found` | plugin 标签里的 class 名写错 | 硬件插件写 `gz_ros2_control/GazeboSimSystem`,系统插件写 `gz_ros2_control::GazeboSimROS2ControlPlugin`,两处不一样 |
| 控制器加载了但关节不动 | command_interface 写成了 velocity,而控制器发 position | 两者必须一致;直接看 `ros2 control list_hardware_interfaces` 的 available 列 |
起 Gazebo,把机器人塞进去
先起一个空世界,再用 create 把 URDF 变成仿真对象。世界一开始用空的,跑通再加地平面以外的道具。
# 终端 1
ros2 run ros_gz_sim gz_sim -- -r -v 3 empty.sdf
# 终端 2(等 gz 窗口出来再执行)
ros2 run ros_gz_sim create -file /tmp/arm6.urdf -name arm6 -z 0.02
# 终端 3
ros2 topic list | grep -E 'clock|joint_states'
ros2 topic echo /joint_states --once看到这个就算过
gz 窗口里出现一台立起来的六轴臂;/joint_states 里六个关节位置都有数(约 0)。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| 臂悬在空中或陷进地面 | create 的 -z 没给或 base_link 原点不在底部 | 加 `-z 0.03`;或把 base_link 的几何原点抬到 z=0.03 |
| 没有 /joint_states | gz_ros2_control 插件没被加载 | 看 gz 终端有没有 `Loaded plugin`;没有就是 URDF 里 <gazebo> 段被 xacro 丢掉了 |
加载控制器:先广播状态,再控轨迹
两个控制器有先后:joint_state_broadcaster 必须先起来,否则 JTC 拿不到反馈。用 spawner 依次拉起,并检查 update 周期有没有 overrun。
ros2 run controller_manager spawner joint_state_broadcaster \
--controller-manager /controller_manager
ros2 run controller_manager spawner arm_controller \
--controller-manager /controller_manager
ros2 control list_controllers
ros2 control list_hardware_interfaces看到这个就算过
两个控制器都是 `active`;六个关节的 position/velocity/effort 接口都在 available 列。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| `Controller manager not available` | 仿真里插件没起来 | 确认 gz 端打印了 controller_manager 的初始化日志;没打印就是插件参数路径不对($(find arm6) 没被解析) |
| JTC 起来就报 `No state interface` | state_interface 名称与 URDF 不一致 | JTC 的 state_interfaces 必须是 URDF 里声明过的子集 |
发第一条轨迹:让它真的动
不写代码,直接用 action 发一条 3 秒的轨迹。这一步通过,说明「规划—控制—执行」的通道是通的,后面 MoveIt 只是换个上游。
ros2 action send_goal /arm_controller/follow_joint_trajectory \
control_msgs/action/FollowJointTrajectory "{
trajectory: {
joint_names: [j1,j2,j3,j4,j5,j6],
points: [
{positions: [0.0, -0.4, 0.8, 0.0, 0.6, 0.0], time_from_start: {sec: 3}}
]
}
}" --feedback看到这个就算过
臂在 3 秒内平滑移到目标位姿,action 返回 SUCCEEDED,没有超调抖动。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| 动作到了但中途一顿一顿 | update_rate 500 但 gz 的物理步长/RTF 跟不上 | 看 gz 终端 RTF;低于 0.9 就把世界里的无关模型删掉,或 `-s` 无界面跑 |
| 返回 INVALID_GOAL | 轨迹点的 positions 数量与 joints 数量不一致 | 6 个关节必须 6 个数,缺一个就整条拒绝 |
MoveIt Setup Assistant:生成配置,不要手写
这一步只做四件事:载入 URDF、生成自碰撞矩阵、建 planning group(base_link → tool0 的链)、选 IK 插件。其余默认,先跑通再优化。
ros2 launch moveit_setup_assistant setup_assistant.launch.py看到这个就算过
界面上四步都变绿,最后生成 ~/arm_ws/src/arm6_moveit_config,里面有 SRDF 与 launch。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| 自碰撞矩阵生成 0 个样本 | URDF 里 link 名字对不上或模型没惯性 | 先确认 `check_urdf /tmp/arm6.urdf` 通过 |
| 找不到 tool0 | planning group 的末端没选链的最后一个 link | group 类型选 Kinematic Chain,base 选 base_link,tip 选 tool0 |
在 RViz 里规划并执行
同时起 move_group、RViz 与之前的 gz 仿真。RViz 里拖末端到目标,点 Plan & Execute——配置正确的话,gz 里的臂会跟着动。
ros2 launch arm6_moveit_config demo.launch.py \
use_sim_time:=true
# 若 demo.launch 自带假控制器,另开一个终端把它换成 gz 的 arm_controller
ros2 control list_controllers看到这个就算过
RViz 里规划出彩色轨迹,Execute 后 gz 中的臂同步运动,末端到达目标位姿。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| 规划成功但 gz 里不动 | MoveIt 连的是假控制器(fake)而不是 arm_controller | 把 moveit 的 controller 名改成 arm_controller,或关掉 fake 执行的 launch 参数 |
| 规划总失败(0 解) | IK 插件 KDL 在该姿态无解 | 装 `ros-jazzy-trac-ik-kinematics-plugin`,在 SRDF 里换成 TRAC-IK 再试 |
| 执行到一半超时 | goal_time 太紧或驱动器跟不上 | 把 JTC 的 constraints.goal_time 放宽,同时核对 trajectory 的 velocity 上限 |
加相机与障碍:这才是「工程化」的开始
空场景里规划成功不算数。加一个箱子和一台深度相机,让 MoveIt 的 planning scene 里有真实障碍,再规划一次。
# 在 world 里加一个箱子(或临时用 gz service 生成)
ros2 run ros_gz_sim create -world empty \
-name box -x 0.5 -y 0.2 -z 0.15 \
-geometry 'box' -size 0.2,0.2,0.3 -static
# URDF 里加深度相机(gz-sensors 插件)
# 然后把点云桥接进 ROS 2
ros2 run ros_gz_bridge parameter_bridge \
/depth/points@sensor_msgs/msg/PointCloud2[gz.msgs.PointCloudPacked看到这个就算过
RViz 里能看到箱子与点云,末端绕开箱子到达目标;清掉箱子后能走直线。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| 点云在 RViz 里错位 | 相机 link 的 tf 没发布 | 加 robot_state_publisher,或补 static_transform_publisher |
| MoveIt 看不见箱子 | planning scene 没接 octomap 或没加 collision object | 先手动加一个 CollisionObject 验证链路,再接点云 |
验收:不看界面,只看这四条
关掉 RViz,用命令行复现一遍。能不看界面判断系统状态,才算真的会了。
ros2 control list_controllers # 两个 active
ros2 topic hz /joint_states # 接近 500 Hz
ros2 topic echo /controller_manager/... 2>/dev/null | head -3 # 无 overrun
ros2 service call /compute_ik moveit_msgs/srv/GetPositionIK \
'{ik_request: {group_name: arm, ik_link_name: tool0}}'看到这个就算过
四条都能跑通,且能解释 overrun 为什么是 0——因为 read()/write() 里没有分配、没有打印、没有等待。
卡住了
| 症状 | 多半是这个原因 | 怎么办 |
|---|---|---|
| joint_states 只有 100Hz 左右 | gz 物理步长或 update_rate 与预期不符 | update_rate 是控制器频率,gz 的 max_step_size 决定上限;两者要匹配 |
验收清单
不看界面、不翻聊天记录,能独立完成下面这几条,这篇教程才算真的过了。
- 换一个末端(夹爪),只改 URDF 与 SRDF,不动控制器与 launch,30 分钟内能重新规划执行
- 能把 6 个关节的 effort 限制改成真实电机的一半,说清哪些参数会跟着变
- 能指着 gz 终端里的 RTF 说出这个数字低时先查什么