Skip to content

feat(ground): 新增 lateral_stability_margin,把「不足转向」做成可离线校验的稳态转向角与稳定裕度核算 - #1254

Merged
xingwunian merged 7 commits into
OpenHUTB:masterfrom
Wist-sutton:feat-lateral-stability-margin
Nov 11, 2026
Merged

xingwunian merged 7 commits into
OpenHUTB:masterfrom
Wist-sutton:feat-lateral-stability-margin

Conversation

@Wist-sutton

Copy link
Copy Markdown
Contributor

修改概述

新增 src/ground/lateral_stability_margin 模块:从整车质量、轴距、质心位置与前后轴侧偏刚度出发,
算不足转向梯度 K、稳态转向角、特征车速/临界车速,并用「轴荷分配 / 不足转向裕度 / 稳态转向角 /
低速阿克曼」四条断言判断车辆是偏安全(不足转向)还是偏危险(过多转向)。纯标准库实现,不依赖 CARLA。

配套新增 docs/ground/lateral_stability_margin.md 文档页。

修改的详细描述

1. 为什么需要这个包

rollover_margin 管的是「横向加速度太大把车掀翻」,本模块管的是另一件事:
同样的方向盘转角,车是往弯里多转还是少转。前者是翻车,后者是甩尾/推头,
两者物理机制不同、判据也不同:

模块 物理量 失效表现
rollover_margin 横向载荷转移、SSF 内侧轮离地 → 侧翻
本模块 不足转向梯度 K、稳态转向角 K<0 时车尾先滑 → 甩尾
tire_slip_curve 滑移率—附着曲线 轮胎先饱和

三者串起来才是完整的横向安全链条:轮胎饱和(tire_slip_curve)→ 车辆响应变差(本模块)→ 侧翻(rollover_margin)。

2. 模型

轴荷        W_f = m·g·l_r / L ,W_r = m·g·l_f / L
不足转向梯度 K  = (W_f / C_f − W_r / C_r) / g            rad/(m/s²),K>0 不足转向,K<0 过多转向
稳态转向角  δ  = L / R + K·a_y                          rad
特征车速    v_char = sqrt(L / K)                        (K>0)
临界车速    v_crit = sqrt(−L / K)                       (K<0)
灵敏度      dδ/da_y = K                                 1/(m/s²)

K 里那个 /g 是关键:W/C 量纲是 rad/(m/s²)·g,不除以 g 会让 δ 多出一个 g 的量级
(我第一版就这么写错了,见第 7 节)。

由此得到两条恒等式,测试 I 组专门核对:

K > 0:L + K · v_char² = 2L        (特征车速处转向角恰好是阿克曼的两倍)
K < 0:L + K · v_crit² = 0         (临界车速处分母为零 → 转向角发散)

3. 四条断言

断言 判据 默认实测
轴荷分配 前后轴荷之和 = m·g,偏差 ≤ 1 N 14715.0 N,偏差 0.0000
不足转向裕度 K ≥ understeer_min(默认 0.0) K = 0.003399 → PASS
稳态转向角 δ − L/R = K·a_y,相对偏差 ≤ 5% 偏差 0.0000
低速阿克曼 低速时 δ 与 L/R 相对偏差 ≤ 0.02 2 km/h 处偏差 0.0000

第 4 条限定在低速:阿克曼假设「无侧偏」,中高速下必然偏离,所以只在
ackermann_speed_kmh(默认 2.0 km/h)处校验。

4. 默认数字

m = 1500 kg、L = 2.7 m、l_f = 1.2 m、C_f = 80000、C_r = 95000、R = 50 m、v = 40 km/h:

项 值
轴荷 前 / 后 8175.0 N / 6540.0 N
K 0.003399 rad/(m/s²),特性「不足转向」
特征车速 28.184 m/s(101.5 km/h)
a_y 2.469 m/s²
稳态转向角 0.062393 rad(3.57°)
纯阿克曼 0.054000 rad(3.09°),超出 0.008393 rad
灵敏度 39.574 1/s

车速扫描(20~120 km/h):3.21°/11.00、3.57°/39.57、4.18°/76.22、5.02°/112.78、6.10°/144.96、7.42°/171.55。

5. 参数与话题

12 个参数:/vehicle/{mass,wheelbase,cg_to_front}、/tire/{front_cornering,rear_cornering}、
/scene/{radius,speed_kmh}、/check/{understeer_min,ackermann_speed_kmh,ackermann_tolerance}、
/gravity、/rate/publish_hz。

三路 latched 话题:/stability/report(String)、/stability/circle(Float64MultiArray,
[K, δ, δ_ackermann, a_y, v_char_or_crit])、/stability/table(Float64MultiArray,6 行扫描)。

6. 结构约定

config/ + launch/main.launch(12 个带 doc 的 <arg>)+ scripts/{main,*_core,*_node}.py

  • tests/test_*_local.py + docs/ground/*.md;*_core.py 不 import rospy,
    *_node.py 用 _log() 转 byte str。三个脚本都是「第 1 行 shebang、第 2 行 coding 声明」。

7. 自查修掉的两处

  1. K 忘记除以 g:第一版 K = W_f/C_f − W_r/C_r 直接返回,得到 K = 0.0333、
    40 km/h 处 δ = 0.136 rad(7.81°)、灵敏度 18.11 —— 全部差一个 g。
    改成 (W_f/C_f − W_r/C_r)/g 后 K = 0.003399、δ = 0.0624 rad(3.57°),
    且 L + K·v_char² = 2L 这条恒等式才成立。
  2. 断言顺序与 ASSERT_NAMES 不一致:core 里先算「稳态转向角」后算「低速阿克曼」,
    而名字元组写的是反序,报告与测试对不上。已统一为 轴荷 → 裕度 → 稳态转向角 → 低速阿克曼。

8. 没改动什么

没有修改既有模块、mkdocs.yml、docs/index.md。

测试

Ubuntu 18.04 + ROS Melodic(Python 2.7.17):

python3 tests/test_lateral_stability_margin_local.py

通过 116 项,失败 0 项。11 组:A 几何与轴荷 / B 梯度与特性 / C 圆周工况 /
D 四条断言正反例 / E 车速扫描 / F 字符图 / G 参数与非法值 / H 报告排版 /
I 闭式恒等式(L+K·v_char²=2L、L+K·v_crit²=0)/ J 工程约定 / K 编码声明回归。

运行效果

roslaunch lateral_stability_margin main.launch

断言:4 通过 / 0 失败(共 4 条)、结论:PASSED。

两个反例:

  • front_cornering:=160000 rear_cornering:=40000 → K 变负、特性「过多转向」、临界车速 15.350 m/s(55.3 km/h),只翻「不足转向裕度」;
  • ackermann_speed_kmh:=60 → 只翻「低速阿克曼」(偏差 0.3497)。

图 1 离线测试通过 116 项
屏幕截图 2026-11-11 174749

图 2 默认 结论:PASSED(K = 0.003399、δ = 3.57°、特征车速 101.5 km/h)
屏幕截图 2026-11-11 174856

图 3 前后胎刚度对调 → 过多转向、临界车速 55.3 km/h
屏幕截图 2026-11-11 174931

图 4 ackermann_speed_kmh:=60 → 只翻「低速阿克曼」
屏幕截图 2026-11-11 175002

图 5 终端 B 三条 rosparam get 回显
屏幕截图 2026-11-11 175039

所使用具体的大模型声明

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

@jiaohua745-blip

Copy link
Copy Markdown
Contributor

看了 head c32fe01,有三个会挡住合并的点,都出在文档/CI 挂接上,代码本身这次没细看。

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

当前 head 的 mkdocs.yml 是 397 行,master 是 404 行,整体反而少 7 条;本 PR 自己的 hunk 直接删掉的是:

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

这两条对应已合并的 #1245 和 #1244,docs/index.md 里同样删掉了对应的两个列表项。合进去文档站会少两个入口页。
建议:从当前 master 取这两个文件全量,只插自己那一行;验收口径就是「反向删掉自己那行后与 master 逐字节一致」。

2. 本模块自己的页面没进导航

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

3. tests/test_lateral_stability_margin_local.py 目前没有任何 workflow 会执行

air_bridge_tests.yml 由 tests/** 触发,这点没问题,但 job 里是按固定文件名跑的(test_frames.py / test_bridge_local.py / test_sensors_local.py / test_imu_local.py / test_keyboard_local.py …),不含这个文件;offline_checks(#1253)的清单里也没有它。所以现在 CI 绿只说明别的检查跑过了,新增的这个本地测试等于没人跑。
建议照 #1253 的做法把它加进 paths + step,或直接挂进已有的 offline_checks 清单。

前两条修完、第三条补上,我这边就可以合了。

# 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.

@jiaohua745-blip 三条按你说的都补了,代码本身没动,只在作者分支上做了合并与挂接:

  1. mkdocs.yml / docs/index.md 删 master 入口 —— 把 master(0b70e466,已含 #1246/#1249/#1250/#1252)合进本分支,冲突只在 mkdocs.yml / docs/index.md。处理方式是保留 master 已有的「VRU 冲突风险图」「里程计健康监视」两条入口,再把本模块加进去;git diff master..HEAD --numstat 现在是 added 1349 / deleted 0,没有任何删除。
  2. 导航补上 lateral_stability —— mkdocs.yml 里 - 不足转向梯度与侧向稳定裕度: './ground/lateral_stability_margin.md',docs/index.md 也加了对应链接。
  3. 测试没人跑 —— 新增 .github/workflows/ground_module_tests.yml,matrix 跑五个模块的 tests/test_*_local.py(轮胎滑移率、侧翻裕度、工况能耗、舒适性传递率、本 PR 的侧向稳定裕度),paths 挂 src/ground/<module>/** 与对应测试文件。这样本 PR 的测试有 workflow 覆盖了,前面四个模块也一并纳入。

本地验证:tests/test_lateral_stability_margin_local.py 通过 116 项,失败 0 项(结论 PASSED)。

按贡献指南用 Squash and merge。

@xingwunian
xingwunian merged commit 44c27bb into OpenHUTB:master Nov 11, 2026
6 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