目标是省掉商用飞控软件的高昂成本，为开源社区提供一套可复现、可扩展的低成本方案， 最终形态是一台开源的「悟三」——支持硬件扩展、由神经网络驱动的飞行平台。
目前处于仿真阶段：动力学、控制、状态估计与风洞已经在环，硬件尚未开始。 本仓库交付的是一个用于开发和验证飞控算法的可微仿真平台，以及在其上得到的一整套 带量化证据的控制能力。
关于「神经网络飞控」这个目标：本仓库的基础设施（仿真、状态估计、参数辨识、 风洞）与控制器是不是神经网络无关，都是必需的；而神经网络控制本身尚未走通 —— 三条技术路线均得到负面结论，详见 当前边界。
参与开发请先读 CONTEXT.md —— 它记录设计决策的理由、已踩过的 陷阱、开发约定与路线图，是接手本项目的必要背景。
| 模块 | 状态 | 关键指标 |
|---|---|---|
| 六自由度刚体动力学 | 完成 | 四元数姿态 + 欧拉方程，RK4 积分，倾斜产生水平分量按解析解验证 |
| 可微 6-DoF 动力学 | 完成 | 双实现逐步对照，单步偏差 1.1e-13，200 步累积 3.6e-07 |
| 级联 PID（位置环 + 姿态环） | 完成 | 定点悬停终端误差 0.5 mm，收敛 1.97 s |
| 轨迹跟踪（含参考前馈） | 完成 | 1 m/s 直线跟踪滞后 0.9 mm（无前馈时 0.749 m） |
| 手动自稳模式 | 完成 | 阶跃满舵上升时间 0.37 s，超调 −0.001° |
| 状态估计 | 完成 | 互补滤波姿态误差 0.32°；IMU 预积分 + 位置校正；位置滤波器默认卡尔曼（噪声/延迟/机动三维度均优于 α-β，见 FilterShowdownTest） |
| 传感器误差模型 | 完成 | 白噪声 / 常值偏置 / 陀螺偏置随机游走 / 加速度计低通 |
| 风场模型 | 完成 | 常值风 / 1-cos 阵风 / Dryden 湍流 |
| 参数辨识 | 完成 | 质量 1.9% / 阻力 14.6% / 惯量 ~18%，开环预测误差降低 11 倍 |
| IMU 失效容错 | 完成 | 加速度失效/偏置检测 + 降级策略（信任位置预积分） |
| 制导与紧急返航 | 完成 | Mission / ReturnHome / EmergencyLand 三模式 + 轨迹限幅标定 |
| 飞行控制主循环 | 完成 | 独立 FlightControlLoop + HAL 抽象（仿真实现已验证） |
| 连续动作 PPO | 可用但未走通 | 定点悬停 0.103 m，比 PID 差 500 倍 |
| 打靶法 / 行为克隆 / MPC | 已验证不适用 | 三条路径均有负面结论与根因分析 |
| 硬件抽象层 | 仿真完成 | HalSensorReader/HalActuatorWriter/HalSetpointSource 抽象已定义， |
仿真实现 HalSimulator 已验证；真机实现未开始 |
┌──────────────────────────────────────┐
│ 控制层 core/control/ │
│ │
│ 定点 PID ── 级联位置环 + 姿态环 │
│ 轨迹跟踪 ── 加参考速度/加速度前馈 │
│ 手动自稳 ── 杆量 → 姿态指令 │
│ 打靶法 / MPC（离线规划） │
└──────────────┬───────────────────────┘
│ SixDofCommand
│ { thrust_body, torque }
┌──────────────▼───────────────────────┐
│ 被控对象 core/simulator/ │
│ │
│ 6-DoF 刚体 · 四元数姿态 · 欧拉方程 │
│ 气动阻力（按相对气流） │
│ 风场：常值 / 阵风 / Dryden 湍流 │
│ RK4 积分 · 推力与力矩限幅 │
└──────────────┬───────────────────────┘
│ SixDofState
│ { pos, vel, quat, omega }
┌──────────────▼───────────────────────┐
│ 感知层 core/estimation/ │
│ │
│ IMU 模型 ── 噪声 / 偏置 / 随机游走 │
│ 互补滤波姿态估计 + 陀螺偏置隐式估计 │
│ IMU 预积分预测 + 位置测量校正 │
└──────────────┬───────────────────────┘
│ 估计状态
▼
控制器（真值不参与闭环）
本仓库刻意区分「完美状态反馈」与「真机链路」，所有性能数字都注明属于哪一种：
理想反馈： 真值状态 ─────────────────────────────► 控制器
真机链路： 真值 ──► 传感器(带噪) ──► 状态估计 ──► 控制器
两者的差距就是这个飞控从仿真走向真机必须付出的第一笔代价。
| 状态来源 | 稳态位置 RMS | 稳态倾角 |
|---|---|---|
| 完美状态反馈 | 0.5 mm | 0.26° |
| 真机链路（带噪传感器 + 估计） | 22.3 mm | 0.81° |
真机链路的精度已被位置传感器噪声（20 mm）本身封顶 —— 继续优化算法不会让 真机精度变好，需要更好的位置观测。
四旋翼靠倾斜产生水平力。稳态时两条解析式成立，并已被实测精确验证
（k = 0.049 N·s²/m²，对应典型小四轴 Cd·A ≈ 0.08 m²）：
倾角： θ = atan(k·v² / (m·g))
偏移： e = k·v² / (m·kp)
| 风速 | 稳态偏移（实测 / 预测） | 稳态倾角（实测 / 预测） |
|---|---|---|
| 4 m/s | 0.1960 / 0.1960 m | 4.5693° / 4.5693° |
| 8 m/s | 0.7840 / 0.7840 m | 17.7278° / 17.7277° |
| 10 m/s | 1.2250 / 1.2250 m | 26.5651° / 26.5651° |
10 m/s 以下解析式精确成立。12 m/s 已触及 max_tilt_deg=35° 倾角上限，
实测偏移 5.84 m，远大于未饱和预测 1.76 m；14/16 m/s 完全失稳。有效抗风上限
约 11.84 m/s，由倾角上限决定（期望加速度限幅上限 15.65 m/s 在此配置下不生效）。
定点控制律 a = kp·(p_ref−p) + kd·(0−v) 隐含假设期望速度恒为零，用于跟踪时
存在系统性滞后，且可解析预测：
| 场景 | 无前馈 | 有前馈 | 改善 |
|---|---|---|---|
| 直线 1 m/s | 0.749 m 滞后 | 0.9 mm | ~800 倍 |
| 圆周 ω=0.5 rad/s | 0.3701 m | 0.0074 m | 50 倍 |
| 圆周 ω=1.0 rad/s | 0.7185 m | 0.0551 m | 13 倍 |
高频圆周的剩余误差不来自控制律，而来自姿态环带宽：提高带宽可直接改善 （9 → 25 rad/s 使误差从 0.4208 降到 0.1196 m）。
| 机动 | 指标 |
|---|---|
| 阶跃满舵（35°） | 上升时间 0.37 s，超调 −0.001°，高度偏离 0.004 m |
| 快速反向（+1 → −1） | 0.195 s 穿越水平，最大角速度 4.028 rad/s |
| 多轴联动（两轴各 35°） | 合成倾角 47.854°（非相加），高度偏离 0.009 m |
| 锥形机动方位角误差 | 与理论相位滞后 2·atan(ω/ωn) 吻合到 0.35% 以内 |
推力补偿使打杆不掉高：倾斜时竖直分量恒为 mg。补偿必须基于实际倾角，
用目标倾角会在过渡期过推（实测爬升 2.9 m）。
- C++23 编译器（Clang / GCC）
- CMake 3.16+
- CTorch（作为子模块位于
core/CTorch）
git clone --recursive https://github.com/Ghost-Silver/OpenInspire3.git
cd OpenInspire3
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j默认构建不依赖 GTest（OpenInspire3 顶层设置 TEST_ENABLED=OFF，关闭 CTorch 子模块的
gtest 测试组）。全量构建后 54 个 OI3 测试可执行文件全部通过。
# 核心验证（快）
./SixDofHoverTest # 六自由度定点悬停，11 项断言
./TrajectoryTrackingTest # 轨迹跟踪与解析预测验证，9 项
./StickManeuverTest # 打杆机动，12 项
./EstimatorTest # 状态估计与闭环消融，9 项
./WindTunnelTest # 抗风极限、阵风、湍流，17 项
./FlightControlLoopTest # 独立飞行控制主循环 + 降级协调，16 项
# 容错与制导
./PositionNonIdealClosedLoopTest # 光流/GPS 级噪声 + IMU 失效/偏置降级，36 项
./GuidanceIntegrationTest # 制导层与容错层集成，17 项
./TrajectoryLimitCalibrationTest # 速度与 jerk 上限标定，4 项
# 耗时较长
./ParameterIdTest # 可微仿真参数辨识
./ModelCalibrationTest # 模型校准收益
./SixDofGradTest # 可微动力学梯度一致性，17 项四旋翼不能直接产生水平推力。 水平运动只能靠倾斜机身、把竖直推力的一部分 转向水平。因此控制器必须是级联结构 —— 位置环先算出所需合力方向，姿态环再让 机体轴对准它。这是「飞控」二字的前提，也是三自由度质点模型无法替代六自由度的原因。
姿态误差的表示要选对。 定点控制只需把机体 z 轴对准推力方向，绕 z 轴的偏航 不受约束，所以用「轴角对齐 z 轴」就够了；手动模式下偏航是被直接操纵的自由度， 必须用完整四元数误差。
增益由物理量推导，而不是试出来。 姿态环增益按期望带宽与阻尼比配合各轴惯量
计算（kp = I·ωn²、kd = 2ζI·ωn），三轴闭环特性一致。惯量本身可以用参数辨识
从实测轨迹得到 —— 校准前手填值与真值相差 3350%，折算成增益误差 2844%。
控制律的结构性缺陷无法靠调参弥补。 定点 PID 用于跟踪时滞后恒为 (kd/kp)·v，
这是控制律缺失前馈的必然结果，调增益只会改变滞后的比例系数。
改控制律时不能让回归数据悄悄漂移。 加入轨迹跟踪入口时，定点路径的浮点运算
序列被刻意保持原样，使全部既有实测结果逐位不变 —— 已用 SixDofHoverTest 与
EstimatorTest 的逐位一致验证。
这一节如实列出做不到的事，避免误解项目状态。
未开始
- 硬件抽象层、嵌入式飞控软件、实时系统、试飞 —— 从仿真到真机的整段路。
- 失效保护、日志遥测、故障注入等真实飞控的标配基础设施。
已知局限
- 偏航不可观测：只有加速度计时，绕重力轴的陀螺偏置在物理上无法观测， 偏航会持续漂移（60 秒约 16°）。定住偏航必须引入磁力计或视觉航向观测。
- 位置通路不是真正的 EKF：采用 EKF 的结构（IMU 预测 + 观测校正），但增益 固定而非由协方差递推得到。当前用固定增益 α-β 滤波 + 位置残差死区处理 GPS 级 大噪声，光流级等小噪声场景保持默认关闭。
传感器速率不匹配未建模：当前 IMU 与控制器同为 1 kHz。已修复（2026-10-02）： 主循环原先硬编码dt = 1 ms，使系统只能在 1 kHz 附近工作（500 Hz 即失控、 250 Hz 坠地）。现改由 HAL 提供的 IMU 时间戳差分推导步长，500 Hz 与 250 Hz 均可正常悬停；HAL 不提供时间戳时回退到原默认值，既有行为不变。125 Hz 仍 发散，属位置环低采样率带宽不足（独立问题，已标注）。- IMU 器件级效应未建模：标度因数、三轴非正交、温度特性、量化噪声、采样抖动。
神经网络控制：三条路径的负面结论
| 路线 | 结论 |
|---|---|
| 离线专家生成（打靶法） | 计算模式的时间尺度不匹配；120 段解约 200 s，而 PPO 需要上千条轨迹 |
| 在线 MPC | 单次重规划约 0.96 s，实时性差两个数量级 |
| 参数辨识 | 唯一正面落点 —— 离线、一次性、不要求实时 |
定点悬停上 PPO 比 PID 差 500 倍；多机体素搜索上 MAPPO 目标发现率 0/20，而简单的 贪心基线 20/20。共同原因是所选任务太简单：简单方法的先验正好匹配问题结构， 学习需要海量样本才能重新发现同样的先验。
学习型控制的优势场景是难以建模的效应（气动干扰、载荷变化、故障容错），而这些 只在真机上才会显现。因此下一步不是继续在理想化仿真里挑战定点悬停，而是选一个 经典方法确实做不好的任务，并考虑混合架构（经典控制器保证稳定性， 神经网络只做前馈补偿与扰动估计）。
- 六自由度动力学与闭环控制
- 可微动力学与参数辨识
- 状态估计与传感器模型
- 轨迹跟踪与参考前馈
- 风场模型与抗风测试
- 手动模式与打杆机动
- 飞行控制主循环与 HAL 抽象（仿真层验证）
- IMU 失效容错、紧急返航与轨迹限幅标定
- 位置滤波器升级（位置-速度卡尔曼已设为默认；α-β 保留为可选回退）
- 混合架构：经典控制器 + 神经网络补偿项
- 强扰动下的敏捷机动（学习型控制的价值场景）
- 真机 HAL 实现与嵌入式飞控软件
- 硬件在环（HIL）测试
- 试飞
- CTorch —— 轻量级 C++ 深度学习框架， 为本项目提供可微仿真后端与自动微分能力。
笙歌 @ ShengFlow