Skip to content

feat(water): 新增 ROV 六推进器推力分配(ROS 1/catkin)模块 - #1154

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

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

Conversation

@xinyangtang91

Copy link
Copy Markdown
Contributor

修改目的与内容

水域载具现有实验多从键盘控制、轨迹跟踪和感知出发,缺少把上层「力/力矩指令」落到「各推进器推力」上的分配环节。推进器饱和、单推进器故障时会发生什么,也没有可复现的对比实验。本 PR 新增 rov_thruster_allocation,把这一层单独拆出来讲清楚。

  • src/water/rov_thruster_allocation/:allocation.py 由推进器布置构造 6×N 分配矩阵,用伪逆做最小二乘分配,支持 clamp / scale 两种饱和策略和单推进器故障重构;main.py 订阅 /rov/wrench,发布 /rov/thruster_cmd 与 /rov/wrench_achieved;含 main.launch、config/params.yaml、README.md 和离线验证脚本。
  • 安全处理:超过 wrench_timeout(0.5 s)没有新的期望 wrench 时推进器归零;节点退出时同样归零。
  • docs/water/rov_thruster_allocation.md:推进器布置、分配矩阵推导、伪逆、饱和与故障策略、话题接口、ROS 与离线运行步骤、三张结果图和指标表。
  • 首页 docs/index.md 与 mkdocs.yml 导航加入口。
  • tests/test_rov_thruster_allocation_local.py:不依赖 ROS 的矩阵、分配、饱和、故障和工程文件检查。

已知限制:只考虑几何分配,不含推进器非线性、死区和效率差异;布局横滚不可控(矩阵秩为 5);故障诊断本身不在本实验范围内;本机没有 ROS 与 ROV 仿真器,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(本次未在本机运行,因为本机没有 ROS/ROV 仿真器)
  • 构建与运行命令(注明执行目录):
    • 在仓库根目录:python src/water/rov_thruster_allocation/offline_sim.py
    • 在仓库根目录:python tests/test_rov_thruster_allocation_local.py
    • 在仓库根目录:python -m mkdocs build
    • 在仓库根目录:python -m mkdocs serve --dev-addr 127.0.0.1:8003 --livereload
    • ROS 端(需 Ubuntu + Noetic,本机未执行):cp -r src/water/rov_thruster_allocation ~/catkin_ws/src/ && cd ~/catkin_ws && catkin_make && source devel/setup.bash && roslaunch rov_thruster_allocation main.launch
  • 验证操作、结果及尚未验证的内容:
    • 正常任务(12 s 预设 wrench):分配残差约 $10^{-13}%$,最大推进器推力 29.5 N;
    • 过载场景:clamp 残差 82.56%、水平力方向偏差 13.57°;scale 残差 55.92%、比例 0.441、方向保持;
    • T2 故障:残差 15.15%,剩余推进器仍提供约 25.5 N 前进力;
    • 分配矩阵秩为 5(横滚不可控);
    • 本地测试 40 项全部通过;mkdocs build 通过(27.25 秒),新页面、导航和三张图片均返回 200;
    • 尚未验证:main.py 在 ROS 中与 ROV 仿真器/实车的联调、catkin_make 编译、main.launch 启动。

运行效果

正常任务下的推进器指令(上:4 个水平推进器,下:2 个垂直推进器):

推进器指令

正常工况下期望与可达 wrench(四个可控分量):

期望与实际 wrench

饱和与故障场景的相对残差:

饱和与故障残差

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

提交前检查

  • 已检查 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。(三张图分别为 66 KB、72 KB、39 KB;文档已注明是离线验证结果,不是 Gazebo/HoloOcean 实机截图。)

大模型使用声明

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

@tianyutu981

Copy link
Copy Markdown
Contributor
  1. 【会编译失败】CMakeLists.txt 写了 install(DIRECTORY launch config ...),但 main.launch 在包根目录、没有 launch/ 子目录,catkin_make 会报错。请移到 launch/main.launch(与 feat(ground): 新增差速小车沿墙行驶模块 #1150 已修复的问题相同,本 PR 和 feat(classical_control): 新增倒立摆能量摆起与 LQR 平衡模块 #1160 都还留着这个 bug)。

  2. 【缺依赖】package.xml 没有声明 numpy 依赖,而 allocation.py/main.py 都 import 了 numpy。建议像 feat(classical_control): 新增倒立摆能量摆起与 LQR 平衡模块 #1160 那样补 <exec_depend>python3-numpy</exec_depend>(Noetic 下 rosdep key 为 python3-numpy),CMakeLists 里"由系统提供"的注释不足以替代声明。

水域载具现有实验多从键盘控制、轨迹跟踪和感知出发,缺少把上层
力/力矩指令落到推进器上的分配环节;推进器饱和与单推进器故障时
会发生什么,也没有可复现的对比实验。

- 新增 src/water/rov_thruster_allocation_ros1:allocation.py 用推进器
  布置矩阵的伪逆做最小二乘分配,支持 clamp/scale 两种饱和策略和单
  推进器故障重构;main.py 订阅 /rov/wrench,发布 /rov/thruster_cmd
  与 /rov/wrench_achieved;包含 launch、参数文件和离线验证脚本。
- 新增 docs/water/rov_thruster_allocation_ros1.md:布局与分配矩阵推导、
  饱和/故障策略、话题接口、ROS 与离线运行、三张结果图和指标表。
- 首页与 mkdocs 导航加入口。

评审修复:
- main.launch 移到 launch/main.launch,与 CMakeLists.txt 的
  install(DIRECTORY launch config ...) 匹配;
- package.xml 升级为 format="3",补充 <exec_depend>python3-numpy</exec_depend>;
- 本地测试移到包内 test/ 目录;
- master 已合入同名的 ROS 2 包 rov_thruster_allocation,为避免覆盖,
  ROS 1/catkin 实现更名为 rov_thruster_allocation_ros1;
- 分支重建到最新 master,解决 docs/index.md 等文件冲突。

验证:离线验证在 Windows + Python 3.12 实际运行,正常任务分配残差约
1e-13%、最大推力 29.5 N;过载时 clamp 残差 82.56%、scale 残差 55.92%;
T2 故障残差 15.15%。本地测试 42 项通过;mkdocs build 通过。ROS 端
未在本机实机验证(没有 ROS 与 ROV 仿真器),需在 Noetic + 仿真器上复验。
@xinyangtang91 xinyangtang91 changed the title feat(water): 新增 ROV 六推进器推力分配模块 feat(water): 新增 ROV 六推进器推力分配(ROS 1/catkin)模块 Nov 13, 2026
@xinyangtang91
xinyangtang91 force-pushed the feat/rov_thruster_allocation branch from 1b68453 to f4716c6 Compare November 13, 2026 11:50
@xinyangtang91

Copy link
Copy Markdown
Contributor Author

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

  • main.launch 移到 launch/main.launch,与 CMakeLists.txt 的 install(DIRECTORY launch config ...) 匹配,catkin_make 不会再因找不到 launch/ 目录报错;
  • package.xml 补充 <exec_depend>python3-numpy</exec_depend>(Noetic rosdep key),并顺带升级为 format="3";
  • 本地测试从仓库根 tests/ 移到包内 test/ 目录;

另外:当前 master 已合入一个同名的 ROS 2/ament 包 rov_thruster_allocation,直接保留原路径会覆盖它。为避免冲突,本 PR 的 ROS 1/catkin 实现已改名为 rov_thruster_allocation_ros1(包名、目录、文档、图片和测试同步改名),原 ROS 2 包保持不动。

分支已重建到最新 master,PR 现在 mergeable=true(15 个文件、+925)。本地验证:42 项测试通过、mkdocs build 通过。

@tianyutu981
tianyutu981 merged commit 71ffb35 into OpenHUTB:master Nov 13, 2026
2 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.

2 participants