在 Gazebo 中仿真 oomwoo-one 扫地机器人基于 ROS 2 与 Docker 的零硬件开发实战【免费下载链接】oomwooOpen-source vacuum robot cleaner项目地址: https://gitcode.com/gh_mirrors/oo/oomwoo本篇教程完整讲解如何把 OOMWOO 开源扫地机器人项目的首款机型oomwoo-one跑进 Gazebo 仿真世界从搭建 Docker 开发环境、启动仿真到 SLAM 建图、Nav2 自主导航、键盘遥操作与碰撞传感器验证全程无需任何实体硬件。读完你将掌握一套可直接复用的「仿真优先simulation-first」开发闭环并为后续编写自己的 OOMWOO ROS 2 包打下基础。为什么用仿真OOMWOO 的「仿真优先」开发路线OOMWOO 是一个你可以自己动手搭建的开源扫地机器人项目Raspberry Pi 3D 打印 ROS 2 2D LiDAR本地运行、无需云服务而oomwoo-one是它的第一款机型。由于实体硬件仍在设计迭代中项目在架构上明确采用**仿真优先simulation-first**原则软件必须先能在 Gazebo 中跑通再移植到硬件上。这一原则在 docs/ARCHITECTURE.md 中被列为设计准则之一其意义在于——任何贡献者即使没有机器人也可以在仿真里构建和测试模块。对应的 contributions/urdf-gazebo-sim/README.md 展示了该仿真的完成度URDF 模型已基本完整含全套传感器并提供了 living-room客厅与 kitchen-dining厨房餐厅两套家居场景世界。本文档教程正是这套仿真环境的「开箱即用」操作手册。前置条件需求说明DockerWindows/macOS 使用 Docker DesktopLinux 使用 Docker EngineX Server图形界面用于显示 Gazebo 与 RViz 窗口Windows 下安装 VcXsrvXLaunchLinux 使用系统原生 X无需额外安装实体机器人不需要整个流程完全在容器内完成1. 启动 X Server仅 Windows 需要在 Windows 上从 VcXsrv 启动XLaunch向导中接受默认值但有两处必须修改在Display settings显示设置页面将 Display number显示编号设为0而不是默认的-1。因为 Docker 容器会连接到host.docker.internal:0.0显示编号必须是 0否则不会出现任何 GUI 窗口。另外在Extra settings额外设置页面勾选Disable access control禁用访问控制让容器可以连接。完成向导后系统托盘中会出现一个小的 X 图标。Linux 用户则只需让本地 Docker 能够访问你的 X serverxhost local:docker技术要点xhost local:docker是 Linux 下让容器访问宿主 X11 socket 的标准做法与 Windows 上「禁用访问控制」的作用一致——都是放开 X 的连接权限使容器内 GUI 进程能把窗口绘制到宿主机屏幕上。2. 拉取 OOMWOO Docker 镜像开发环境已封装为带 ROS 2 Jazzy 的 Docker 镜像直接拉取即可docker pull makerspet/oomwoo:jazzy-dev镜像名中的jazzy对应 ROS 2 Jazzy Jalisco 发行版dev表示开发环境镜像内含 Gazebo、RViz、SLAM、Nav2 以及 OOMWOO 的仿真与 bringup 包。3. 启动容器WindowsPowerShelldocker run --name makerspet -it --rm -v c:\maps:/root/maps -p 8888:8888/udp -p 5555:5555/udp -e DISPLAYhost.docker.internal:0.0 -e LIBGL_ALWAYS_INDIRECT0 --add-hosthost.docker.internal:host-gateway makerspet/oomwoo:jazzy-devDISPLAY...:0.0必须与第 1 步 XLaunch 的 display 0 保持一致。Ubuntu / Linuxdocker run --name makerspet -it --rm -v ~/maps:/root/maps -p 8888:8888/udp -p 5555:5555/udp -e DISPLAY$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix --network host makerspet/oomwoo:jazzy-dev命令参数说明参数作用--name makerspet给容器命名后续docker exec用该名称进入-it --rm交互式终端退出即自动删除容器-v c:\maps:/root/maps或-v ~/maps:/root/maps将宿主机的maps目录挂载为容器内/root/maps用于存放保存的地图-p 8888:8888/udp -p 5555:5555/udp映射仿真所需 UDP 端口-e DISPLAY...指定 X 显示服务地址Windows 为host.docker.internal:0.0Linux 直接透传$DISPLAY-e LIBGL_ALWAYS_INDIRECT0关闭间接渲染保证 OpenGL 图形性能--add-hosthost.docker.internal:host-gateway让 Windows 容器解析host.docker.internal指向宿主机-v /tmp/.X11-unix:/tmp/.X11-unix --network hostLinux 下共享 X socket 并直连宿主网络Gazebo 通信需要需要更多终端进入同一个容器再开一个 PowerShell 或终端窗口运行docker exec -it makerspet bash后续所有操作都在容器内进行需要开多个终端时反复使用docker exec -it makerspet bash即可。4. 选择 oomwoo-one 机器人模型进入容器后用kaia配置工具将机器人模型设为 oomwoo-onekaia config robot.model oomwoo_onekaia是 OOMWOO 开发环境的模型/配置选择工具。项目约定所有 ROS 2 包都通过这种方式切换机器人模型如oomwoo_one这与 docs/SOFTWARE_INTERFACES.md 中「遵循用kaia config robot.model oomwoo_one选择机器人包」的约定一致。从当前架构文档看oomwoo-one 的 URDF 基线是约 349 mm 的圆形机身见 docs/ARCHITECTURE.md 坐标帧与硬件架构章节。5. 启动 Gazebo 世界ros2 launch kaiaai_gazebo world.launch.py执行后 Gazebo 窗口打开oomwoo-one 出现在一个客厅living-room场景世界中。如果你希望切换到其他场景contributions/urdf-gazebo-sim/README.md 提供了world:参数选择不同世界文件的用法ros2 launch oomwoo_gazebo world.launch.py world:kitchen_dining.world ros2 launch oomwoo_gazebo world.launch.py world:living_room.world说明kaiaai_gazebo与oomwoo_gazebo是同一仿真在不同发布渠道中的包名前者随开发镜像提供它们共享world.launch.py启动方式与世界文件体系。多套家居世界正是为了后续测试建图、覆盖清扫与导航而设计的。6. 启动 SLAM 建图在容器新开的终端docker exec -it makerspet bash中运行ros2 launch kaiaai_bringup navigation.launch.py use_sim_time:true slam:True这里有两个关键参数use_sim_time:true告诉所有节点使用 Gazebo 的仿真时钟/clock而非墙钟这是仿真场景的硬性要求。按 docs/SOFTWARE_INTERFACES.md 的 QoS 约定仿真 launch 文件应当将use_sim_time置为 true否则里程计、TF、传感器时间戳与仿真时钟不同步。slam:True开启 SLAM建图与定位同步进行。从 docs/ARCHITECTURE.md 的软件架构看项目 MVP 的 SLAM 栈以 slam_toolbox 为预期方案手动建图模式正是 MVP 的核心节点之一。启动后节点会订阅 2D LiDAR 的/scan数据开始增量建图。7. 打开 RViz 监控器再开一个终端ros2 launch kaiaai_bringup monitor_robot.launch.py use_sim_time:trueRViz 窗口中可以看到机器人的激光点云、TF 坐标树以及正在不断生长的地图。随着机器人移动地图会实时填充——这正是观察 SLAM 收敛效果的直观方式。8. 键盘手动驾驶ros2 run kaiaai_teleop teleop_keyboard用键盘控制 oomwoo-one 在房间里移动把地图逐步补齐。teleop 节点本质上是向/cmd_velgeometry_msgs/msg/Twist发布速度指令Gazebo 中的差速驱动控制器消费该指令并驱动机器人运动。这也是 docs/SOFTWARE_INTERFACES.md 基线主题表里/cmd_vel的职责划分Teleop、Nav2 作为生产者Gazebo diff-drive 作为消费者。9. 自主导航Nav2在 RViz 中点击顶部工具栏的Nav2 Goal然后在地图上点击并拖拽出一个目标点。oomwoo-one 会自行规划路径并自动行驶到目标位置。底层机制是 Nav2 的NavigateToPoseactionnav2_msgs/action/NavigateToPose这也是 docs/SOFTWARE_INTERFACES.md 中为nav-localize、cleaning-jobs、dock-cycle等模块预留的标准接口——导航能力以 action 形式对外开放任何模块都可以复用。规划时 Nav2 会结合 SLAM 产出的/map、LiDAR 的/scan与里程计/odom计算代价地图并规避障碍。10. 检查碰撞bumper传感器ros2 topic echo /bumper_left ros2 topic echo /bumper_right驱动机器人撞向墙壁观察左/右碰撞传感器的接触事件输出。关于 bumper 主题的消息细节docs/SOFTWARE_INTERFACES.md 有明确约定值得展开说明消息类型Gazebo 场景下为ros_gz_interfaces/msg/Contacts关键字段contacts列表每个 contact 含collision1、collision2、positions、normals、depths、wrenches消费约定消费者应将len(msg.contacts) 0过滤掉地面接触后视为一次碰撞事件注意不要读取collisions字段——那是单接触消息类型的字段bridge 并不发布它未来硬件版本可能用归一化的 bumper 消息替换原始 Gazebo 接触消息因此在模块代码中应把 Gazebo 特有的解析逻辑隔离在一个小适配器里。当前仿真中/bumper_left与/bumper_right由 Gazebo 左右碰撞接触传感器产生供恢复、安全以及 clean-and-map 等模块消费。这与 contributions/clean-and-map/README.md 中「通过 bumper 接触检测 LiDAR 不可见的静态障碍玻璃、低矮物体等并重规划」的需求直接对应。11. 保存地图ros2 run nav2_map_server map_saver_cli -f ~/maps/map地图会以map.yamlmap.pgm的形式保存Windows 下位于c:\mapsLinux 下位于~/maps即容器内/root/maps挂载的宿主机目录。保存后的地图是后续「在已知地图上导航」模块见 contributions/nav-localize/README.md的输入也是 clean-and-map「首扫成图」验收标准的一部分。接口契约仿真是真机接口的一面镜子这套仿真之所以值得认真对待在于它暴露的 ROS 2 接口与将来真机保持一致。按 docs/SOFTWARE_INTERFACES.md 的基线主题表本次教程中实际用到的接口可以归纳如下主题消息类型方向生产者消费者/cmd_velgeometry_msgs/msg/Twist命令Teleop、Nav2Gazebo 差速控制器/odomnav_msgs/msg/Odometry状态Gazebo 里程计SLAM、Nav2/tftf2_msgs/msg/TFMessage状态robot state publisher、里程计所有位姿相关模块/joint_statessensor_msgs/msg/JointState状态Gazebo joint state publisherrobot state publisher、诊断/scansensor_msgs/msg/LaserScan传感器2D LiDAR / Gazebo LiDARSLAM、Nav2 代价地图/mapnav_msgs/msg/OccupancyGrid状态SLAM 或 map serverNav2、可视化/bumper_leftros_gz_interfaces/msg/Contacts传感器Gazebo 左接触传感器恢复、安全模块/bumper_rightros_gz_interfaces/msg/Contacts传感器Gazebo 右接触传感器恢复、安全模块坐标帧同样有契约REP-103 约定、SI 单位map全局地图帧SLAM/Nav2 与已存地图使用、odom里程计帧、base_footprint导航平面基座帧、base_link机器人主体帧、base_scanLiDAR 帧。如果你想快速验证仿真是否工作正常docs/SOFTWARE_INTERFACES.md 提供了官方的验证清单命令可直接复用ros2 topic list ros2 topic echo /scan --once ros2 topic echo /odom --once ros2 topic echo /bumper_left ros2 topic echo /bumper_right ros2 run tf2_tools view_frames故障排查速查现象原因与处理容器内无 GUI 窗口Windows 检查 XLaunch Display number 是否为 0 且勾选了「禁用访问控制」Linux 检查是否执行过xhost local:dockerSLAM 地图漂移或错乱确认所有 launch 都带了use_sim_time:true仿真时钟未对齐会导致 TF/里程计错乱键盘无反应确认teleop_keyboard终端窗口处于聚焦状态键位在终端中读取且/cmd_vel只有这一个发布者保存地图找不到文件检查容器挂载路径~/maps对应宿主机挂载的maps目录下一步从「玩仿真」到「写自己的包」至此你已经跑通完整的 oomwoo-one 仿真闭环SLAM 建图、Nav2 导航、键盘遥操作、bumper 传感器以及地图保存——这些接口与真机将要暴露的完全一致。接下来可以做的事情包括编写第一个 OOMWOO ROS 2 包参考 docs/blog/oomwoo-one-first-ros2-package.md写一个「沿覆盖路径行驶 同时建图」的节点并用ros2 launch一键启动仿真、SLAM 与你的代码参与 clean-and-map 模块在 contributions/clean-and-map/README.md 的指引下实现「无地图起步、边清扫边建图、探索边界直到地图完整」的首扫覆盖算法参与 nav-localize 模块在 contributions/nav-localize/README.md 的指引下基于保存的地图实现已知地图定位、Nav2 导航与「被绑架机器人」的重新定位恢复了解整体软件契约深入阅读 docs/SOFTWARE_INTERFACES.md 与 docs/ARCHITECTURE.md理解各模块如何通过标准 ROS 2 接口并行协作。这就是 OOMWOO「仿真优先」的完整开发循环没有硬件也能开发、测试并贡献一个开源扫地机器人的软件栈。【免费下载链接】oomwooOpen-source vacuum robot cleaner项目地址: https://gitcode.com/gh_mirrors/oo/oomwoo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考