机器人入行指南
实践/手把手/在 Gazebo 里从零搭一台六轴臂,让它听你的话

手把手 2 / 4

在 Gazebo 里从零搭一台六轴臂,让它听你的话

URDF → gz-sim → gz_ros2_control → MoveIt 2,一条链走通,约 6 小时

约 6–8 h11 步需要会基本 Linux 命令;ROS 2 用过一点点就够

数学:三角函数与矩阵(数学桥 T1)编程:会命令行与基本 Linux硬件:Linux 电脑(Ubuntu 24.04)

做完这件事,你手上会有

一条 6 轴臂在 Gazebo 里动起来,能被 MoveIt 2 规划并执行到指定位姿;换个末端、加个障碍都不用重来。

这是机械臂方向唯一必须亲手走一遍的链路。走通之后,任何一台陌生型号的臂,你都能在两天内接起来——因为流程完全一样,只有参数不同。

开工前

需要什么版本 / 说明
Ubuntu 24.04 + ROS 2 Jazzy官方配套
Gazebo Harmonic(gz-sim 8)ros-jazzy-ros-gz
gz_ros2_controlros-jazzy-gz-ros2-control
MoveIt 2ros-jazzy-moveit

目录

  1. 装环境:先确认版本能配上
  2. 建包:先定目录,后面不用挪文件
  3. 写 URDF:六个关节 + 惯性参数,一个都不能省
  4. 加 ros2_control 标签:让仿真认识你的关节
  5. 起 Gazebo,把机器人塞进去
  6. 加载控制器:先广播状态,再控轨迹
  7. 发第一条轨迹:让它真的动
  8. MoveIt Setup Assistant:生成配置,不要手写
  9. 在 RViz 里规划并执行
  10. 加相机与障碍:这才是「工程化」的开始
  11. 验收:不看界面,只看这四条
建模URDF/Xacro + 惯量仿真世界Gazebo 插件 + 物理引擎控制器ros2_control 轨迹执行验收每步给预期产物本篇 11 步每步都有「应该看到什么」——卡住就对照,不用猜
01

装环境:先确认版本能配上

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`
02

建包:先定目录,后面不用挪文件

一个包放模型、配置、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`
03

写 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 质量处理
04

加 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 列
05

起 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_statesgz_ros2_control 插件没被加载看 gz 终端有没有 `Loaded plugin`;没有就是 URDF 里 <gazebo> 段被 xacro 丢掉了
06

加载控制器:先广播状态,再控轨迹

两个控制器有先后: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 里声明过的子集
07

发第一条轨迹:让它真的动

不写代码,直接用 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 个数,缺一个就整条拒绝
08

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` 通过
找不到 tool0planning group 的末端没选链的最后一个 linkgroup 类型选 Kinematic Chain,base 选 base_link,tip 选 tool0
09

在 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 上限
10

加相机与障碍:这才是「工程化」的开始

空场景里规划成功不算数。加一个箱子和一台深度相机,让 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 验证链路,再接点云
11

验收:不看界面,只看这四条

关掉 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 决定上限;两者要匹配

验收清单

不看界面、不翻聊天记录,能独立完成下面这几条,这篇教程才算真的过了。

接着学

其他教程