Add JSBSim service backend
This commit is contained in:
moriy
379
service/F22_COBRA_RESEARCH.md
Normal file
379
service/F22_COBRA_RESEARCH.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# F-22 Cobra 机动研究记录
|
||||
|
||||
本文记录当前 JSBSim 眼镜蛇机动研究的现状、技术方案和已修改位置。范围覆盖 `service` 后端、`web-test` 前端、共享 schema，以及为 F-22 Cobra 研究复制出的本地飞机模型。
|
||||
|
||||
## 目前现状
|
||||
|
||||
项目当前以 `web-test` 为前端、`service` 为后端，通过本地 HTTP API 调用 JSBSim 完成飞行动力学仿真。
|
||||
|
||||
当前默认研究对象是：
|
||||
|
||||
- 前端 aircraftId: `f22cobra-jsbsim`
|
||||
- 后端 JSBSim model id: `f22cobra`
|
||||
- 模型文件: `service/aircraft/f22cobra/f22cobra.xml`
|
||||
- 后端服务: `http://127.0.0.1:4317`
|
||||
- 内部积分频率: `integrationRateHz = 120`
|
||||
- 输出采样频率: `sampleRateHz = 30`
|
||||
|
||||
当前 Cobra 默认参数是一个稳定的近似 Cobra 基线，而不是追求极限 120 度迎角的表演级参数：
|
||||
|
||||
```json
|
||||
{
|
||||
"aircraftId": "f22cobra-jsbsim",
|
||||
"durationSec": 5,
|
||||
"sampleRateHz": 30,
|
||||
"integrationRateHz": 120,
|
||||
"trim": false,
|
||||
"initialState": {
|
||||
"position": [0, 3000, 0],
|
||||
"velocityMps": 120,
|
||||
"headingDeg": 0
|
||||
},
|
||||
"maneuver": {
|
||||
"type": "cobra",
|
||||
"parameters": {
|
||||
"controlMode": "closed-loop",
|
||||
"entryDelaySec": 0.15,
|
||||
"pullDurationSec": 0.7,
|
||||
"holdDurationSec": 0,
|
||||
"recoveryDurationSec": 2.0,
|
||||
"targetAlphaDeg": 80,
|
||||
"recoveryAlphaDeg": 8,
|
||||
"pitchRateLimitDegS": 80,
|
||||
"holdPitchRateDegS": 0,
|
||||
"maxElevatorCmd": -0.45,
|
||||
"recoveryElevatorCmd": 0.65,
|
||||
"throttleCmd": 1,
|
||||
"pullTvcCmd": -0.05,
|
||||
"recoveryTvcCmd": 0.85,
|
||||
"speedbrakeCmd": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在当前 F-22 模型和上述参数下，直接 JSBSim 验证的典型指标约为：
|
||||
|
||||
- 峰值迎角 `maxAlpha`: 约 `71.9 deg`
|
||||
- 峰值俯仰角速度 `maxPitchRate`: 约 `122.9 deg/s`
|
||||
- 最低速度 `minSpeed`: 约 `106.4 m/s`
|
||||
- 5 秒末迎角 `endAlpha`: 约 `9.7 deg`
|
||||
- 5 秒末俯仰角 `endPitch`: 约 `31.0 deg`
|
||||
|
||||
这个状态的意义是：先获得可重复、能恢复、不会突然翻转的基线，再继续向更高 alpha 推进。
|
||||
|
||||
## 技术方案
|
||||
|
||||
### 1. 后端用 JSBSim 做 6DoF 积分
|
||||
|
||||
后端 `service/scripts/jsbsim_runner.py` 是 JSBSim 的 Python runner。Node 后端通过 `service/src/backends/jsbsimBackend.js` 调用该 runner。
|
||||
|
||||
关键点：
|
||||
|
||||
- `sampleRateHz` 只控制返回给前端的采样密度。
|
||||
- `integrationRateHz` 控制 JSBSim 内部积分步长，当前默认 120 Hz。
|
||||
- 仿真过程中内部积分按 `integrationRateHz` 推进，输出样本按 `sampleRateHz` 抽样。
|
||||
- F-22 研究默认 `trim: false`，因为 bundled F-22 在部分速度点纵向 trim 会失败，但直接 initial condition 可以运行。
|
||||
|
||||
### 2. 用本地 F-22 研究模型打开 TVC 控制
|
||||
|
||||
原始 bundled F-22 的 TVC 链路不适合直接外部命令控制。当前复制出本地模型：
|
||||
|
||||
```text
|
||||
service/aircraft/f22cobra/f22cobra.xml
|
||||
```
|
||||
|
||||
并加入/改造：
|
||||
|
||||
- `fcs/tvc-cmd-norm`
|
||||
- TVC actuator 输入改为外部命令。
|
||||
- 输出仍写到 `fcs/tvc-pos-norm` / `fcs/tvc-pos-rad`，供 JSBSim 气动和遥测读取。
|
||||
|
||||
这样后端可以通过 `fcs/tvc-cmd-norm` 直接施加 TVC 指令。
|
||||
|
||||
### 3. Cobra 从开环时间线升级为闭环控制器
|
||||
|
||||
早期 Cobra 使用固定时间线：
|
||||
|
||||
```text
|
||||
某时刻 elevator = X, tvc = Y, throttle = Z
|
||||
```
|
||||
|
||||
这种开环方式容易出现：
|
||||
|
||||
- 抬头过猛
|
||||
- 俯仰角速度尖峰
|
||||
- 高迎角后恢复不下来
|
||||
- 轨迹出现不自然的旋转或深失速
|
||||
|
||||
现在 `cobra` 默认使用：
|
||||
|
||||
```json
|
||||
{ "controlMode": "closed-loop" }
|
||||
```
|
||||
|
||||
闭环控制器每个积分步读取当前状态：
|
||||
|
||||
- `aero/alpha-rad`
|
||||
- `attitude/theta-rad`
|
||||
- `velocities/q-rad_sec`
|
||||
- `velocities/vtrue-fps`
|
||||
|
||||
然后计算：
|
||||
|
||||
- elevator command
|
||||
- TVC command
|
||||
- throttle command
|
||||
- speedbrake command
|
||||
|
||||
控制目标不是“固定时间点打多少杆”，而是：
|
||||
|
||||
- 拉起阶段限制 pitch rate
|
||||
- 接近目标 alpha 时自动减小拉起
|
||||
- 恢复阶段用 elevator + TVC 把 alpha 拉回低迎角
|
||||
- 避免过快掉速和深失速
|
||||
|
||||
旧的开环 Cobra 仍保留：
|
||||
|
||||
```json
|
||||
{ "controlMode": "open-loop" }
|
||||
```
|
||||
|
||||
这方便后续对比开环和闭环表现。
|
||||
|
||||
### 4. 姿态输出改用四元数
|
||||
|
||||
前端之前使用 Euler/HPR 处理姿态，在接近 90 度俯仰时容易出现视觉上的突然翻转。
|
||||
|
||||
现在后端输出 body-to-local ENU 四元数：
|
||||
|
||||
```json
|
||||
"rotation": [x, y, z, w]
|
||||
```
|
||||
|
||||
前端播放时用 quaternion slerp 插值，Cesium 渲染也直接使用四元数路径。这避免了高俯仰角附近的 Euler 奇异跳变。
|
||||
|
||||
### 5. 轨迹积分使用 JSBSim 地速分量
|
||||
|
||||
位置轨迹不再用 heading/pitch 自己推算水平位移，而是使用 JSBSim 输出的地球坐标速度：
|
||||
|
||||
- `velocities/v-east-fps`
|
||||
- `velocities/v-north-fps`
|
||||
|
||||
这避免了姿态大幅变化时轨迹方向和机体方向互相污染。
|
||||
|
||||
### 6. 前端加入 Cobra 参数面板和遥测面板
|
||||
|
||||
前端现在默认选中 `f22cobra-jsbsim` 和 `Cobra`。
|
||||
|
||||
Cobra 参数面板可以直接调：
|
||||
|
||||
- `Target alpha`
|
||||
- `Pitch-rate cap`
|
||||
- `Pull time`
|
||||
- `Recovery time`
|
||||
- `Pull elevator`
|
||||
- `Recovery elevator`
|
||||
- `Pull TVC`
|
||||
- `Recovery TVC`
|
||||
|
||||
右侧遥测面板显示关键曲线和 summary，便于判断问题来源：
|
||||
|
||||
- alpha
|
||||
- pitch
|
||||
- pitch rate
|
||||
- velocity
|
||||
- altitude delta
|
||||
- elevator command
|
||||
- TVC command
|
||||
- speedbrake command
|
||||
|
||||
## 修改的地方
|
||||
|
||||
### service 后端
|
||||
|
||||
#### `service/scripts/jsbsim_runner.py`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 新增 `integrationRateHz` 支持，默认 120 Hz。
|
||||
- 内部积分频率与输出采样频率解耦。
|
||||
- 新增/扩展 `cobra` maneuver。
|
||||
- 新增 `controlMode = closed-loop` 的 Cobra 控制器。
|
||||
- 保留 `controlMode = open-loop` 的时间线控制。
|
||||
- 控制输入支持：
|
||||
- elevator
|
||||
- aileron
|
||||
- rudder
|
||||
- throttle
|
||||
- tvc
|
||||
- speedbrake
|
||||
- 输出样本增加：
|
||||
- `alphaDeg`
|
||||
- `betaDeg`
|
||||
- `qbar`
|
||||
- `verticalSpeedMps`
|
||||
- `pitchRateDegS`
|
||||
- `rollRateDegS`
|
||||
- `yawRateDegS`
|
||||
- `controlInputs`
|
||||
- `controlSurfaces`
|
||||
- `fcs`
|
||||
- 姿态输出改为 ENU body quaternion。
|
||||
- 本地位置积分改用 JSBSim east/north velocity。
|
||||
|
||||
#### `service/aircraft/f22cobra/f22cobra.xml`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 从 bundled JSBSim F-22 复制出项目本地研究模型。
|
||||
- 模型名称改为 F-22 Cobra Research。
|
||||
- 新增 `fcs/tvc-cmd-norm` property。
|
||||
- TVC actuator 改为读取 `fcs/tvc-cmd-norm`。
|
||||
- 保证外部控制能驱动 `fcs/tvc-pos-norm`。
|
||||
|
||||
#### `service/src/backends/jsbsimBackend.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 新增 `f22cobra-jsbsim` aircraft。
|
||||
- 将 `integrationRateHz` 透传给 Python runner。
|
||||
- `cobra` / `control-script` 加入 JSBSim 后端支持列表。
|
||||
- F-22 研究机型标记为 high-alpha / TVC / no-trim experimental。
|
||||
|
||||
#### `service/src/backends/mockBackend.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- mock backend 同步支持 `integrationRateHz`。
|
||||
- mock 输出结构补齐部分 JSBSim 遥测字段。
|
||||
- 支持 `control-script` / `cobra` 的视觉测试路径。
|
||||
|
||||
#### `service/src/simulator.test.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 增加对 `integrationRateHz = 120` 的断言。
|
||||
- 增加 `control-script` / `cobra` 基础测试。
|
||||
|
||||
#### `service/scripts/sweep_f22_cobra.py`
|
||||
|
||||
主要作用：
|
||||
|
||||
- 批量扫描 Cobra 参数组合。
|
||||
- 计算 max alpha、max pitch、min speed、end alpha、end pitch、forward delta 等指标。
|
||||
- 用 score 排序，辅助后续自动调参。
|
||||
|
||||
### shared schema
|
||||
|
||||
#### `shared/schemas/flight-sim-api.schema.json`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 新增 `integrationRateHz`。
|
||||
- 新增 `trim`。
|
||||
- maneuver enum 增加：
|
||||
- `control-script`
|
||||
- `cobra`
|
||||
- sample schema 增加遥测字段：
|
||||
- `qbar`
|
||||
- `verticalSpeedMps`
|
||||
- `pitchRateDegS`
|
||||
- `rollRateDegS`
|
||||
- `yawRateDegS`
|
||||
- `controlInputs`
|
||||
- `controlSurfaces`
|
||||
- `fcs`
|
||||
- Cobra 参数说明中记录 `controlMode=open-loop|closed-loop`。
|
||||
|
||||
### web-test 前端
|
||||
|
||||
#### `web-test/src/api/simulationService.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 默认 aircraft 使用 F-22 Cobra research。
|
||||
- 默认 `sampleRateHz = 30`。
|
||||
- 默认 `integrationRateHz = 120`。
|
||||
- F-22 research 默认 `trim = false`。
|
||||
- Cobra 默认参数改为稳定闭环基线。
|
||||
- 支持从前端 Cobra 参数面板覆盖默认参数。
|
||||
- 参数进入请求前做范围 clamp。
|
||||
|
||||
#### `web-test/index.html`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 默认 maneuver 改为 Cobra。
|
||||
- 默认 duration 改为 5 秒。
|
||||
- 默认 speed 改为 120 m/s。
|
||||
- 新增 Cobra Controller 参数面板。
|
||||
- 新增遥测 canvas 面板。
|
||||
|
||||
#### `web-test/src/ui/controls.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 读取 Cobra 参数面板输入。
|
||||
- `getValues()` 返回 `cobraParameters`。
|
||||
- 非 Cobra 机动时隐藏 Cobra 参数区。
|
||||
|
||||
#### `web-test/src/ui/researchPanel.js`
|
||||
|
||||
主要作用：
|
||||
|
||||
- 绘制 Cobra 遥测曲线。
|
||||
- 输出 summary：
|
||||
- max alpha
|
||||
- max pitch
|
||||
- max pitch rate
|
||||
- min speed
|
||||
- end alpha
|
||||
- speedbrake 状态
|
||||
|
||||
#### `web-test/src/playback/trajectoryPlayer.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 使用四元数 slerp 插值姿态。
|
||||
- 减少高俯仰角播放时的姿态跳变。
|
||||
|
||||
#### `web-test/src/renderer/cesiumScene.js`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 支持后端 quaternion rotation。
|
||||
- Cesium aircraft orientation 从本地 ENU body quaternion 转换到世界坐标。
|
||||
- 保留 HPR fallback。
|
||||
|
||||
#### `web-test/src/styles.css`
|
||||
|
||||
主要改动：
|
||||
|
||||
- 增加 Cobra 参数面板样式。
|
||||
- 增加遥测面板样式。
|
||||
- 调整移动端布局。
|
||||
|
||||
## 当前限制
|
||||
|
||||
1. 当前 F-22 XML 的高迎角 / 失速后气动可信度有限。
|
||||
2. 目前稳定基线只能做到约 70-72 度 alpha，继续推高 alpha 容易进入深失速或恢复困难。
|
||||
3. `speedbrakeCmd` 在该 F-22 模型中更像离散开关，部分小数指令不会有效展开。
|
||||
4. 目前闭环控制器是工程研究用，不是完整真实 FCS。
|
||||
5. 参数 sweep 还没有接入前端，只能通过脚本跑。
|
||||
|
||||
## 下一步建议
|
||||
|
||||
1. 把 `sweep_f22_cobra.py` 接到 service API，支持前端一键 sweep。
|
||||
2. 增加 Cobra 参数 preset：
|
||||
- stable baseline
|
||||
- high-alpha attempt
|
||||
- aggressive TVC recovery
|
||||
- open-loop comparison
|
||||
3. 为机动研究抽象统一 controller 接口，后续复用到：
|
||||
- Herbst maneuver
|
||||
- Kulbit
|
||||
- J-turn
|
||||
- tailslide
|
||||
4. 进一步寻找或构建更可信的高迎角/失速后 F-22、Su-27、F-16 MATV 等 JSBSim 模型。
|
||||
5. 增加自动评分指标，把“像不像 Cobra”量化，而不是只靠视觉判断。
|
||||
Reference in New Issue
Block a user