Skip to content

feat(ground): 新增 rollover_margin,把「侧翻裕度」做成可离线校验的载荷转移与极限车速核算 - #1249

Merged
xingwunian merged 8 commits into
OpenHUTB:masterfrom
Wist-sutton:feat-rollover-margin
Nov 11, 2026
Merged

xingwunian merged 8 commits into
OpenHUTB:masterfrom
Wist-sutton:feat-rollover-margin

Conversation

@Wist-sutton

Copy link
Copy Markdown
Contributor

修改概述: 新增 src/ground/rollover_margin 包,把「过弯会不会翻车」做成一组可断言的准静态计算 —— 静态稳定因子 SSF、侧翻临界加速度、内外侧车轮垂向力、给定半径的极限车速,并在终端输出载荷条与车速扫描表。

修改的详细描述

1. 为什么需要这个包

仓库里已有三个和「过弯」相关但方向不同的模块,缺的是横向稳定性这一块:

已有模块 它回答什么
tire_slip_curve 附着系数从哪来(滑移率决定 μ)
braking_distance_check 纵向:从看见到停住要几米
turning_sweep_check 几何:转弯时车身占多宽、通道要多宽
本包 稳定性:载荷转移多少、何时抬轮、这个半径极限多快

turning_sweep_check 回答「这个弯能不能转过去(不压线)」,本包回答「这个弯能不能转过去(不翻车)」——
一个管空间,一个管稳定性。而且本包的三个输入(轮距、质心高、质量)与三个输出之间是闭式代数关系,
可以直接写成断言,不需要仿真器,因此在没有 CARLA 的机器上也能回归。

2. 模型(全部闭式,无迭代)

SSF     = track / (2·h_cg)              静态稳定因子
a_crit  = SSF · g                       侧翻临界侧向加速度
ΔF_z    = m · a_y · h_cg / track        横向载荷转移
F_inner = m·g/2 − ΔF_z
F_outer = m·g/2 + ΔF_z
v_max   = sqrt(a_crit · R)              给定半径的极限车速
safe_speed(margin) = sqrt(margin · a_crit · R)

两条自洽关系是断言的依据:

  • 抬轮发生在 ΔF_z = m·g/2,即 a_y = a_crit;
  • ΔF_z / F_z0 恒等于 a_y / a_crit。

垂向力守恒 F_inner + F_outer ≡ m·g 也在测试里逐点校验。

3. 四条断言

断言 判据 失败意味着
侧翻裕度 a_y/a_crit ≤ rollover_margin(默认 0.70) 过弯太快或车太高
内侧轮载荷 F_inner > 0 已抬轮,准静态模型失效
极限车速 v ≤ sqrt(a_crit·R) 车速超过该半径的物理上限
载荷转移 ` ΔF_z/F_z0 − a_y/a_crit

前三条描述安全性,第四条描述实现正确性 —— 这个分工让两类问题能被分开定位:
把质心抬到 0.90 m,前三条同时翻、第四条仍然通过(详见下面图 4)。

4. 字符图与扫描表

  • render_loads():12 行横向载荷柱,# 内侧、= 外侧,| 标出静态载荷中心,
    抬轮时会在内侧出现 ! 标记;
  • speed_table():30/40/50/60/70/80/90 km/h 七行,每行给 a_y、裕度、内侧轮载荷、是否抬轮,
    同时以 CSV 形式发布到 /rollover/loads。

5. 参数与话题

12 个参数(vehicle/* 四个、corner/* 两个、check/* 两个、rate/publish_hz、topic/* 三个),
launch/main.launch 为每一个都声明了带 doc 的 <arg> 并写回同名 <param>,命令行可覆盖。
三路 latched 话题:/rollover/report(String 报告)、/rollover/loads(String,CSV)、
/rollover/critical_speed(Float64,km/h)。

6. 结构约定

  • scripts/rollover_core.py 纯标准库,不 import rospy / numpy / yaml,离线测试直接跑它;
  • scripts/main.py 是薄入口(from rollover_node import main),符合仓库 main. 约定;
  • config/ 与 launch/ 由 CMakeLists.txt 的 install(DIRECTORY … USE_SOURCE_PERMISSIONS) 安装;
  • 文档页沿用 docs/ground/rollover_margin.md(新建),含模型、四条断言、参数表、实测输出、两个反例。

7. 自查修掉的两处

  1. render_loads() 最初只在 row < height // 2 时画柱,导致柱子只有半截 —— 改成满高并保留
    静态载荷中心那条竖线;
  2. 测试 E17/E18 原用 transfer_tolerance = 0.0 期望第四条失败,但实现里留了 +1e-12
    浮点余量,偏差 1.1e-16 仍判通过 —— 改为不可能满足的 -1e-6,断言才真正生效。

8. 没改动什么

  • 没有触碰 mkdocs.yml 之外的任何既有文件;本包文档是新建页面,不需要覆盖旧内容;
  • 不引入第三方依赖,Melodic(Python 2.7)与 Noetic(Python 3)都能直接跑。

经过了什么样的测试?

  1. 操作系统:Ubuntu 18.04(VMware 虚拟机)+ ROS Melodic(Python 2.7)
  2. Python 版本:运行测试用 Python 3.6.9;节点运行在 Python 2.7(rospy 只在 py2 下可用)
  3. 基础校验:
    • python3 tests/test_rollover_margin_local.py → 通过 165 项,失败 0 项(不需要 ROS / CARLA / 显示器)
    • catkin_make 通过,rospack find rollover_margin 能定位到 src/ground/rollover_margin
    • roslaunch rollover_margin main.launch 打出 结论:PASSED
    • 两个反例分别只翻「侧翻裕度」与「侧翻裕度 + 内侧轮载荷 + 极限车速」
    • rosparam get 三个参数与 config/rollover_margin.yaml 一致
  4. 数学自检(测试里逐点校验):
    • F_inner + F_outer = m·g(垂向力守恒)
    • ΔF_z/F_z0 = a_y/a_crit(两条定义自洽)
    • a_y = a_crit 时 F_inner = 0(抬轮判定与载荷转移同源)
    • safe_speed(1.0) = sqrt(a_crit·R) 等于 speed_limit()(两条路径同一结果)

运行效果(动图、视频、图片、链接等)

默认工况:SSF 1.4000、侧向加速度 9.259 m/s²、裕度 0.674、内侧轮 2397.2 N / 外侧轮 12317.8 N、
极限车速 73.1 km/h,四条断言全部通过。

图 1:离线测试 通过 165 项,失败 0 项。
屏幕截图 2026-11-11 170812

图 2:默认工况的完整报告与载荷条,结论:PASSED。
屏幕截图 2026-11-11 170935

图 3:反例一 rollover_margin:=0.5,只有「侧翻裕度」失败(3 通过 / 1 失败)。
屏幕截图 2026-11-11 171007

图 4:反例二 cg_height:=0.90,SSF 掉到 0.8556、内侧轮 −759.4 N,安全类三条同时失败(1 通过 / 3 失败),
而「载荷转移」仍
屏幕截图 2026-11-11 171043
然通过。

图 5:终端 B 的 rosparam get,1.54 / 0.7 / 0.55 与 yaml 一致。
屏幕截图 2026-11-11 171142

所使用具体的大模型声明:使用大模型辅助代码编写、测试编写与文档整理,提交内容由本人负责。

@jiaohua745-blip

Copy link
Copy Markdown
Contributor

这份和 #1254 是同一个模式,三个点都要处理(代码本身这次没细看)。

1. mkdocs.yml / docs/index.md 删掉了 master 已有的两条入口(阻断)

本 PR 的 hunk 是:

-    - VRU 冲突风险图: './ground/vru_conflict_risk_map.md'
-    - 里程计健康监视: './ground/odom_health_monitor.md'
+(空行)

这两条对应已合并的 #1245 / #1244,docs/index.md 里对应的两个列表项也一起没了。合进去文档站会少两个入口页。

2. 自己的页面没进导航

docs/ground/rollover_margin.md 已经入库,但 head 的 mkdocs.yml 和 docs/index.md 里都 grep 不到 rollover_margin,模板里「新模块已添加首页和导航链接」这条实际没做到,页面只能靠 URL 直接访问。

3. tests/test_rollover_margin_local.py 没有 workflow 会执行

本 PR 没加 workflow;air_bridge_tests.yml 虽然被 tests/** 触发(所以显示 success),但 job 里是按固定文件名跑的,不含这个文件;#1253 的 offline_checks 清单里也没有它。CI 绿只说明别的检查过了。

修法:从当前 master 取 mkdocs.yml 和 docs/index.md 全量,只插自己那一行(验收口径:反向删掉自己那行后与 master 逐字节一致),再把这个测试挂进一个 workflow(可照 #1253 的接法)。这三条修完我这边就可以合。

# Conflicts:
#	docs/index.md
#	mkdocs.yml

@xingwunian xingwunian 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.

按贡献指南第 8 节本地核对过(git fetch origin pull/1249/head → 逐文件看 → 跑离线测试),没有阻断问题,可以合。

  • 把 master(b61c2150,已含 #1246)合进本分支,冲突只在 mkdocs.yml / docs/index.md
  • 本 PR 原来的 hunk 把 master 已有的「VRU 冲突风险图」「里程计健康监视」两条入口删掉了,而「横向载荷转移与侧翻裕度」又没进导航。已改成:保留 master 两条,补上本模块的导航项与首页链接(./ground/rollover_margin.md)
  • tests/test_rollover_margin_local.py 本地跑:通过 165 项,失败 0 项
  • 相对 master 的净变化 1435 行新增、0 行删除;catkin_install_python 三个脚本齐全,包内只依赖 math,package.xml 无缺失依赖

代码逻辑没动,只补了合并与导航。按贡献指南用 Squash and merge。

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