简介基于ROS_2与Navigation_2框架开发的智能巡检机器人仿真系统源码包面向机器人开发者、高校师生以及工业巡检、仓库管理等场景的技术人员。系统集成了运动控制、环境感知、自主导航、语音播报、图像采集和目标点循环巡检等完整功能可在Gazebo等仿真环境中验证路径规划、避障与任务调度逻辑帮助使用者低成本完成算法验证与系统联调。资源共63个文件其中20个Python脚本实现节点控制与业务逻辑12个xacro和1个urdf构建机器人模型yaml、xml、cfg等配置类文件用于导航参数与传感器设置sdf、world、rviz等负责仿真环境和可视化包体仅96KB结构紧凑、定位明确。目前已有108人学习浏览适合需要系统掌握ROS2导航框架和巡检系统设计的中高级开发者。随包附带的README、md说明和附赠资源文档配合autopatrol_robot等目录划分可帮助梳理各功能模块的依赖关系显著降低二次开发与迁移成本。1. 仓库里跑一圈只需要一条指令这套ROS 2巡检仿真系统做了什么凌晨两点的仓库人工巡检通常靠打卡表和手电筒。换成这套基于ROS 2和Navigation 2的仿真巡检系统后值班工程师在终端敲一条launch命令机器人就会从充电桩出发依次经过预设的检查点每到一处在停靠位采集图像、语音播报状态最后回到起点等待下一轮指令。整个过程在Gazebo仿真里完整跑通不需要实体车就可以验证导航、避障和任务编排逻辑。这个资源适合两类人一是刚学完ROS 2基础、想系统接触Navigation 2工程的新手二是需要快速搭建巡检Demo去做课程设计或方案验证的工程师。它把工业巡检、仓库管理里最常见的需求——周期巡检、状态播报、图像留档——全落到了可运行的代码层。2. 项目结构与消息接口读懂ros_patrol_robot四个功能包的职责边界拿到zip包解压后第一件事不是急着编译而是先看清src目录下的包分工。这个项目整体上是三层结构描述层、导航层、应用层。fishbot_description负责机器人物理模型和传感器仿真fishbot_navigation2负责建图与自主导航fishbot_application负责巡检业务逻辑而autopatrol_interfaces则定义各层之间传输消息的格式。四个包合在一起才构成从机器人长什么样到巡检任务怎么执行的完整链路。理解这个分层后续改任何功能都能快速定位到对应包而不是全局搜代码。2.1 按职责拆包description、navigation2、application、interfaces各管什么四个功能包的依赖关系是单向的application依赖interfacesnavigation2依赖description这种设计避免了循环依赖。fishbot_description存放URDF/Xacro模型文件定义了差速底盘、二维激光雷达、深度相机的安装位置和物理属性。fishbot_navigation2存放Navigation 2的配置文件、launch文件和代价地图参数负责把传感器数据变成可执行的导航行为。fishbot_application是巡检逻辑所在接收导航结果后触发图像保存和语音播报。autopatrol_interfaces只放自定义消息和服务定义不写任何业务代码。自定义接口是整个项目的地基所以我一般会先单独编译它。常见做法是分两步构建避免下游包读不到新生成的接口定义cd ~/ros_patrol_robot colcon build --packages-select autopatrol_interfaces source install/setup.bash colcon build --packages-select fishbot_description fishbot_navigation2 fishbot_application autopatrol_robot第一行编译自定义接口包编译完成后先source一次让后续包能找到新生成的头文件和消息类型。如果两条build合成一条命令虽然colcon会按依赖自动排序但接口包的消息定义有改动时下游包经常出现找不到msg头文件的缓存问题所以分两步更稳。后一条build里的四个包之间没有互相引用并行编译效率更高。2.2 用自定义消息固定巡检任务的数据结构巡检任务不能散落在代码里否则每个点加一个停留时间就要改源码。这个项目在autopatrol_interfaces里定义任务数据结构我过去做同类项目时也会沿用类似的字段设计# autopatrol_interfaces/msg/PatrolPoint.msg string name # 目标点名称如 checkpoint_1 float32 x # 地图坐标系X坐标 float32 y # 地图坐标系Y坐标 float32 yaw # 到达后的朝向角 float32 dwell_time # 停靠检测时长单位秒再用一个服务把整张巡检表返回给应用层# autopatrol_interfaces/srv/GetPatrolPlan.srv --- PatrolPoint[] points字段里把坐标和停靠时长绑定在一起好处是应用层的状态机不需要感知地图细节只需要请求服务拿到巡检表然后逐个下发导航目标。需要调整巡检路线时只改服务端实现或参数文件客户端代码完全不用动。编译完成后可以用命令验证接口是否生成正确ros2 interface show autopatrol_interfaces/msg/PatrolPoint正常会打印出字段名和类型。如果提示找不到接口多数情况是install目录没source成功或者包名拼写错误。这一步验证很关键接口不对后面所有节点都会在运行时掉链子。2.3 编译顺序与工作空间初始化自定义接口编译完成后还要确认整个工作空间能被launch入口正确加载。这个项目里autopatrol_robot模块承担了串联工作通常它下面放着总launch文件和rviz配置用于一次拉起全部节点。总入口的启动命令一般是ros2 launch autopatrol_robot patrol.launch.py这一行会同时拉起Gazebo、机器人模型、Navigation 2和巡检应用节点。如果只需要单独调试某一部分可以分别用fishbot_description的spawn.launch.py拉起机器人模型再用fishbot_navigation2的navigation2.launch.py启动导航栈。每启动一个模块建议在另一个终端用ros2 node list确认节点都活着再进入下一步联调。提示建模、导航、应用分开启动比每次都用总launch更适合调试。Gazebo重启一次代价很大导航参数调整之后只需要重启navigation2节点不需要把整个仿真关掉。3. 从SLAM建图到Navigation 2自主导航运动控制与路径规划怎么串起来第2章把包的结构讲清楚了接下来进入核心链路机器人怎么从能走变成知道往哪走。完整流程是先启动SLAM建立环境地图把地图交给Navigation 2做全局路径规划和局部避障最后通过/cmd_vel话题驱动差速底盘。三个环节只要一个断层后续巡检任务就跑不起来。这里我把每个环节里最容易踩坑的参数单独拎出来讲。3.1 先用SLAM建图激光雷达数据与里程计输入的准备工作Navigation 2本身不负责建图它消费的是静态地图所以第一步要把环境地图建出来。这个项目在fishbot_navigation2里提供了slam相关的launch配置常见做法是使用slam_toolbox或cartographer二者都订阅激光雷达扫描话题和里程计话题。雷达话题默认是/scan里程计是/odom代价地图的观测来源是雷达因此雷达在URDF里的安装高度和角度直接影响建图质量。雷达装歪了地图里的墙就是斜的导航时全局路径会一并出错。启动SLAM建图ros2 launch fishbot_navigation2 slam.launch.py建图过程中需要手动遥控机器人跑遍整个环境。可以用键盘节点也可以直接发布速度指令。键盘方式更直观ros2 run teleop_twist_keyboard teleop_twist_keyboard地图建好之后要保存成pgm和yaml两个文件命令是ros2 run nav2_map_server map_saver_cli -f ~/maps/factory_map-f指定保存路径和文件名前缀会生成factory_map.pgm和factory_map.yaml。yaml里记录分辨率、原点坐标和占用阈值后面启动导航栈时要显式传这个yaml路径。建图时建议走S形路线覆盖所有角落激光扫描不到的空旷区域在地图里会显示为未知未知区域被代价地图当作不可通行区域巡检路径规划会绕远路。3.2 启动Navigation 2导航栈map、planner、controller三层的参数映射有了静态地图启动导航栈ros2 launch fishbot_navigation2 navigation2.launch.py map:~/maps/factory_map.yamlNavigation 2的三块核心组件分别是map_server、planner_server和controller_server。map_server提供静态地图planner_server规划全局路径controller_server负责局部轨迹跟踪。三者的参数集中在nav2_params.yaml里其中几个参数对巡检场景影响最大参数典型值作用planner_server.robot_radius0.25全局代价地图的膨胀半径controller_server.max_vel_x0.5最大前进速度需与底盘匹配controller_server.min_vel_x0.05最小前进速度避免频繁停车controller_server.xy_goal_tolerance0.15到达判定距离BTNavigator.default_bt_xmlnavigate_to_pose巡检行为树类型local_costmap.observation_sourcesscan局部代价地图观测源max_vel_x设置得比底盘实际能力高时controller_server算出的轨迹底盘跟不上仿真里会出现车身原地抖动。xy_goal_tolerance直接决定巡检点停靠精度工业场景要求高可以设0.1但设太小会到不了目标点就一直转圈影响巡检节拍。实际项目中这些参数通常以yaml覆盖文件的方式传入launch也就是用params_file参数替换默认配置。3.3 用/cmd_vel做运动控制验证速度限制与坐标系关系建图和导航链路都准备好后需要确认运动控制链路正常。用一条topic发布指令就能做最基础的验证ros2 topic pub -r 10 /cmd_vel geometry_msgs/msg/Twist {linear: {x: 0.15, y: 0.0, z: 0.0}, angular: {z: 0.0}}这条指令以10Hz频率发布线速度0.15m/s、角速度为0。机器人如果在Gazebo里直线向前移动说明底盘驱动、关节控制器和里程计反馈都正常。如果车不动或原地旋转优先检查/odom话题是否有输出再查TF树。/cmd_vel接收的是底盘坐标系下的速度指令如果base_link的方向和期望朝向不一致需要在Xacro里调整雷达或底盘的安装朝向而不是在代码里反向补偿否则导航闭环后会出现路径偏移。4. 目标点循环巡检的完整实现动作客户端、图像采集与语音播报导航栈只是工具巡检才是目的。这一章把三条业务线合并成一个可运行的巡检系统用NavigateToPose动作客户端逐个访问目标点到达后采集图像保存同时用语音播报当前状态。三个功能相互独立又按顺序协作正好对应工业巡检里到点、记录、上报的标准动作。4.1 用NavigateToPose动作客户端编排多点巡检状态机Navigation 2提供/navigate_to_pose动作服务巡检节点只需要维护一个状态指针——当前巡检到第几个点。完整实现是一个带回调链的ActionClientimport rclpy from rclpy.node import Node from rclpy.action import ActionClient from nav2_msgs.action import NavigateToPose from geometry_msgs.msg import PoseStamped class PatrolPlanner(Node): def __init__(self): super().__init__(patrol_planner) self.action_client ActionClient(self, NavigateToPose, navigate_to_pose) self.action_client.wait_for_server() self.points [] self.index 0 def send_goal(self): if self.index len(self.points): self.get_logger().info(本轮巡检完成开始下一轮) self.index 0 return point self.points[self.index] goal_pose PoseStamped() goal_pose.header.frame_id map goal_pose.header.stamp self.get_clock().now().to_msg() goal_pose.pose.position.x point[x] goal_pose.pose.position.y point[y] goal_pose.pose.orientation.z point[yaw] goal_msg NavigateToPose.Goal() goal_msg.pose goal_pose self.action_client.send_goal_async(goal_msg).add_done_callback(self.on_goal_response) def on_goal_response(self, future): goal_handle future.result() if goal_handle.accepted: self.get_logger().info(目标点已接受) goal_handle.get_result_async().add_done_callback(self.on_nav_result) def on_nav_result(self, future): self.get_logger().info(到达目标点) self.index 1 self.send_goal()逻辑说明send_goal按顺序下发目标点index越界就归零开启新一轮巡检形成循环。on_goal_response里判断动作服务端是否接受目标接受后挂get_result_async回调导航结果返回时在on_nav_result里累加index再继续下一个点。orientation.z只提供偏航角因为平面移动时roll和pitch恒为零。参数说明巡检点列表可以从参数服务器加载也可以从第2章定义的GetPatrolPlan服务获取。实际项目里推荐服务方式因为路线调整时只需要改服务端的数据源不需要重启巡检节点这在长时间无人值守场景里很重要。4.2 到达目标点后的图像采集与本地存储每次到达巡检点后机器人需要把现场画面存下来作为巡检记录。图像采集基于sensor_msgs/Image话题配合cv_bridge转成OpenCV格式from sensor_msgs.msg import Image from cv_bridge import CvBridge import cv2 class ImageCollector(Node): def __init__(self): super().__init__(image_collector) self.bridge CvBridge() self.subscription self.create_subscription( Image, /camera/image_raw, self.image_callback, 10) self.save_enabled False def image_callback(self, msg): if not self.save_enabled: return frame self.bridge.imgmsg_to_cv2(msg, bgr8) filename f/tmp/patrol_{self.get_clock().now().to_msg().sec}.jpg cv2.imwrite(filename, frame) self.get_logger().info(f已保存: {filename})save_enabled是保存开关在状态机到达目标点后置True启动离开后置False避免把移动过程中的模糊帧存下来。imgmsg_to_cv2的第二个参数bgr8指定图像编码如果相机数据是灰度图需要改成mono8编码不匹配会直接抛异常。保存路径建议挂载到外部存储目录仿真连续跑几轮之后/tmp目录会被大量图片占满影响系统性能。4.3 语音播报把巡检状态合成语音的两种接法语音模块在仿真环境里最容易忽略因为Gazebo没有真实声卡但状态播报的逻辑必须跑通。这里的常见做法有两种一是调用系统TTS二是通过audio_common包挂在ROS 2话题链路上。第一种方案简单直接import subprocess def speak(self, text: str): subprocess.Popen([espeak-ng, -v, zh, text])subprocess.Popen异步启动不会阻塞巡检流程。-v zh指定中文语音系统需提前安装espeak-ng。生产级做法是把播报文本发布到一个状态消息话题语音节点只负责订阅和播报与巡检业务完全解耦这样任何模块都能触发播报而不只是巡检节点。5. 仿真调试技巧TF树、代价地图与导航卡死的检查顺序仿真环境跑起来容易跑得稳难。最后从排错顺序的角度总结几个巡检场景里真正能省时间的调试手段按从外到内、从低频到高频的顺序检查。5.1 先用view_frames确认TF树完整导航卡死的第一嫌疑不是代价地图而是TF。底盘、激光雷达、相机之间的坐标变换错一位代价地图直接全黑导航无从谈起。执行ros2 run tf2_tools view_frames执行后生成frames.pdf打开检查是否有悬空的坐标系。正常情况下应该有map到odom到base_link的完整链路base_link下挂着laser和camera。odom到base_link缺失说明robot_state_publisher没启动laser不在base_link下检查URDF中的joint定义。TF树正确是所有导航行为的前提这一步最基础也最容易跳过。5.2 代价地图异常与导航卡死的排查TF没问题但导航还是卡死按这个顺序查先确认/global_costmap/costmap有数据再看/local_costmap/costmap。全局地图全黑说明map_server加载失败检查yaml路径和pgm文件是否配套。局部地图异常优先看激光雷达话题频率ros2 topic hz /scan频率输出在5Hz以下说明雷达数据刷新太慢局部代价地图形同虚设。仿真里通常是Gazebo物理步长太大导致传感器发布受限减小update rate即可。注意巡检过程中如果有临时障碍物挡路膨胀层会把障碍物周围标记为死区。障碍物移走后局部代价地图偶尔不会立即恢复最有效的手段是重新请求一次全局路径规划或者重启navigation2节点。5.3 一张表对照常见症状与处理方法症状优先检查项处理手段启动后地图空白map_server参数确认map.yaml绝对路径正确车原地抖动不前max_vel_x过高或雷达频率低降速到0.3以下检查/scan话题hz目标点宣布到达但位置偏xy_goal_tolerance过大调到0.1至0.15之间避障不灵敏local_costmap膨胀半径增大footprint的padding值TF缺odomrobot_state_publisher确认use_sim_time参数为true多轮巡检时还有一个实用技巧在巡检节点里记录每个目标点的到达时间戳每轮循环结束后对比各点耗时。这个数据能直接暴露哪段路径规划异常哪里绕路、哪里频繁重规划都不用盯Rviz看耗时曲线就能定位。这个方法不需要额外调试工具在状态机里维护一张Python字典就能实现比对着日志猜问题快得多。本文还有配套的精品资源点击获取