Skip to content

feat(ground): 新增差速小车沿墙行驶模块 - #1150

Merged
tianyutu981 merged 1 commit into
OpenHUTB:masterfrom
xinyangtang91:feat/diff_drive_wall_following
Nov 13, 2026
Merged

tianyutu981 merged 1 commit into
OpenHUTB:masterfrom
xinyangtang91:feat/diff_drive_wall_following

Conversation

@xinyangtang91

Copy link
Copy Markdown
Contributor

修改目的与内容

地面载具里已有定点停车、避障、路径跟踪等模块,但缺少一个「只用一路激光保持与墙距离」的入门实验。沿墙行驶是理解激光分区、距离闭环和墙角状态机的经典题目,也便于在没有 Gazebo 和实车的情况下用离线仿真复现。

本 PR 新增地面载具模块 diff_drive_wall_following:

  • src/ground/diff_drive_wall_following/:main.py 订阅 /scan(LaserScan),取正前、正右、右前、右后、正左五路距离,发布 /cmd_vel(Twist);wall_follower.py 用右侧距离误差和车身夹角误差计算角速度,正前方过近时进入原地左转状态;含 main.launch、config/params.yaml、README.md 和离线仿真 offline_sim.py。
  • 安全处理:激光超过 scan_timeout(0.5 s)没有更新时发布零速度;角速度越大线速度越低;退出时发布零速度。
  • docs/ground/diff_drive_wall_following.md:五路测距说明、控制律、墙角状态图、ROS 与离线两种运行步骤、三张结果图和指标表。
  • 首页 docs/index.md 与 mkdocs.yml 导航加入口。
  • tests/test_diff_drive_wall_following_local.py:不依赖 ROS 的沿墙控制、墙角切换、限幅和工程文件检查。

已知限制:离线仿真是理想矩形房间 + 简化运动学,不含轮子打滑和真实激光噪声;本机没有 ROS 与 Gazebo,ROS 端实际运行尚未验证。

测试环境与结果

  • 实际系统、ROS、Python、模拟器及关键依赖版本:
    • 离线仿真与文档构建:Windows 10.0.26200,Python 3.12.14,numpy 2.5.4,matplotlib 3.11.2,mkdocs 1.6.1
    • ROS 端目标环境:Ubuntu 20.04 + ROS Noetic + TurtleBot3 burger(本次未在本机运行,因为本机没有 ROS/Gazebo)
  • 构建与运行命令(注明执行目录):
    • 在仓库根目录:python src/ground/diff_drive_wall_following/offline_sim.py
    • 在仓库根目录:python tests/test_diff_drive_wall_following_local.py
    • 在仓库根目录:python -m mkdocs build
    • 在仓库根目录:python -m mkdocs serve --dev-addr 127.0.0.1:8002 --livereload
    • ROS 端(需 Ubuntu + Noetic + TurtleBot3,本机未执行):cp -r src/ground/diff_drive_wall_following ~/catkin_ws/src/ && cd ~/catkin_ws && catkin_make && source devel/setup.bash && roslaunch diff_drive_wall_following main.launch
  • 验证操作、结果及尚未验证的内容:
    • 离线仿真实际运行:绕行一圈 60.95 s、路径长度 17.06 m、平均跟墙误差 0.031 m、最大 0.273 m(墙角段)、最小前方净空 0.698 m;
    • 本地测试 27 项全部通过(沿墙控制、墙角切换、限幅、工程文件);
    • mkdocs build 通过(27.03 秒);mkdocs serve 下新页面、导航入口和三张图片均返回 200;
    • 尚未验证:main.py 在 ROS 中与 Gazebo/实车激光雷达的联调、catkin_make 编译、main.launch 启动。

运行效果

沿右侧墙绕行一圈的轨迹(蓝:沿墙,红:墙角转向):

沿墙轨迹

右侧墙距离:

右侧墙距离

速度指令:

速度曲线

三张图由 offline_sim.py 在本机实际运行生成;ROS 端接入 Gazebo/实车后的效果待另一台机器复验后补充。

提交前检查

  • 已检查 Files changed 和冲突,无无关生成文件、重复内容或误删公共文件。(本地 git diff 与 PR 页面均只有本模块的 15 个文件;分支基于最新 master,无冲突。)
  • 源码与教程按模块分别放在 src、docs,文件使用英文下划线命名。
  • 模块提供 main.* 和 launch,依赖及安装路径正确,README 步骤已实际运行。(main.py、main.launch、package.xml、CMakeLists.txt 已提供,依赖与安装路径已检查;但 README 的 ROS 运行步骤未在本机执行,因为本机没有 ROS,待另一台机器验证。)
  • 新模块已添加首页和导航链接;已运行 mkdocs serve --livereload 检查相关页面。
  • 功能描述与验证证据一致;PNG 小于 3 MB,GIF 小于 5 MB。(三张图分别为 42 KB、76 KB、90 KB;文档已注明是离线仿真结果,不是 Gazebo 实机截图。)

大模型使用声明

  • 使用工具:DeepSeek 助手(DeepSeek Harness)。
  • 辅助范围:模块代码与文档初稿、测试和离线仿真脚本、命令核对;运行数据和三张图由本机实际运行生成,不是模型编造。
  • 作者已逐项核对上述内容,并对提交内容的正确性负全部责任;ROS 端复验项见“尚未验证”和未勾选的检查项。

@Enemy52 Enemy52 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. CMakeLists.txt install 了不存在的 launch/ 目录:main.launch 文件在包根目录,不是在 launch/ 子目录里,但 CMakeLists 写的是 install(DIRECTORY launch config ...),catkin_make 会因为找不到 launch/ 目录报错。要么把 main.launch 移到 launch/ 子目录,要么改 install 路径。
  2. CI 0 个 check:根本没配 workflow,测试和构建都没在 CI 跑过。
  3. package.xml 还是 format="2":仓库其他包统一用 format="3",升级一下。
  4. 测试文件放在仓库根目录的 tests/ 下:不是包内的 test/ 目录,和其他包惯例不一致。

@xinyangtang91
xinyangtang91 force-pushed the feat/diff_drive_wall_following branch 2 times, most recently from 55427db to 7aaee0d Compare November 12, 2026 14:30
@xinyangtang91

Copy link
Copy Markdown
Contributor Author

已按评审意见修改并重新推送(分支已重建到最新 master):

  • main.launch 移到 launch/main.launch,与 install(DIRECTORY launch config ...) 一致;
  • package.xml 升级为 format="3";
  • 本地测试从仓库根 tests/ 移到包内 test/,路径改为 src/ground/diff_drive_wall_following/test/test_diff_drive_wall_following_local.py,测试内的包路径和 launch 路径同步调整;
  • 新增 .github/workflows/diff_drive_wall_following_tests.yml:push/PR 触发,test job 用 Python 3.8 跑模块测试和 py_compile,docs job 安装 requirements-docs.txt 后执行 mkdocs build。

本地验证:28 项测试通过、mkdocs build 通过。CI 已在本仓库 fork 上触发(run 43237964822,当前 queued);上游仓库对首次贡献者的 workflow 需要维护者批准后才会在 PR 上显示 check。

@tianyutu981

Copy link
Copy Markdown
Contributor
  1. 【CI 会失败】.github/workflows/diff_drive_wall_following_tests.yml 的 docs job 里 pip install -r requirements-docs.txt,但仓库里只有 requirements.txt(根目录的 mkdocs 依赖就是它),没有 requirements-docs.txt。请改为 pip install -r requirements.txt,否则 docs job 会直接报错。

  2. 【边缘情况·建议】main.py 的 _beam_distance 在某个方向完全没有有效测距时会返回 inf;若 front_right 和 back_right 恰好同时为 inf,wall_follower.py 里 align_error = inf - inf = nan,会一路传播成 NaN 的 /cmd_vel。建议在 WallFollower.update 里对测距缺失做兜底(例如某路为 inf 时用 side 代替或跳过夹角项)。

地面载具里已有定点停车、避障和路径跟踪,但缺少一个只用一路激光
保持与墙距离的入门实验。沿墙行驶是理解激光分区、距离闭环和墙角
状态机的经典题目,也便于在没有 Gazebo 时用离线仿真复现。

- 新增 src/ground/diff_drive_wall_following:main.py 订阅 /scan、
  发布 /cmd_vel;wall_follower.py 用右侧距离误差与车身夹角误差计算
  角速度,正前方过近时进入原地左转状态;包含 launch、参数文件和
  离线仿真脚本。
- 新增 docs/ground/diff_drive_wall_following.md:原理、状态图、参数、
  ROS 与离线两种运行步骤、三张结果图和指标表。
- 首页与 mkdocs 导航加入口。

评审修复:
- main.launch 移到 launch/ 目录,与 install(DIRECTORY launch ...) 一致;
- package.xml 升级为 format="3";
- 本地测试从仓库根 tests/ 移到包内 test/ 目录;
- 新增 .github/workflows/diff_drive_wall_following_tests.yml,push/PR
  时自动运行模块测试、字节编译并构建文档。

验证:离线仿真在 Windows + Python 3.12 实际运行,绕行一圈 60.95 s、
路径 17.06 m、平均跟墙误差 0.031 m、最大 0.273 m;本地测试 28 项通过;
mkdocs build 通过。ROS 端未在本机实机验证(没有 ROS 与 Gazebo),
需在 Noetic + TurtleBot3 上复验。

评审修复(第二轮):
- docs job 改为安装仓库根的 requirements.txt(仓库没有
  requirements-docs.txt),并显式安装 mkdocs 本体,避免只依赖插件的
  传递依赖;
- WallFollower.update 对 inf 测距做兜底:单路缺失时用 side 代替,
  两路都缺失时跳过夹角项,避免 inf-inf=NaN 进入 cmd_vel;
- main.py 发布前再次检查线速度/角速度有限性,异常时归零;
- 新增 4 项测距缺失单元测试,本地测试 32 项通过。
@xinyangtang91
xinyangtang91 force-pushed the feat/diff_drive_wall_following branch from 7aaee0d to bd65394 Compare November 13, 2026 11:55
@xinyangtang91

Copy link
Copy Markdown
Contributor Author

已按评审意见修改并重新推送:

  • CI docs job:改为安装仓库根的 requirements.txt(仓库里没有 requirements-docs.txt),并显式安装 mkdocs 本体,避免只依赖插件的传递依赖。最新一次运行里 Module tests (no ROS) 与 Docs build 都已通过。
  • 测距缺失兜底:WallFollower.update() 对 inf 做处理——单路缺失时用 side 代替,前右/后右两路都缺失时跳过夹角项;side 本身无效时走丢墙分支,不会再出现 inf - inf = NaN。main.py 发布 cmd_vel 前再检查一次 v/w 有限性,异常时归零。
  • 新增 4 项测距缺失单元测试(两路 inf、单路 inf、完全丢墙),本地 32 项全部通过。

分支已重建到最新 master,PR 现在 mergeable=true(16 个文件)。

@tianyutu981
tianyutu981 merged commit d2f2a8c into OpenHUTB:master Nov 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants