1. 为什么先用 ROS2 + Gazebo Classic 跑通差速 AGV
ROS2 与 Gazebo Classic 是机器人方向最常用的一套代码开发工具。我见过太多人一上来就焊底盘、接编码器,结果连“车往哪边转”都没对齐,烧了两块驱动板才回头补仿真。这套工具链把试错成本压到最低:模型用 URDF/Xacro 描述,运动能力靠一段插件参数给出来,动不了就改字段,不用动烙铁。你要做的是一台两轮差速、带万向轮的 AGV,能在仿真里被键盘遥控,并且跑出方向正确的里程计。它适合刚接触 ROS2、手上还没有实车、或者实车调不动想先排除算法问题的从业者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 搭 URDF/Xacro:把轮距 0.3、轮径 0.1 写进模型
差分底盘的运动学其实只有两个几何量:两轮中心距 wheel_separation 和轮子直径 wheel_diameter。Gazebo 的差分驱动插件后面所有速度换算,都是拿这两个数当分母、分子算出来的。所以建模阶段真正要较真的不是外观,而是这两个数必须和插件里填的完全一致——差 1 厘米,直行就会慢慢画弧,这是后面排查章节反复要回来对账的地方。
2.1 link 与 joint 的父子关系先理清
一个最小可跑的 AGV 只需要四个 link:base_link 作为车体基准,left_wheel_link 与 right_wheel_link 挂在左右两侧,再加一个前向或后向的 caster_link 当支撑点。关节类型上,两个驱动轮必须是 continuous(可以整圈无限旋转),万向轮用 fixed 或者低摩擦的 continuous 都行。很多人在这里翻车,是把驱动轮写成了 revolute 并给了上下限,结果轮子转到 ±180° 就卡死,车在原地抽一下就不动了。
驱动轮挂在 base_link 下面,origin 的 y 分量分别取 +wheel_separation/2 和 -wheel_separation/2,这一步决定了左右轮到底在哪一侧。左右写反了,车会朝着与预期相反的方向转,而且 odom 的角速度符号也是反的,后面用键盘控制时会觉得“怎么按左转却往右拐”。
2.2 Xacro 参数化:一处改,处处同步
我把几何量全部提到文件头部用 xacro:property 定义,这样 URDF 和插件参数可以共享同一套数字来源,避免手工抄两遍抄错。下面是我每次新建模型时用的骨架:
xml复制<?xml version="1.0"?>
<robot name="agv" xmlns:xacro="http://ros.org/wiki/xacro">
<!-- 几何量集中在这里,改一处即可 -->
<xacro:property name="wheel_separation" value="0.3"/>
<xacro:property name="wheel_diameter" value="0.1"/>
<xacro:property name="wheel_radius" value="${wheel_diameter/2}"/>
<link name="base_link">
<visual>
<geometry><box size="0.4 0.3 0.1"/></geometry>
</visual>
<collision>
<geometry><box size="0.4 0.3 0.1"/></geometry>
</collision>
</link>
<link name="left_wheel_link">
<visual>
<geometry><cylinder radius="${wheel_radius}" length="0.04"/></geometry>
</visual>
<collision>
<geometry><cylinder radius="${wheel_radius}" length="0.04"/></geometry>
</collision>
</link>
<!-- 右轮同理,此处省略重复的 visual/collision -->
<link name="right_wheel_link"/>
<!-- 驱动轮:continuous 才能整圈无限转 -->
<joint name="left_wheel_joint" type="continuous">
<parent link="base_link"/>
<child link="left_wheel_link"/>
<origin xyz="0 ${wheel_separation/2} 0" rpy="${-pi/2} 0 0"/>
<axis xyz="0 0 1"/>
</joint>
<joint name="right_wheel_joint" type="continuous">
<parent link="base_link"/>
<child link="right_wheel_link"/>
<origin xyz="0 ${-wheel_separation/2} 0" rpy="${-pi/2} 0 0"/>
<axis xyz="0 0 1"/>
</joint>
<link name="caster_link"/>
<joint name="caster_joint" type="fixed">
<parent link="base_link"/>
<child link="caster_link"/>
<origin xyz="0.15 0 -0.05"/>
</joint>
</robot>
这段代码里有三个容易看漏的点。第一,wheel_radius 是从 wheel_diameter 派生出来的,圆柱几何体用半径、插件用直径,两套单位混着用最容易错,所以我干脆只保留直径这一个源头。第二,圆柱默认轴向是 z,而车轮要绕 y 轴滚,因此 origin 里先给 rpy="-pi/2 0 0" 把圆柱放倒,再用 axis xyz="0 0 1" 声明旋转轴——注意这个 axis 是在关节自身坐标系里表达的,不是世界坐标系,放倒之后 z 轴正好指向车的横向。第三,万向轮用 fixed 只是让它跟着车体走,如果你希望它在仿真里真正承重并滚动,需要改成低摩擦的 continuous,否则车体前部会悬空、底盘姿态发飘。
参数改法很直接:实车轮距量出来是 0.28 米,就把 wheel_separation 改成 0.28,插件里的同名参数一起改,别只改一处。轮径 0.1 米对应的半径是 0.05,圆柱长度 0.04 是轮宽,这个值不影响运动学,只影响视觉和碰撞体积。改完用 xacro agv.urdf.xacro > agv.urdf 展开一次,确认没有语法报错再进下一步——Xacro 的报错信息经常只给行号不给原因,早展开早发现。
3. 配 diff_drive 插件:libgazebo_ros_diff_drive.so 的参数逐项过
模型只描述“长什么样”,能不能动取决于 Gazebo 插件。差速底盘的标准做法是挂 libgazebo_ros_diff_drive.so,它负责两件事:订阅 cmd_vel 把线速度、角速度分解成左右轮的目标转速;读取左右轮的关节位置,反算出 odom 里程计并广播 TF。这两件事都依赖你在插件里填的参数,填错任何一项,现象都不是报错而是“能动但不对”,排查成本最高。
3.1 插件配置的完整写法
下面这份配置是我在多次调试后固定下来的版本,字段顺序不重要,但字段名一个都不能错:
xml复制<gazebo>
<plugin name="diff_drive" filename="libgazebo_ros_diff_drive.so">
<ros>
<namespace>/agv</namespace>
</ros>
<left_joint>left_wheel_joint</left_joint>
<right_joint>right_wheel_joint</right_joint>
<wheel_separation>0.3</wheel_separation>
<wheel_diameter>0.1</wheel_diameter>
<max_wheel_torque>20</max_wheel_torque>
<max_wheel_acceleration>1.0</max_wheel_acceleration>
<command_topic>cmd_vel</command_topic>
<odometry_topic>odom</odometry_topic>
<odometry_frame>odom</odometry_frame>
<robot_base_frame>base_link</robot_base_frame>
</plugin>
</gazebo>
逻辑上,left_joint / right_joint 必须和 URDF 里 <joint name="..."> 的字符串完全一致,包括下划线,不能写成 left_wheel 这种省略形式;插件是按名字去模型里查关节的,查不到就静默跳过,表现出来就是“车有质量、有碰撞,但推它才动,发指令没反应”。wheel_separation 与 wheel_diameter 要和第 2 章 Xacro 里的属性值逐位对齐,这是运动学换算的唯一依据。
max_wheel_torque 给的是每个轮子的力矩上限,单位是牛·米。设太小,车在仿真里起步肉、爬个小坡就停;设太大,速度阶跃时轮子会瞬间打滑,odom 跟着抖。20 这个量级对一台几十厘米见方的小车够用,实车换成大轮毂电机时要按实际扭矩往上调。max_wheel_acceleration 限制的是轮子角加速度,单位是 rad/s²,它的作用是把 cmd_vel 的阶跃变成斜坡——键盘遥控按一下就是一整格速度,没有这个限制,车会瞬间窜出去,视觉上和物理上都很假。1.0 意味着从静止到满速需要一段可见的加速过程,调大更灵敏,调小更“重”。
3.2 话题、坐标系与命名空间
command_topic 和 odometry_topic 填的是相对名字,最终话题会被 <namespace> 拼成 /agv/cmd_vel 和 /agv/odom。这个设计在多机器人场景下很有用,但单机调试时容易被忽略:你在终端里 ros2 topic pub /cmd_vel 发指令毫无反应,因为插件根本不在根命名空间下听。要么把 namespace 留空,要么发指令时老老实实带上 /agv 前缀,我一般选后者,因为后面接导航栈时多机扩展不用返工。
odometry_frame 对应里程计的父坐标系,通常是 odom;robot_base_frame 对应子坐标系,必须是模型里的 base_link。这两个名字会和 robot_state_publisher 发布的关节 TF 拼在一起,构成 odom → base_link → 各轮 的完整树。如果 robot_base_frame 写成了 URDF 里不存在的名字,TF 树会断在中间,RViz 里模型能显示但位置不更新,ros2 run tf2_tools view_frames 一看就少一截。参数对照可以按下面这张表过一遍:
| 参数 | 作用 | 常见错法 |
|---|---|---|
| left_joint / right_joint | 绑定驱动轮关节名 | 与 URDF 名字不一致,插件静默失效 |
| wheel_separation | 两轮中心距,速度分解的分母 | 与模型不符,直行画弧 |
| wheel_diameter | 轮径,角速度换算依据 | 填成半径,速度差一倍 |
| max_wheel_torque | 单轮力矩上限 | 过小爬坡停转,过大起步打滑 |
| max_wheel_acceleration | 轮角加速度上限 | 过大导致阶跃窜车 |
| command_topic | 速度指令订阅话题 | 忽略 namespace 导致收不到 |
| odometry_frame / robot_base_frame | 里程计 TF 父子坐标系 | 名字不存在导致 TF 树断开 |
4. 串启动文件与键盘控制:car_gazebo.launch.py 怎么拆
模型和插件都齐了,还差一个把 Gazebo、机器人状态发布、模型生成三件事串起来的启动文件。ROS2 的 launch 用 Python 写,好处是可以直接调 get_package_share_directory 拿路径,不用在 XML 里手拼绝对路径。这一步配错,现象往往是“Gazebo 起来了,但场景里空空如也”,比参数错更好排查。
4.1 launch 文件的三段结构
python复制# car_gazebo.launch.py
from launch import LaunchDescription
from launch_ros.actions import Node
from launch.actions import IncludeLaunchDescription
from launch.launch_description_sources import PythonLaunchDescriptionSource
import os
from ament_index_python.packages import get_package_share_directory
def generate_launch_description():
pkg_path = get_package_share_directory('agv_description')
# 第一段:把 gazebo_ros 自带的启动文件包进来,负责起 gzserver/gzclient
gazebo = IncludeLaunchDescription(
PythonLaunchDescriptionSource([
os.path.join(get_package_share_directory('gazebo_ros'), 'launch', 'gazebo.launch.py')
])
)
# 第二段:从 robot_description 话题取模型,生成到场景里,实体名 agv
spawn_entity = Node(
package='gazebo_ros',
executable='spawn_entity.py',
arguments=['-topic', 'robot_description', '-entity', 'agv'],
output='screen'
)
# 第三段:发布关节 TF,并强制使用仿真时间
robot_state_publisher = Node(
package='robot_state_publisher',
executable='robot_state_publisher',
name='robot_state_publisher',
output='screen',
parameters=[{'use_sim_time': True}]
)
return LaunchDescription([
gazebo,
robot_state_publisher,
spawn_entity,
])
第一段用 IncludeLaunchDescription 复用 gazebo_ros 的官方启动文件,而不是自己写 ExecuteProcess 去调 gzserver,原因是官方文件里已经处理好了资源路径、插件路径这些环境变量,自己起很容易缺 GAZEBO_PLUGIN_PATH 导致插件加载失败。第二段 spawn_entity.py 的关键是 -topic robot_description:它订阅这个话题拿 URDF 字符串,所以你得保证有节点在发布它(通常由 robot_state_publisher 从参数读入后转发)。-entity agv 是场景里的模型名,重复启动同名实体会报“already exists”,改个名或者先删掉旧实体就行。
第三段的 use_sim_time: True 是血泪经验:Gazebo 用的是自己的仿真时钟,节点如果用系统墙钟,odom 的时间戳会和 TF 对不上,RViz 里模型疯狂闪烁或者干脆不显示。所有参与仿真的节点都要开这个开关,漏一个就会出现“有的数据正常、有的数据卡住”的玄学现象。
4.2 键盘控制与话题对接
模型生成之后,用键盘遥控只需要一个节点,它把按键转成 geometry_msgs/Twist 发到 cmd_vel:
bash复制# 终端 A:启动仿真
ros2 launch agv_description car_gazebo.launch.py
# 终端 B:键盘遥控,话题重映射到插件监听的命名空间
ros2 run teleop_twist_keyboard teleop_twist_keyboard \
--ros-args -r cmd_vel:=/agv/cmd_vel
-r cmd_vel:=/agv/cmd_vel 是重映射语法,左边是节点默认发布的话题,右边是插件实际订阅的话题,两边必须对上。因为第 3 章里我们把 namespace 设成了 /agv,插件听的是 /agv/cmd_vel,而 teleop_twist_keyboard 默认发到根命名空间的 /cmd_vel,不做重映射就是石沉大海。如果你在插件里干脆没写 namespace,那这条重映射也可以省掉,但建议统一成带前缀的写法,接导航时省事。
键盘节点的按键含义是固定的:i 前进、, 后退、j 左转、l 右转、k 急停,q/z 调最大速度。按下 i 之后车没动,先别怀疑模型,去终端 B 看它有没有打印速度值,再看 ros2 topic echo /agv/odom 有没有数据——两个都有,问题就在插件参数;只有一个,问题在话题对接。
5. 避坑排查:车不动、跑偏、odom 乱跳的五种现场
这一章是我调试过程中真实踩过的坑,按“现象 → 原因 → 解决”整理。差分 AGV 的故障有个共同特点:几乎都不报错,全靠现象反推,所以现象描述得越具体,定位越快。
5.1 发指令车不动,或者动起来方向反了
现象:teleop_twist_keyboard 按 i 有速度打印,但车纹丝不动;或者按 j 左转,车却往右拐。
原因:前者通常是 left_joint / right_joint 的名字和 URDF 对不上,插件查不到关节就静默不驱动;后者是左右轮的 origin 的 y 分量写反了,或者左右关节名互换。还有一种隐蔽情况:轮子被写成了 revolute 且带角度上下限,转过一点就顶到限位。
解决:先把 URDF 展开后搜 joint name=,逐个和插件里的字符串比对;再检查 <origin xyz="0 ±wheel_separation/2 0"> 的正负号,约定右侧为负、左侧为正。轮子类型统一改成 continuous。确认后重启 Gazebo,因为插件参数是加载时读的,改完不重启不生效。
5.2 直行跑偏,越走越歪
现象:按住前进不放,车走出一段弧线,odom 的 y 值持续单边增长。
原因:wheel_separation 与模型实际轮距不一致,或者 wheel_diameter 填成了半径。差分运动学里,直线行驶要求左右轮线速度相等,而这个换算依赖轮径;转向角速度依赖轮距。任一处偏差都会让“直行”变成“微弯”。
解决:把 Xacro 里的 wheel_separation、wheel_diameter 和插件里的两个同名参数对齐到小数点后三位。改完做一次直线测试:发一个固定线速度、角速度为零的指令,看 odom 的 y 是否保持在零附近。这一步别偷懒,轮距差两厘米,跑十米就能偏出半米。
5.3 odom 数据乱跳或 TF 树断开
现象:RViz 里模型闪烁、位置不更新,ros2 run tf2_tools view_frames 生成的树里 odom 和 base_link 之间没有连线。
原因:一是 robot_base_frame 填了 URDF 里不存在的名字,TF 断在中间;二是 use_sim_time 没开,odom 的时间戳用的是墙钟,和仿真时钟对不上;三是 odometry_frame 和 robot_base_frame 写成了同一个名字,父子自环。
解决:robot_base_frame 必须等于 URDF 里的根 link,一般是 base_link;odometry_frame 用 odom,两者不能相同。所有节点补上 use_sim_time: True,包括 robot_state_publisher、键盘节点以外的任何订阅方。改完重开一次 view_frames 验证树是完整的。
5.4 起步窜车、停车点头
现象:按下前进,车瞬间弹出去;松开按键,车猛地一顿。
原因:max_wheel_acceleration 设得过大,cmd_vel 的阶跃直接被当成目标速度下发;或者 max_wheel_torque 过大,轮子瞬间达到目标转速并打滑。
解决:把 max_wheel_acceleration 从默认的大值降到 1.0 量级,让速度变化有个可见的斜坡;力矩上限按车重和轮径估算,几十厘米的小车 20 左右足够,不要为了“有劲”盲目调高,打滑会让 odom 失真。
5.5 场景里没有模型,或模型掉进地面
现象:Gazebo 起来了,但场景空白;或者模型生成后直接往下掉,穿过地面。
原因:spawn_entity.py 订阅 robot_description 拿不到内容,通常是 robot_state_publisher 没起或者 URDF 解析失败;掉穿地面则是模型初始 z 高度为负,或者碰撞体缺失、地面模型没加载。
解决:先 ros2 topic echo /robot_description 确认有 URDF 字符串,没有就检查 launch 里 robot_state_publisher 是否在 spawn_entity 之前启动;给 spawn_entity.py 加 -z 0.1 把初始高度抬起来;检查每个 link 是否都有 <collision>,只有 <visual> 的 link 在物理引擎里是幽灵。
6. 验证闭环:用 odom 与 TF 反推运动学对不对
把车开起来只是第一步,能不能确认“它跑的就是我以为的运动学”,决定了这套仿真能不能拿来验证上层算法。我一般做两件事:一是发已知的速度指令,反算理论位移,和 odom 实测对比;二是用 TF 查 odom → base_link 的变换是否连续。
先做直线验证。发一个线速度 0.2 m/s、持续 5 秒的指令,理论上应该前进 1 米:
bash复制ros2 topic pub --rate 10 /agv/cmd_vel geometry_msgs/msg/Twist \
"{linear: {x: 0.2}, angular: {z: 0.0}}"
跑完看 ros2 topic echo /agv/odom --once 里的 pose.pose.position.x,接近 1.0 说明轮径和轮距都对;明显小于 1 说明轮径填小了,明显大于 1 说明填大了。再做原地旋转验证:发 angular.z = 0.5、线速度为零,转 2π/0.5 秒应该刚好一圈,看 orientation 的四元数是否回到初始附近。这两项都过了,运动学参数基本可信。
然后是 TF 连续性。用 ros2 run tf2_ros tf2_echo odom base_link 实时打印变换,正常情况数值应该平滑变化,出现跳变或长时间不更新,多半是某个节点的 use_sim_time 没开。我还会顺手看一眼 ros2 topic hz /agv/odom,频率稳定在和插件更新周期匹配的数值上,才说明仿真没被卡住。
从那以后,我每次新建一个差分模型,都会先把轮距、轮径这两个数写在纸条上贴在显示器边,改任何一处参数都回头对一遍,再跑一次直线和原地转的验证。差分底盘看着简单,真正让人返工的从来不是算法,而是那两个小数点。希望帮到你。
