【保姆级教程】！两小时入门TurtleBot3 SLAM建图+自主导航+避障实战教程（附完整源码）

前言

本教程基于Ubuntu 20.04 + ROS Noetic环境，使用TurtleBot3 Gazebo仿真平台，从零开始完成 SLAM 建图、自主导航、绕桩巡航、自主避障四个完整任务，并附上所有源代码。

适合 ROS 初学者、机器人课程学生、自学小白导航入门。

完整代码已开源到 GitHub：https://github.com/EnoXie422/turtlebot3-slam-navigation若本文对你有帮助，欢迎点个 Star⭐ 支持一下～

💡 全文所有命令均经过实际测试，可直接复制使用。每个关键步骤附有截图说明。

一、环境准备

1.1 系统要求

1.2 安装ROS依赖包

打开终端（Ctrl + Alt + T），输入以下命令：

sudoapt-getinstallros-noetic-joy ros-noetic-teleop-twist-joy\ros-noetic-teleop-twist-keyboard ros-noetic-laser-proc\ros-noetic-rgbd-launch ros-noetic-rosserial-arduino\ros-noetic-rosserial-python ros-noetic-rosserial-client\ros-noetic-rosserial-msgs ros-noetic-amcl ros-noetic-map-server\ros-noetic-move-base ros-noetic-urdf ros-noetic-xacro\ros-noetic-compressed-image-transport ros-noetic-rqt* ros-noetic-rviz\ros-noetic-gmapping ros-noetic-navigation ros-noetic-interactive-markers

1.3 安装TurtleBot3专用包

sudoaptinstallros-noetic-dynamixel-sdksudoaptinstallros-noetic-turtlebot3-msgssudoaptinstallros-noetic-turtlebot3sudoaptinstallros-noetic-dwa-local-planner

⚠️重要：dwa-local-planner必须安装，否则导航时会报错Failed to create the dwa_local_planner/DWAPlannerROS planner

1.4 下载TurtleBot3仿真包

cd~/catkin_ws/src/gitclone-bnoetic https://github.com/ROBOTIS-GIT/turtlebot3_simulations.gitcd~/catkin_ws&&catkin_make

你将看到这样的内容
编译完成后会显示[100%]，无红色报错即为成功

1.5 配置工作空间自动加载

echo"source ~/catkin_ws/devel/setup.bash">>~/.bashrcsource~/.bashrc

二、Gazebo仿真基础

TurtleBot3提供三种仿真世界：

2.1 启动TurtleBot3 World

exportTURTLEBOT3_MODEL=burger roslaunch turtlebot3_gazebo turtlebot3_world.launch

应该能看到一个六边形场地，中间有9个绿色圆柱桩呈3×3排列，机器人在初始位置

2.2 启动TurtleBot3 House

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_gazebo turtlebot3_house.launch

⏳ 第一次启动House会下载模型，可能需要几分钟

应该能看到一个完整的房屋场景，包含客厅、卧室、厨房等多个房间

2.3 键盘控制机器人

新开一个终端：

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_teleop turtlebot3_teleop_key.launch

控制按键：

终端会显示按键说明、当前速度等信息

三、SLAM建图

SLAM（Simultaneous Localization And Mapping）即同时定位与建图，让机器人边走边构建地图。

3.1 建图流程

需要同时打开4个终端：

终端1：启动Gazebo世界

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_gazebo turtlebot3_house.launch

终端2：启动Gmapping SLAM节点

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_slam turtlebot3_slam.launch slam_methods:=gmapping

启动后会弹出 RViz 窗口，能实时看到地图被绘制出来。

刚启动SLAM时的RViz界面就是这样

此时地图基本是空白的，只能看到机器人周围一小圈被扫描的区域

终端3：键盘控制机器人

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_teleop turtlebot3_teleop_key.launch

3.2 建图技巧

为了获得高质量地图，建议遵循以下原则：

1. 速度要慢：移动速度越慢，激光雷达扫描越完整
2. 先转后走：避免边转弯边前进，会导致地图扭曲
   • ✅ 正确：原地旋转扫描 → 直线前进 → 到达新位置后再旋转
   • ❌ 错误：螺旋式前进
3. 沿墙行走：先沿墙绕一圈，再进入每个房间内部
4. 观察RViz：
   • 灰色区域 = 未扫描，需要前往
   • 黑白分明 = 扫描完成
   • 地图跳动 = 速度过快，停下重新校准

注：地图的形状可能在扫描时因操作或其他的原因不是十分方正，在此实验中，只要地图形状没有特别明显的错误，都可以完成

3.3 保存地图

地图绘制完成后，新开终端4保存：

rosrun map_server map_saver-f~/map_house

注：House地图保存为map_house，World地图保存为map_world，方便区分

保存成功后会在用户目录生成两个文件：

• map_house.pgm：地图图像
• map_house.yaml：地图配置文件

四、自主导航

导航功能基于已建好的地图，使用 ROS 的move_base框架自动规划路径。

4.1 启动导航

终端1：启动Gazebo

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_gazebo turtlebot3_house.launch

终端2：启动导航节点

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_navigation turtlebot3_navigation.launch map_file:=$HOME/map_house.yaml

能看到完整地图，机器人位置可能不准确，地图上还没有定位粒子

不用担心现在位置很乱！现在机器人在地图里的位置和我们建模的位置不在一起，我们接下来就要改变初始位置

4.2 设置初始位置

RViz 启动后，机器人不知道自己在哪，需要手动告诉它：

1. 点击RViz顶部工具栏的2D Pose Estimate按钮
2. 在地图上机器人实际所在的位置点击并拖动
3. 拖动方向 = 机器人面朝的方向
4. 松开鼠标后，地图上会出现一群绿色小箭头（粒子云），同时也可以看到，我们建模所生成的边界（抖动的绿色点形成的边线）和地图位置相重合

4.3 精确定位（可省略）

为了让 AMCL 算法收敛，需要让机器人稍微移动一下：

exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_teleop turtlebot3_teleop_key.launch

用W A S D让机器人前后晃动几次，绿色箭头会聚拢，说明定位精确了。

⚠️ 定位完成后必须按 Ctrl+C 关闭键盘控制终端，否则会与导航指令冲突

4.4 设置导航目标

1. 点击RViz顶部的2D Nav Goal按钮
2. 在地图上目标位置点击并拖动箭头
3. 箭头根部 = 目标坐标 (x, y)
4. 箭头方向 = 到达目标后的朝向 θ
5. 松开鼠标，机器人会自动规划路径并行驶

RViz中机器人和目标点之间出现一条彩色路径线（全局规划），机器人开始沿路径移动

最后会看到机器人成功到达目标位置，姿态也与目标箭头一致

五、任务一：绕桩巡航（TurtleBot3 World）

5.1 任务目标

让机器人在 TurtleBot3 World 中自主沿着九个圆柱桩的外围走一圈。

* * * ← 九个圆柱桩 * * * * * * 机器人需绕外围一圈

5.2 实现思路

利用move_base导航框架，依次发送8个目标点给机器人，让它形成一个环绕外围的路径：

(-1.5, 1.5) → (0, 2.0) → (1.5, 1.5) ↑ ↓ (-2.0, 0) (2.0, 0) ↑ ↓ (-1.5,-1.5) ← (0,-2.0) ← (1.5,-1.5)

5.3 扫描地图

因为绕桩巡航需要在World里跑，需要World的地图，按照前文三、SLAM建图的流程，仿照之前TurtleBot3 House地图建模流程，对TurtleBot3 World重新建图

终端1：启动World场景

exportTURTLEBOT3_MODEL=burger roslaunch turtlebot3_gazebo turtlebot3_world.launch

终端2 — 启动SLAM

exportTURTLEBOT3_MODEL=burger roslaunch turtlebot3_slam turtlebot3_slam.launch slam_methods:=gmapping

终端3 — 键盘控制

exportTURTLEBOT3_MODEL=burger roslaunch turtlebot3_teleop turtlebot3_teleop_key.launch

终端4 — 保存World地图

rosrun map_server map_saver-f~/map_world

注意这次保存名字叫 map_world，和之前House的地图分开

5.4 创建脚本

mkdir-p~/scripts gedit ~/scripts/task3_circle.py

在打开的编辑器中粘贴以下代码：

#!/usr/bin/env python3importrospyimportactionlibfrommove_base_msgs.msgimportMoveBaseAction,MoveBaseGoalfromgeometry_msgs.msgimportQuaternion# 绕九个点外围的8个目标点坐标waypoints=[(1.5,1.5),(0.0,2.0),(-1.5,1.5),(-2.0,0.0),(-1.5,-1.5),(0.0,-2.0),(1.5,-1.5),(2.0,0.0),]defsend_goal(client,x,y):goal=MoveBaseGoal()goal.target_pose.header.frame_id="map"goal.target_pose.header.stamp=rospy.Time.now()goal.target_pose.pose.position.x=x goal.target_pose.pose.position.y=y goal.target_pose.pose.position.z=0.0# 注意：必须设置完整四元数，否则会报invalid quaterniongoal.target_pose.pose.orientation=Quaternion(0.0,0.0,0.0,1.0)rospy.loginfo(f"前往目标点: ({x},{y})")client.send_goal(goal)# 等待最多60秒到达目标点finished=client.wait_for_result(rospy.Duration(60))iffinishedandclient.get_state()==actionlib.GoalStatus.SUCCEEDED:rospy.loginfo("到达目标点！")rospy.sleep(1.0)else:rospy.logwarn("未能到达目标点，继续下一个")defmain():rospy.init_node('task3_circle')client=actionlib.SimpleActionClient('move_base',MoveBaseAction)rospy.loginfo("等待move_base服务...")client.wait_for_server()rospy.loginfo("等待3秒让导航系统准备好...")rospy.sleep(3.0)rospy.loginfo("开始绕圈！")for(x,y)inwaypoints:send_goal(client,x,y)rospy.loginfo("绕圈完成！")if__name__=='__main__':main()

保存后给脚本添加执行权限：

chmod+x ~/scripts/task3_circle.py

5.5 代码核心解析

1. 四元数设置（避坑点）

goal.target_pose.pose.orientation=Quaternion(0.0,0.0,0.0,1.0)

很多教程只写orientation.w = 1.0，会报错Aborting on goal because it was sent with an invalid quaternion。必须完整设置四元数 (x, y, z, w) = (0, 0, 0, 1)表示朝向正前方。

2. 等待机制

finished=client.wait_for_result(rospy.Duration(60))

设置60秒超时，避免某个点到不了导致整个脚本卡死。

3. 顺序遍历

for(x,y)inwaypoints:send_goal(client,x,y)

依次发送8个目标点，机器人完成一个再走下一个。

4. 目标点坐标选取

可能因为各版本有所不同，地图方向和坐标位置可能略有区别，可以自行在RViz中查看对应的绕桩坐标修改参数，方法如下：

1. 点击RViz顶部的Panels→ **Tool Properties**按钮
2. 鼠标移到RViz地图上，窗口最底部便会显示类似这样的数字：
   X: 1.234 Y: -0.567 Z: 0.000

5.6 运行任务一

需要3个终端：

# 终端1：启动GazeboexportTURTLEBOT3_MODEL=burger roslaunch turtlebot3_gazebo turtlebot3_world.launch

# 终端2：启动导航exportTURTLEBOT3_MODEL=burger roslaunch turtlebot3_navigation turtlebot3_navigation.launch map_file:=$HOME/map_world.yaml

⚠️在RViz中用2D Pose Estimate设置好初始位置后：

# 终端3：运行脚本python3 ~/scripts/task3_circle.py

机器人会自动按顺序前往8个目标点，完成绕桩一圈！

六、任务二：自主避障（TurtleBot3 House）

6.1 任务目标

让机器人在 TurtleBot3 House 中不依赖地图，仅靠激光雷达数据实时感知障碍物，实现自主行走与避障。

6.2 实现思路

经典的反应式避障算法：

1. 读取/scan话题获取360度激光雷达距离数据
2. 划分前/左/右三个扇区
3. 根据各扇区最近障碍距离做决策：
   • 前方很近（<0.5m）→ 停下，向空的一侧旋转
   • 前方较近（0.5~1m）→ 减速并微转
   • 前方空旷（>1m）→ 全速直走

6.3 创建脚本

gedit ~/scripts/task4_avoid.py

粘贴以下代码：

#!/usr/bin/env python3importrospyfromsensor_msgs.msgimportLaserScanfromgeometry_msgs.msgimportTwistimportmathclassObstacleAvoider:def__init__(self):rospy.init_node('task4_avoid')# 发布速度指令self.cmd_pub=rospy.Publisher('/cmd_vel',Twist,queue_size=10)# 订阅激光雷达数据self.scan_sub=rospy.Subscriber('/scan',LaserScan,self.scan_callback)rospy.loginfo("避障节点启动！")defget_min_range(self,ranges,start_deg,end_deg,total):"""根据角度范围获取最小距离"""start_idx=int(start_deg/360.0*total)end_idx=int(end_deg/360.0*total)sector=ranges[start_idx:end_idx]# 过滤无效数据valid=[rforrinsectorifnotmath.isnan(r)andnotmath.isinf(r)andr>0.01]returnmin(valid)ifvalidelse999.0defscan_callback(self,scan):ranges=scan.ranges total=len(ranges)# 前方扇区：跨越0度，需要分两段front_left=self.get_min_range(ranges,330,360,total)front_right=self.get_min_range(ranges,0,30,total)front=min(front_left,front_right)# 左侧扇区：60~120度left=self.get_min_range(ranges,60,120,total)# 右侧扇区：240~300度right=self.get_min_range(ranges,240,300,total)rospy.loginfo(f"左:{left:.2f}前:{front:.2f}右:{right:.2f}")twist=Twist()iffront<0.5:# 前方有障碍，停下转向空旷一侧twist.linear.x=0.0ifleft>right:twist.angular.z=0.5rospy.loginfo("前方有障碍，左转！")else:twist.angular.z=-0.5rospy.loginfo("前方有障碍，右转！")eliffront<1.0:# 前方较近，减速并微转twist.linear.x=0.1twist.angular.z=0.3ifleft>rightelse-0.3rospy.loginfo("前方较近，减速转向")else:# 前方空旷，直走twist.linear.x=0.2twist.angular.z=0.0rospy.loginfo("前方空旷，直走")self.cmd_pub.publish(twist)defrun(self):rospy.spin()if__name__=='__main__':avoider=ObstacleAvoider()avoider.run()

保存后添加执行权限：

chmod+x ~/scripts/task4_avoid.py

6.4 代码核心解析

1. 激光雷达扇区划分（关键避坑点）

很多教程直接对ranges列表做切片如ranges[:total//4]，但waffle_pi 的雷达0度=正前方，正前方扇区跨越了0度，需要分两段读取：

front_left=self.get_min_range(ranges,330,360,total)# 左前方front_right=self.get_min_range(ranges,0,30,total)# 右前方front=min(front_left,front_right)# 取两段最小值

2. 无效数据过滤

valid=[rforrinsectorifnotmath.isnan(r)andnotmath.isinf(r)andr>0.01]

激光雷达可能返回nan、inf或 0，必须过滤掉，否则min()会返回错误结果。

3. 三级避障策略

4. 转向决策

ifleft>right:twist.angular.z=0.5# 左边更空，往左转（正值）else:twist.angular.z=-0.5# 右边更空，往右转（负值）

ROS 中规定：角速度正值=逆时针（左转），负值=顺时针（右转）。

6.5 运行任务二

# 终端1：启动House场景exportTURTLEBOT3_MODEL=waffle_pi roslaunch turtlebot3_gazebo turtlebot3_house.launch

# 终端2：运行避障脚本python3 ~/scripts/task4_avoid.py

终端会持续打印距离信息：

[INFO] 左:1.23 前:2.45 右:1.67 [INFO] 前方空旷，直走 [INFO] 左:0.89 前:0.42 右:1.12 [INFO] 前方有障碍，右转！

七、常见问题排查

7.1 报错：Failed to create the dwa_local_planner

原因：缺少 dwa-local-planner 包

解决：

sudoaptinstallros-noetic-dwa-local-planner

7.2 报错：Aborting on goal because it was sent with an invalid quaternion

原因：四元数设置不完整

解决：使用完整四元数

fromgeometry_msgs.msgimportQuaternion goal.target_pose.pose.orientation=Quaternion(0.0,0.0,0.0,1.0)

7.3 dpkg被中断错误

原因：之前的安装被中断

解决：

sudodpkg--configure-a

💡 如果中途询问是否替换配置文件（如vmtoolsd），输入N保留原版本即可

7.4 虚拟机网络故障详细排查（重点！）

很多同学装完后发现apt install报错暂时不能解析域名，ping www.baidu.com也不通。这是因为虚拟机网卡没有正常工作。下面是完整排查步骤。

7.4.1 先诊断网络状态

ipaddriproute

典型故障表现：

• ens33网卡状态显示为DOWN（没启用）
• 没有分配到 IP 地址（看不到inet 192.168.x.x）
• 路由表完全为空

7.4.2 修复方法一：重启网络管理服务

先试最简单的：

sudosystemctl restart NetworkManager

等几秒后再检查：

ipaddriprouteping8.8.8.8

如果ens33拿到了 IP（出现inet 192.168.x.x），且ping通了，修复成功。

7.4.3 修复方法二：手动启用网卡

如果方法一无效，手动拉起网卡：

sudoiplinksetens33 upsudodhclient ens33

然后再ip addr看是否拿到 IP。

7.4.4 修复方法三：检查VMware网络适配器设置

如果ens33一直 DOWN 且 NetworkManager 拉不起来，多半是虚拟机网络适配器被禁用了。

操作步骤：

1. 在 VMware 窗口右下角找到网络适配器图标（小电脑形状）
2. 右键 →连接（确认有勾）

或者通过菜单操作：

1. 虚拟机→设置→网络适配器
2. 确认已连接和启动时连接都打勾
3. 网络连接方式选NAT 模式（最不容易出问题）
4. 如果之前用的是自定义或仅主机模式，先改成NAT试试

改完之后回到虚拟机里再跑一遍：

sudosystemctl restart NetworkManageripaddrpingwww.baidu.com

7.4.5 修复方法四：重启VMware服务（在Windows宿主机操作）

如果以上都不行，在 Windows 上重启 VMware 的网络服务：

1. 按Win + R，输入services.msc，回车

2. 找到这两个服务，分别右键→重新启动：

   • VMware NAT Service
   • VMware DHCP Service

3. 然后回到Ubuntu虚拟机重新尝试上网

7.4.6 修复方法五：更换软件源

如果网络正常但 ROS 源连不上，换国内镜像源：

sudosh-c'echo "deb https://mirrors.tuna.tsinghua.edu.cn/ros/ubuntu focal main" > /etc/apt/sources.list.d/ros-latest.list'sudoaptupdate

7.5 避障时机器人撞墙不转

原因：扇区角度划分错误，没检测到前方障碍

解决：正前方0度跨越问题，必须分两段读取雷达数据（见 6.4 节）

7.6 导航目标点瞬间失败

原因：初始位置未设置或定位不准

解决：

1. 用2D Pose Estimate设置初始位置
2. 用键盘晃动机器人帮助 AMCL 收敛
3. 确认绿色粒子云已聚拢
4. 关闭键盘控制终端再运行脚本

7.7 RViz 中地图区域空白

原因：Fixed Frame 设置错误

解决：

1. 在 RViz 左侧Global Options中
2. 把Fixed Frame从odom改为map（导航时）或base_footprint（仅Gazebo时）

九、总结

本教程完整覆盖了 TurtleBot3 仿真环境下的核心功能：

完整代码已开源到 GitHub：https://github.com/EnoXie422/turtlebot3-slam-navigation若本文对你有帮助，欢迎点个 Star 支持一下⭐～

如果本文对你有帮助，欢迎点赞、收藏、关注三连支持！有问题欢迎评论区交流 💬

📌本文标签：#ROS#TurtleBot3#SLAM#自主导航#Gazebo仿真#机器人#避障算法