planecontrol —— 飞控控制律(基于模型的设计)

多旋翼控制律的**基于模型的设计(MBD)**工程:用 MATLAB/Simulink 建模,内环与外环 均采用 ADRC(自抗扰控制),直接对接 auxpilot 飞控固件(Embedded Coder 生成 C 代码)。

  • 机型:多旋翼(X 型四旋翼,矩控混控)
  • 控制结构:航线管理/制导(航点状态机)→ 姿态角环(ADRC)→ 角速率环(ADRC)→ 混控 → 4 路电机 PWM
  • 控制频率:200 Hz(= auxpilot 的 BOARD_CTL_HZ)
  • 交付:SIL 仿真验证 + Embedded Coder 代码生成,接入 auxpilot/middleware/model/
  • MATLAB 版本:R2024a 起。*.slx / *.sldd 以 R2024a 格式入库——R2024a 装有 Embedded Coder / Simulink Coder / Aerospace Blockset,是实际出码的版本;R2026a 未授权这些产品、且默认工具链未注册,出码会失败,但能向下打开本工程的模型与字典。 换版本重建时(build_all / autoGenFilesInit)产物的格式会随之改变,请用 R2024a 重建后再提交,以免把模型升到 R2026a 格式而让 R2024a 打不开。

五个模型 = 三个壳(AP / SIL / HIL)+ 两个被引用的模块

模型 属于 角色 可独立生成代码
autopilot (被三壳引用的模块,不是壳) 自驾仪:指令(Ap_Cmd)+ 参数(Ap_Param)+ 导航(NAV)+ 控制律(CTL)+ 通讯(COMM_RX/COMM_TX);即「一整套飞行与控制」 是(→ 烧飞控)
model (被 SIL/HIL 引用的模块,不是壳) 飞机模型:Aerospace 6DoF (Quaternion) + 本工程推进/气动,结构真源 models/model.xml 否(6DOF 含连续状态,ERT 不支持)
ap AP 壳 HAL(pc_hal.c,C Caller)+ autopilot;无对象 —— AP 壳的对象是真实飞机 否(引用 autopilot)
sil SIL 壳 设备模型 HAL(pc_sim.c,C Caller)+ autopilot + model 否
hil HIL 壳 硬件帧 HAL(pc_hal.c,C Caller,4 处 [HIL-IO *] 替换点)+ autopilot + model 否

另有 test/assets/model_ref.slx(回归基准,不进构建)与 test/assets/prop_fixture.xml (XML 方言测试夹具)。全部构建产物 .slx = 5 个(上表:3 壳 + 2 模块)+ 1 个测试基准(model_ref.slx)。三个壳的形状: AP = HAL + Autopilot;SIL = HAL(设备模型) + Autopilot + MODEL;HIL = HAL(硬件帧) + Autopilot + MODEL。 机型变体(原 _heavy)与演示模型(原 model_prop)已按「只要三个壳」精简掉。 pc_ctl / pc_nav 只在出码时于 work/ 里临时生成,不入库。

导航(NAV)与控制律(CTL)不再是独立模型,而是 autopilot.slx 内部的子系统: 由 build_nav / build_ctl 的「合并模式」直接画进宿主子系统(全工程只剩一个装配文件)。 装配(SIL / HIL)只引用 autopilot / model、不复制;固件侧仍需 pc_ctl_* 接口时由 gencode_ctl 用同一份内容构建器在临时目录生成 pc_ctl.slx 出码(内容与 autopilot 内的 CTL 子系统同源、不会漂移),pc_nav 同理。见第 5 节。

固定翼(Cessna 172)平行轨道:三壳 + C 内核 + 验证体系

与多旋翼主线并行独立:独立参数/模型/文件前缀(c172_* / fw_* / sil_c172 / hil_c172), 不改动四旋翼链路;固定翼有自己的 85 项回归 c172_all(quick 82 项)。HIL 移植清单见 doc/hil_porting.md (已实测 ARM Cortex-M4F/M4 交叉编译:32/32 文件通过)。 入口文档:doc/C172_SUMMARY.md(交付总览)、doc/C172_STATUS.md(状态/验收/边界)、doc/C172_VERIFICATION_MATRIX.md(验证矩阵)、doc/fixedwing_report.md(阶段性工程报告)、doc/fixedwing.md(总览)、 doc/architecture.md §17(逐轮技术记录 17.1~17.197)、doc/gcs_ng_integration.md(跨工程 GCS)、doc/gcs_ui_automation.md(GCS UI 自动化清单)。

壳 固定翼产物 组成 C 形态(出码)
AP controllers/fw/autopilot_fw.slx(被 SIL/HIL 引用) HAL 接口 + 自驾仪(纵向 PID 串级/LQR 可选 + 横航向 PID + 自动配平 + 风补偿) fw_ap_cstep(gencode_fw_ap)
SIL models/sil_c172.slx HAL(设备模型)+ AP + models/c172.slx(对象模型) c172_step + fw_ap_cstep(C 全栈 c172_mission_closeloop)
HIL models/hil_c172.slx HAL(帧协议 $CMD/$SENS/$TLM/$WARN)+ AP + 对象模型 c172_hil_mission_run(帧驱动任务运行器)
任务层壳 models/task_cfun_fw.slx C Function 块封装任务管理器出码(5 入/3 出,Simulink 内可仿真) fw_mission_cstep(gencode_fw_mission)

对象模型(1:1 参数化,数据可追溯)

  • 参数真源 core/model/c172_params.m(几何/惯量/气动表/导数/发动机/螺旋桨,来源 JSBSim c172x + eng_io320 + prop_75in2f, 原始文件注明 Cessna 172P Information Manual 1982 / FAA TCDS 3A12);
  • MATLAB 内核 c172_step(14 状态四元数 6DoF + ISA + 襟翼 + 地面效应 + 变质量 + P 因子/滑流 + 地面接触), C 内核默认 15 状态(失速动态启用,gencode_c172),MATLAB 内核 14/15 状态按需分派(c172_core 共用核心); MIL Simulink 对象模型 models/c172.slx 由 build_c172 从 XML 生成(失速迟滞默认启用,hyst=false 可回静态), 物理项(气动主表/地面效应/变质量/P 因子/滑流/失速迟滞/地面接触)均已与内核同步(构建选项 mdot/hyst/gear);
  • 配平求解 c172_solve_trim、风/大气 c172_wind/c172_dryden;

控制与任务

  • 自驾仪 fw_ap_step(纵向 PID 串级:速度→油门、高度→俯仰→俯仰角速率;横航向:航向→滚转→滚转角速率; 偏航阻尼+侧滑协调;自动配平前馈 fw_ap_settrim;在线风估计 fw_wind_est + 风补偿);
  • 研究分支:纵向 LQR(fw_lqr_long)、外环 LQR(fw_lqr_outer)、增益调度(fw_lqr_sched,7×7 网格 + 包线保护)、 LQR 外环自驾仪 fw_ap_lqr;
  • 任务层:L1 航线制导 fw_nav_step、自动起飞/着陆律 fw_takeoff_law/fw_landing_law、任务管理器 fw_mission_step (模式 0 空闲/1 起飞/2 航线/3 下降/4 着陆/5 故障保护;故障枚举与恢复;C 形态 fw_mission_cstep);

验证(85 项,c172_all;quick 82 项):

类别 数量 代表项
对象模型(内核/系数/配平/风/地面/失速) ~22 c172_trim_check、c172_core_check、c172_ground_check、c172_stall_hyst_check
自驾仪/制导/任务 ~9 c172_ap_check、c172_route_wind_check、c172_mission_manager_check、c172_mission_dynstall_check
三壳/C 代码/协议/性能 ~15 c172_three_shell_check、c172_mission_closeloop_check、c172_hil_bidir_check、c172_bench/c172_proto_bench、c172_sil_udp_check(跨工程)、c172_nav_exec_check(C 航线执行)
MIL 对象模型同步 5 c172_sim、c172_mil_ge_check、c172_mil_mass_check、c172_mil_pf_check、c172_mil_hyst_check、c172_mil_gear_check
Simulink SIL 3 c172_sil_check、c172_sil_wind_check、c172_sil_nav_check
故障/告警/极端/制导内核 ~12 c172_fault_envelope_check、c172_spin_check、c172_stall_warning_check、c172_warn_proto_check、c172_fault_modes_check、c172_sensor_*、c172_slew_check、fw_nav_kernel_geom_check、fw_nav_l1_closeloop_check

关键指标(实测):配平 55 m/s@1000 m:α=1.34°、de=2.60°、thr=0.850、L/D=8.88;失速 CLmax=1.447@14.9°; 地面效应近地油门 −3.2%;自动起飞 635 m/34.1 m/s;着陆接地 31.9~32.4 m/s;全任务 580 s、5 航点; 风补偿侧偏 907→68 m;Dryden RMS 1.51/1.49/0.90;LQR 外环高度阶跃调节 2.5 s;失速迟滞宽度 4.19°; C 闭环单步 0.16 µs、协议往返 5.4 µs/帧(200 Hz 余量 >900×)。

C 侧完整链路:test/c/ 下有对象模型 runner、闭环、航线闭环、任务链全栈闭环、HIL 帧运行器、双向帧联调、 性能基准与协议基准;全部与 MATLAB 参考逐拍一致(1e-11~1e-17)。HIL 帧协议双格式:文本帧(默认, 联调/日志可读,往返 5.4 µs)与二进制帧(可选,168 B/往返 0.12 µs,快 29×,适合 1 kHz+)。

跨工程 GCS 接入(2026-10,已实现)

  • gcs-ng 侧新增机型桥接 orchestrator/cmd/silc172(GCSCOM 原生,机型清单 sil/c172/): SIL 模式:GCSCOM ⇄ $SET/$STATE 外部 C172 模型(test/c/c172_sil_udp.c:对象模型+级联 AP+L1 航线执行+告警); HIL 模式(--ext-mode hil):GCSCOM ⇄ HIL 服务器 $CMD/$WARN ⇄ plant $STATE 广播 (test/c/c172_hil_udp_run.c + c172_hil_plant.c,锁步 1 SENS↔1 TLM↔1 步);
  • 已覆盖:遥测(STATE/ATT/POS/VEL/MODE/BAT/GNSS/SYS/RC/EVENT + ALERT)、指令(含 1010 执行航线/1011 暂停)、 参数 8 项 AP 增益、航线上传/下载/选择/执行/跳转、文件业务(上传 SHA256/CRC 校验、下载、删除/管理);
  • 一键联调:tasks/verify/c172_gcs_ui_launch.ps1(SIL;-Hil 为 HIL 三进程栈;抓帧验证);清单 doc/gcs_ui_e2e.md;
  • UI 自动化(CDP,2026-10):一键全回归 tasks/verify/c172_gcs_ui_all.ps1(10/10 PASS,576.9 s);指令面板 8 类点击 → 桥接 CMD 按序验证(解锁/上锁/待机/工作/执行航线/暂停航线/一键起飞/返航); 任务页真实交互、设置页 6 子页、参数面板 8/8 读取 + 写入回读闭环(Kalt 0.06↔0.05);SIL 与 HIL 两壳 UI 截图(doc/figures/gcs_hil_ui.jpg); 明细与一键命令见 doc/gcs_ui_automation.md;
  • 工程文档:doc/gcs_ng_integration.md(协议表/链路/验证)。

CI 入口(跨仓)

入口 内容
tasks/verify/c172_crossrepo_ci.ps1 跨仓快速 CI(gcs-ng verify + C 航线执行,~2 min)
同上 -WithQuick / -WithFull / -WithUI + quick 82 项(~27 min)/ + 全量 85 项(~36 min)/ + GCS UI 全回归 10 项(~10 min)
tasks/verify/c172_nav_exec_ci.bat C 航线执行检查(独立 MATLAB 进程)
tools/ci/install_hooks.ps1 双仓 pre-push 钩子(推送前自动跑快速跨仓 CI)
gcs-ng tools/verify.ps1 gofmt/vet/build/定向 go test 门禁

边界:gcs-ng 接入已实现(上述);HIL × GCSCOM 直连未实现(C172 HIL 走 C 帧运行器,gcs-ng/hil/pc 为四旋翼主线); 失速动态默认启用评估已通过(标称任务无影响);MIL 与内核差异仅剩数值积分格式(ode4 vs Euler)与可选失速模型。

模型布局(自动布局引擎)

全部 *.slx 的块坐标由 tasks/build/+mbd/autolayout.m 按数据流分层统一排布: 建图 → 丢回边(反馈回路)→ 最长路径分层 → 层内重心排序(Inport/Outport 固定两侧)→ 按端口数定块高 → 过宽的长链(且基本前馈)蛇形折行;掩码/库链接块(如 Aerospace 6DoF) 尺寸与内部不动,注解自动避让。由 build_model / build_autopilot / mbd.assembly / build_hil / smoke_xml2mdl_v2 在保存模型前调用,故每次重建都得到同一张可读的图。

  • 体检闸门:pc('run','verify_layout')(或 R = layout_report())→ 自有系统 零重叠 + 画布宽高比有界,报告落 work/layout/layout_report.md(当前 37 个系统全过)。
  • 细节与两个坑(模型引用惰性走线导致的"引用脏模型"、Fit to view 不能落盘)见 doc/architecture.md §14。

三壳架构:AP / HIL / SIL(一个内核 + 三个壳)

内核只有一份(参数 / 航线 / 通讯 / 指令 / 控制逻辑 / 控制律 + HIL·SIL 的飞行动力学), 壳是内核外面的边界层;三个壳装同一个内核(同一个 pc_autopilot_step), 对外接口刻意不一致:

壳 对外接口 传感器 执行输出 壳内对象 壳内环境 实体
ap HAL + 链路字节 真实惯导(壳外)+ 遥控 µs / 电池 执行机构 µs 无(真实飞机) 无 auxpilot 固件
hil HAL 硬件帧 + 链路字节 硬件帧 执行机构 µs 有(仿真) 硬件/占位风 hil.slx / gcs-ng/hil/pc(HIL_PC.exe)
sil 设备模型 + 框架 + 归一化 pwm 设备模型合成惯导 + 框架给归一化遥控 归一化 pwm 有(仿真) 常值风 + Dryden 湍流 + 突风 sil.slx / gcs-ng/sil/pc(SIL_PC.exe)
  • 真源:shells/shell_registry.m(壳)+ shells/spec_shell.m(对外接口契约)+ data/bus_define/pc_iface.xlsx(边界 C 接口,按域);壳的边界实现只有两处 shell_sense / shell_act,内核一行不改。详见 doc/shells.md。
  • 桌面即可跑三壳对照(不需要 Simulink / 硬件 / 编译器): sim_shells; 或 L = shell_run('sil', shell_scenario('sil'), 400); (SIL 与 HIL 的内核输出与轨迹逐位一致 —— 差别只在对外接口)。
  • 闸门:run_tests 里的 t_shell_registry(接口派生/产物/两两不同)与 t_shell_contract(SIL≡HIL、AP 无对象、µs 口径与 pc_hal.c 一致、壳内对象同源); 报告 pc('run','verify_shells') → work/shells/shell_report.md。

飞行动力学模型(core/model/,壳内共用一份)

model_quad_x 只做编排(6 自由度刚体 + 四元数 + 前向欧拉),物理分层: model_atmos(ISA 大气密度)· model_rotor(k_T·ω² + 地效 + 诱导功率/轴流修正)· model_aero(阻力 + 压心力矩)· model_ground_force|clamp(弹簧-阻尼-摩擦地面接触)· model_wind(常值风 + Dryden 湍流 + 1-cos 突风)。

★ 中性默认 = 回归红线:新增系数全为 0(model_params.m)时,与补物理之前的旧实现 逐位一致(t_fd_neutral 用冻结旧实现做 6 场景逐位对照),既有整定结论不变; 打开系数即得到更完整的动力学。验证报告:pc('run','verify_fd') → work/verify/fd_report.md(配平 / 悬停线性化极点 / 地效曲线 / ISA 剖面 / 湍流统计 / 地面接触)。

固定翼(Cessna 172)模型与自驾仪/导航

工程内另含一套独立的固定翼 1:1 参数化模型(塞斯纳 172P)及配套自驾仪、航线制导, 与四旋翼主线并行、互不影响:

  • 阶段性工程报告:doc/fixedwing_report.md;总览与参数/验证矩阵:doc/fixedwing.md (详细技术记录见 doc/architecture.md §17)
  • 模型生成:build_c172 / build_fw_ap / build_nav_fw / build_sil_c172 → models/c172.slx、controllers/fw/*.slx、mainModels/sil_c172.slx
  • 一键回归:c172_all(79 项,含 Simulink SIL,约 31 分钟);c172_all('quick',true)(76 项,约 22 分钟)
  • C 侧组件:gencode_c172 / gencode_fw_ap / gencode_fw_nav

1. 为什么单独一个仓库

auxpilot 里只保留接入点(middleware/model/ctl_model*.{h,c}),控制律本体 (模型、参数、仿真、测试、生成脚本)放在本仓库,好处是:

  • 控制律可以独立于固件做 SIL / 参数扫描 / 回归,不用烧板子;
  • 模型与算法(core/)是唯一真源,Simulink 与 SIL 仿真、单元测试共用同一份数学;
  • 换控制律不动固件,只换生成代码。

2. 目录结构

planecontrol/
├── planecontrol.prj        MATLAB 工程 ★ 入口:打开它,路径与快捷方式自动就绪
├── .gitattributes          *.slx 声明为二进制 + mlAutoMerge
├── .gitignore              忽略 work/ 与全部生成物(模型/字典/Excel/清单);仓库只留源码与真源
├── resources/              工程元数据(MATLAB 维护,随工程一起入库)
├── README.md
├── core/                    ★ **内核**(MATLAB,可生成 C 代码):唯一真源,按功能域分子目录
│                            (参数 / 航线 / 控制律 / 控制逻辑 / 通讯 / 在环飞行动力学,三壳共用同一份)
│   ├── shared/             枚举/接口生成物(ap_types / nav_types / pc_enums_gen / pc_iface_gen)+ 通用小工具 util_*
│   ├── cmd/                指令解算与参数台账(ap_cmd_step / ap_param_table / ap_param_*)
│   ├── control_law/        ADRC 核心(adrc_*)+ 姿态/速率环 + 混控;整定真源 ctl_params_quad_x
│   ├── nav/                航线管理/制导(nav_step / nav_lat_guidance / nav_alt_hold / nav_leg_geom)+ 外环枚举 afcs_types
│   ├── flight_mgmt/        飞行阶段状态机(nav_stage_step)
│   ├── comm/               地面站通讯域(ap_comm_step / ap_comm_types)
│   ├── device/             SIL 设备模型(pc_dev_step)
│   ├── plant/              飞行动力学(model_quad_x 编排 + model_atmos / model_rotor / model_aero / model_ground_* / model_wind + pc_model_step)+ 机型注册 aircraft_registry / aircraft_names / aircraft_params
│   ├── health/             健康/故障域(health_step / health_state_init / hal_health_types)
│   ├── autopilot/          整机单拍 pc_autopilot_step.m ★ SIL/HIL 内核的唯一入口
│   └── sim/                SIL/HIL 专属参数真源 sim_params.m
├── shells/                 ★ **三个壳(AP / HIL / SIL)**:内核外面的边界层
│   ├── shell_registry.m    三壳唯一真源(对外接口 / 传感器来源 / 执行量纲 / 是否有对象与环境)
│   ├── spec_shell.m        壳的对外接口契约(与 utilities/spec_*.m 同族)
│   ├── shell_iface.m       由 registry + 接口注册表派生对外函数/常量/头
│   ├── shell_sense.m       边界感知:按壳把对外输入折成内核输入(HAL µs / 硬件帧 / 设备模型)
│   ├── shell_act.m         边界执行:按壳把内核输出折成对外量(µs 或归一化 pwm)
│   ├── shell_step.m / shell_run.m / shell_scenario.m / shell_u_init.m
│   └──                      桌面三壳运行器(壳内对象 = core/plant,壳内环境 = core/model/model_wind)
├── libraries/mbd-tools/    可复用 MBD 工具(随仓内置):Excel → .sldd/头/注册表 + xml2mdl v1/v2 结构引擎
├── models/                 ★ 飞机模型模块:结构真源 <机型>.xml(v2 方言)→(生成,不入库)<机型>.slx + <机型>_mdl_init.m
├── mainModels/             顶层装配(生成,不入库):sil.slx / hil.slx + 机型版
├── controllers/
│   └── autopilot/          顶层模块 autopilot.slx(生成,不入库;内含 NAV / CTL 子系统)
│                           + 边界 C 源码(pc_ap_comm.c / pc_hal.c / pc_sim.c / pc_ap_comm_ext.h 手写;pc_{hal,ap_comm,sim}.h 生成)
├── data/                   ★ 数据:真源 Excel 与其生成产物
│   ├── bus_define/         手改真源只有两个:pc_io_busdef.xlsx(边界帧)、pc_routes.xlsx(航点表);
│   │                       其余 *_busdef / pc_enums / pc_iface 由 core/ 下真源经 update_* 生成(勿手改)
│   └── autoGenFiles/       由 Excel 生成的 .sldd / .h / .md(生成物,不入库;含按机型的字典引用图)
├── sim/                    仿真验证
│   ├── sim_make_u.m        构造一份"可飞"的输入
│   ├── sim_adrc_axis.m     单轴 ADRC 阶跃演示
│   ├── sim_closedloop.m    双环闭环 SIL(滚转/俯仰/偏航阶跃)
│   ├── sim_shells.m        三壳(AP/HIL/SIL)对照演示:同一个内核、不同的对外接口
│   └── sim_nav.m           航线管理闭环 SIL(起飞→巡航→盘旋→返航→降落)
├── test/                   单元测试(run_tests.m 统一入口 + t_*.m 各域用例,纯 MATLAB 不需 Simulink)
│   └── assets/             回归资产(model_ref.slx:XML 化前的对象模型,compare_model 的比对基准)
├── tasks/                  全部任务脚本,按「数据 / 构建 / 出码 / 校验 / 分析」分组
│   ├── data/               真源 → Excel → 字典:update_{enums,iface,nav,pc_params,plant,sim} + autoGenFilesInit
│   ├── build/              模型装配:build_all / build_{plant,autopilot,ctl,nav,sil,hil} + blk_*.m + +mbd/ + smoke_xml2mdl_v2
│   ├── gen/                出码:gencode_{autopilot,ctl,nav,plant,autopilot_c,sim_c,params_c} + gen_ert(ERT 出码内核)
│   ├── verify/             校验:compare_model + smoke_xml2mdl_v2 + fd_validate(飞行动力学报告)+ shell_report(三壳对照报告)+ layout_report(模型布局体检)
│   ├── tools/              工具层:pc() 编排 / 产物溯源清单 / 脚手架 / 跨仓同步(见 §2「工具层」)
│   └── ctrl/ mode/ trim/ unc/   学科分析:线性化/裕度/b0、模态耦合、配平表、不确定性打靶(报告落 work/<域>/)
├── utilities/              工程环境与根 IO 契约
│   ├── spec_env.m          公共契约:路径 / 频率 / PWM 路数 / 模型名
│   ├── spec_ctl.m / spec_nav.m / spec_model.m / spec_autopilot.m   各**模块**(内核)的根 IO 契约
│   │                       ※ **壳**的对外接口契约不在这里,在 shells/spec_shell.m
│   ├── path_bootstrap.m    环境自举:加搜索路径 + 把缓存/出码目录指到 work/ ★ matlab -batch 的入口
│   ├── startup.m           工程启动(调用 path_bootstrap + 注册常量 + 版本检查)
│   ├── shutdown.m          工程关闭(还原 fileGenControl)
│   ├── startVars.m         把工程常量(mdl_name / ctl_hz 等)注册到 base
│   └── checkVersion.m      git 版本检查(脏工作区 warning)
├── doc/
│   ├── architecture.md     总体架构文档:现状 / 目标态 / 迁移清单 + 与 auxpilot 的接口契约(根 IO 字段表 / 单位 / 开关)
│   └── shells.md           三壳架构(AP / HIL / SIL):对外接口、内核、边界、运行与验证
└── work/                   构建产物(.gitignore 忽略,随工程自举自动创建)

树即架构:core/ = 内核(三壳共用,唯一真源);shells/ = 三个壳(AP / HIL / SIL 的对外接口与 边界适配);models/ + mainModels/ + controllers/autopilot/ = 产物与跨仓边界 C。 controllers/autopilot/ 的路径被固件与 gcs-ng 硬编码,不要移动。

归属分类(新增文件时先问自己属哪一类,避免再次长歪):

类别 位置 判据
内核真源 core/(参数 / 航线 / 控制律 / 控制逻辑 / 通讯 / 在环飞行动力学) 三壳共用的唯一真源
壳真源 shells/(三壳的对外接口与边界适配) 壳只在"边界"上不同,内核一行不改
数据/结构/契约真源 data/bus_define/*.xlsx、models/*.xml、utilities/spec_*.m(模块)、shells/spec_shell.m(壳) 手改的只有这些
产物(不入库) models/*.slx、mainModels/*.slx、*.slld、data/autoGenFiles/*、data/bus_define/ 下生成的 xlsx、controllers/autopilot/pc_{hal,ap_comm,sim}.h 生成物勿手改;pc('all') 重建
工具 libraries/mbd-tools(随仓内置,可整目录复制到别的工程复用)、tasks/{data,build,gen,verify,ctrl,mode,trim,unc}(本工程专用)、tasks/tools(编排/溯源/脚手架) 新脚本按此归位
中间产物 work/(缓存、出码、报告、临时模型) 一律不入库

源码 / 生成物边界(2026-10-17 工程瘦身):仓库只保留源码与真源,下列产物一律不入库、 由 pc('all') 按依赖增量重建:模型 *.slx、字典 *.sldd、data/bus_define/ 下生成的 Excel (除手改真源 pc_io_busdef.xlsx / pc_routes.xlsx)、data/autoGenFiles/、生成头 controllers/autopilot/pc_{hal,ap_comm,sim}.h、data/gen_manifest.json、布局对比图。 一键清理(默认干跑):clean_generated(); clean_generated('apply', true); 一键重建:pc('all')(按类 pc('all','kind','data') / 'build' / 'gen')。 新克隆 / 刚清理的树没有可直接打开的模型,先重建;这是「仓库只放源码」的权衡结果。

构建产物不落仓库根:matlab -batch 不执行工程启动文件,Simulink 缓存默认落当前目录。 所以离线/脚本方式跑一律用 utilities/path_bootstrap.m 自举(startup.m 内部也调它), 它把 CacheFolder / CodeGenFolder 指到 work/,仓库根不再产生 *.slxc / slprj/:

matlab -batch "addpath('utilities'); path_bootstrap; run_tests"

*.slx 由 tasks/build/build_*.m 程序化生成,同时也入库:这样在 planecontrol.prj 工程里可以直接双击打开模型,不必先跑构建脚本。.gitattributes 已把 *.slx 声明为二进制 + mlAutoMerge。改了脚本(build_*.m / blk_*.m / core/*.m)之后,请重跑 build_all 再提交,保持脚本与模型一致。

工具层:pc() —— 编排 / 溯源 / 脚手架

任务脚本不必再"记顺序、手敲一串",走工具层(tasks/tools/,用法见 pc.m 头注):

命令 作用
pc('list') 打印工具表(tasks/tools/pc_registry.m 是工具与依赖的唯一真源)
pc('plan') 干跑:逐条"最新 / 待跑 + 原因"(判据 = data/gen_manifest.json 里的输入真源指纹)
pc('all') 按依赖顺序跑过期工具(增量);'kind','data' 可只跑一段(data / build / gen / sync / verify)
pc('check') 过期报告 + run_tests + compare_model → work/reports/check.md
pc('sync') 把 C 内核与参数片段同步到 auxpilot、gcs-ng(幂等:内容一致就跳过,不产生无意义 diff)
pc('new-aircraft', id) 新机型脚手架:参数真源 + 结构 XML + 注册一行;随后 pc('all') 自动重建该机型全链
pc('new-iface', 名, 域) 新边界接口脚手架:真源 Excel 追加行 → 重新生成头/注册表 → 断言 .c 实现存在

为什么要"产物溯源":真源 → 产物是多段流水线,此前只有枚举 / 接口 / 参数台账三处有逐字节闸门, 其余链路上"改了真源忘了重跑"全靠人记。data/gen_manifest.json(入库)记下每个工具的输入真源指纹与 产物清单,于是 pc('plan') / pc('check') 能直接回答"这个产物还是不是当前真源的产物" —— 换机器、清空 work/ 之后同样成立。每次执行的完整输出落在 work/reports/<工具id>.log。

命令行(不打开工程)走 -sd utilities,MATLAB 会执行该目录下的 startup.m(= path_bootstrap):

% 增量重建 + 出一致性报告
matlab -sd utilities -batch "pc('plan')"
matlab -sd utilities -batch "pc('all')"

单独跑旧脚本(update_nav / build_all / gencode_autopilot_c …)依然可用、不会坏, 只是清单不会自动更新,pc('plan') 会把对应工具标成"待跑";跑一次 pc('all') 即自愈。

机型化机制(当前只注册 1 个机型)

一台飞机 = core/model/aircraft_registry.m 里的一行注册项(现在只有 '' = 默认机型, 三个壳共用同一个对象与同一份整定)。机型 ID 只决定「生成什么」, 其余命名一律由 core/model/aircraft_names.m 派生(禁止散落的字符串拼接)。

core/model/aircraft_registry.m        ← 加机型只改这里(id / display / 参数真源 / 结构 XML / bus_new)
        │  aircraft_names(id) 统一派生产物名
        ├── 结构 XML   models/<机型>.xml   ──build_model(id)──▶ models/<机型>.slx
        ├── 参数真源   core/model/<机型参数>.m
        │        update_model(id) ─▶ data/bus_define/pc_model_busdef[_<机型>].xlsx
        │        autoGenFilesInit ─▶ data/autoGenFiles/pc_model_busdef[_<机型>].sldd
        │                                     (对象参数总线 pc_model_params[_<机型>]_s)
        └── 装配       build_sil(id)/build_hil(id) ─▶ mainModels/sil[_<机型>].slx / hil[_<机型>].slx
                 SIL/HIL 参数:update_sim(id) ─▶ data/bus_define/sil[_·hil]_busdef[_<机型>].xlsx
                 ── autoGenFilesInit ─▶ 各自的 .sldd,且**各自引用本机型的对象参数字典**

跨机型共用 vs 按机型派生

跨机型共用(一份) 按机型派生(各一份)
autopilot.slx(含 NAV / CTL / 指令 / 参数 / 地面站通讯) models/<机型>.slx(对象模型;质量/惯量在生成时烘进 6DoF 掩码)
DEV 设备模型 / 硬件帧边界(pc_sim.c / pc_hal.c 与 add_dev_*) 对象参数表/字典、SIL·HIL 参数表/字典
边界帧定义 pc_io_busdef(pc_act_s / pc_sns_s)、航线 pc_routes.xlsx 装配 sil<机型>.slx / hil<机型>.slx
控制参数总线 pc_params_s(全机型仍共用一份;整定真源已按机型分派) 控制律整定真源 ctl_params_quad_x.m(见下)

现役机型('' = 默认机型;这也是唯一注册的机型):

id 说明 产物
'' 默认机型(450mm 级四旋翼,1.0 kg) model.slx / pc_model_params_s / sil.slx / hil.slx

运行:build_all(建 4 个模型);sim('sil')。注册表里只有一台飞机 ⇒ 下面所有 [_<机型>] 后缀都退化为无后缀;新增机型时机制不变,产物名由 aircraft_names 自动派生。

新增一个机型的步骤

% 1) 写参数真源        core/model/model_params_<id>.m(字段集必须与 model_params.m 完全一致)
% 2) 写结构真源        models/model_<id>.xml(可拷现成 XML 改名;换机架才改图)
% 3) 注册              core/model/aircraft_registry.m 的 defs() 追加一行(bus_new = true 才会派生独立总线)
% 4) 出数据 + 建模型
update_model('<id>'); update_sim('<id>');   % 本机型的参数表(Excel)
autoGenFilesInit;                            % Excel → .sldd(按机型建字典引用图)
build_all;                                   % 按注册表建:plant / sil / hil(autopilot 共用,只建一次)
run_tests;                                   % t_aircraft_registry 会核对命名/字段集红线

控制参数:一份总线类型 + 按机型取值(P1-1 已落地,见 doc/architecture.md §1.1 / §11 P1-1): 整定真源每机型一份(默认机型 core/control_law/ctl_params_quad_x.m;新增机型时另备同名真源), 入口 ctl_params(Ts, id) 按注册表 ctl_m 分派;取值只有一个转换入口 core/control_law/ctl_params_bus.m,三处消费:① 模型侧 —— 装配按机型用 pc_params[_<机型>]_s_init_val 驱动 autopilot 的 ctl_params 根入端口(与对象参数从 MODEL 入端口进来同构);② 内核侧 —— 框架(gcs-ng SIL 运行器 / auxpilot 固件)用 tasks/gen/gencode_params_c 生成的 X-macro 片段 pc_params_s.inc 填 pc_autopilot_step 的 u.ctl_params;③ Excel 台账 pc_params_busdef.xlsx(默认机型那一份,autoGenFilesInit 会与真源逐字段核对)。内核不认机型,故模型与内核同一口径、不会分叉;新增机型与默认机型 同机架(b0 与质量无关),两份取值当前逐位相同,换机架时只改该机型真源即可。

参数与数据字典(真源 → .sldd)

控制参数、航线管理参数、航线数据、飞机对象参数、边界总线 IO 以及 SIL/HIL 专属参数 都通过生成的数据字典(.sldd)取用,避免"参数散落在脚本与模型里各写一份"。各域各自 一个 Excel / 一个 .sldd,并按"域"建立显式字典引用图(见下):

core/control_law/ctl_params_quad_x.m                          ← 手改这里(★ 默认机型整定真源;
        │                                                        新增机型用 ctl_params_<id>.m,
        │                                                        由 ctl_params(Ts,id) 分派)
        │  tasks/data/update_pc_params.m             (深度展开为 139 个扁平 double 标量)
        ▼
data/bus_define/pc_params_busdef.xlsx    (工作表 pc_params_s,勿手改)
        │  tasks/data/autoGenFilesInit.m
        ▼
data/autoGenFiles/pc_params_busdef.sldd  ← 自动生成,随工程入库

core/nav/nav_params.m                                ← 手改这里(★ 航线管理参数真源)
        │  tasks/data/update_nav.m                   (展开为扁平 double 标量)
        ▼
data/bus_define/pc_nav_busdef.xlsx       (工作表 pc_nav_params_s,勿手改)
data/bus_define/pc_routes.xlsx           ← 手改这里(★ 航线数据真源:航点表)
        │  tasks/data/update_nav.m                   (打包成并列定长数组,工作表 pc_route_s)
        ▼
data/autoGenFiles/pc_nav_busdef.sldd     ← 自动生成,随工程入库

core/model/<机型参数真源>.m                           ← 手改这里(★ 飞机对象参数真源;换飞机改这里)
        │  tasks/data/update_model.m                 (展开为 26 个元素:标量 + 机体轴 3 元向量)
        ▼
data/bus_define/pc_model_busdef[_<机型>].xlsx (工作表 pc_model_params[_<机型>]_s,勿手改)
        │  tasks/data/autoGenFilesInit.m
        ▼
data/autoGenFiles/pc_model_busdef[_<机型>].sldd ← 自动生成,随工程入库

data/bus_define/pc_io_busdef.xlsx        ← 手改这里(★ 边界总线真源:pc_act_s / pc_sns_s)
        │  tasks/data/autoGenFilesInit.m
        ▼
data/autoGenFiles/pc_io_busdef.sldd      ← 自动生成

core/sim/sim_params.m 的 S.sil 表                     ← 手改这里(★ SIL 专属参数真源)
        ▼  tasks/data/update_sim.m
data/bus_define/pc_sil_busdef[_<机型>].xlsx (工作表 sil_params[_<机型>]_s)
        │  tasks/data/autoGenFilesInit.m
        ▼
data/autoGenFiles/pc_sil_busdef[_<机型>].sldd ← 自动生成

core/sim/sim_params.m 的 S.hil 表                     ← 手改这里(★ HIL 专属参数真源)
        ▼  tasks/data/update_sim.m
data/bus_define/pc_hil_busdef[_<机型>].xlsx (工作表 hil_params[_<机型>]_s)
        │  tasks/data/autoGenFilesInit.m
        ▼
data/autoGenFiles/pc_hil_busdef[_<机型>].sldd ← 自动生成

显式字典引用图(tasks/data/autoGenFilesInit.m 文末声明;dd.addDataSource):

pc_io_busdef.sldd  ──引用──▶  pc_params_busdef.sldd, pc_nav_busdef.sldd
pc_sil_busdef.sldd ──引用──▶  pc_io_busdef.sldd, pc_model_busdef.sldd
pc_hil_busdef.sldd ──引用──▶  pc_io_busdef.sldd, pc_model_busdef.sldd
pc_sil_busdef_<机型>.sldd ──引用──▶  pc_io_busdef.sldd, pc_model_busdef_<机型>.sldd
pc_hil_busdef_<机型>.sldd ──引用──▶  pc_io_busdef.sldd, pc_model_busdef_<机型>.sldd

即"SIL/HIL 有自己的参数、飞机有自己的参数,而 SIL/HIL 又用到飞机参数":装配模型 (sil[_<机型>] / hil[_<机型>])绑自己的字典,经引用即可解析边界帧(pc_sns_s / pc_act_s,来自 pc_io_busdef)、航线(pc_route_s,经 pc_io_busdef 转引 pc_nav_busdef)与本机型的对象参数总线(pc_model_params[_<机型>]_s)。对象参数只在 SIL/HIL 处被引用,pc_io_busdef 不再需要它。引用关系写在 .sldd 里,所以按机型各一份 (见上节「机型化机制」)。

  • 总线类 Excel(*_busdef.xlsx):工作表名 = 总线名,第 1 行表头、数据从 A2 起, 列 A..K = Name | Dimensions | DimensionsMode | DataType | SampleTime | Complexity | Min | Max | DocUnits | Description | IntVal。每行一个总线元素,整表合成一个 Simulink.Bus;IntVal 非空的行会另外累积出 <工作表名>_init_val 结构体(模型里 可直接用作该总线的常值/初值)。嵌套总线时叶子总线的工作表要排在父总线之前。
  • 参数类 Excel:列 A..H = Name | Value | StorageClass | Description | DataType | Min | Max | DocUnits。getParamsfromExcel 生成 .sldd;getParamsfromExcel2WS 只灌 base 工作区、不建 .sldd(出码前临时装载用)。
  • pc_params_busdef.xlsx(工作表 pc_params_s)把全套控制参数定义成一条扁平参数 总线:139 个 double 标量元素(Ts / pwm_* / rc_* / att_<轴>_* / rate_<轴>_* / mix_*),元素名 = 参数结构体字段路径用下划线连接(如 att_roll_b0), 值写在 IntVal 列,生成 pc_params_s_init_val。该 Excel 由 tasks/data/update_pc_params.m 从默认机型的整定真源 core/control_law/ctl_params_quad_x.m 自动导出,不要手改;与真源 逐项一致(往返校验 139/139)。※ 总线是全机型共用的一份,故各机型的整定取值必须一致 (见「机型化机制」的分派与限制)。
  • 控制律模块 pc_ctl 的最后一个根入端口就是这条参数总线 pc_params_s(装配侧以 pc_params_s_init_val 常值驱动),块内经 core/control_law/ctl_params_unpack.m 还原成嵌套参数 结构体 P 供算法使用;这样参数在模型里可在线整定,而 core/ 仍是唯一消费口径。
  • pc_nav_busdef.xlsx 有两张工作表:pc_nav_params_s(航线管理参数,扁平 double 标量,值取自 core/nav/nav_params.m,生成 pc_nav_params_s_init_val)与 pc_route_s(当前航线,用并列定长数组表示:n 航点数 + wp_lat_deg / wp_lon_deg / wp_alt_m / wp_speed_mps / wp_radius_m / wp_type,各长 max_wp=32,生成 pc_route_s_init_val)。它由 tasks/data/update_nav.m 从 core/nav/nav_params.m 与人工编辑的 data/bus_define/pc_routes.xlsx(航点表)自动导出,不要手改。航线管理模块 pc_nav 的 末两位入端口就是这两条总线(装配/仿真侧以 pc_nav_params_s_init_val / pc_route_s_init_val 常值驱动),块内经 core/nav/nav_params_unpack.m 还原参数。改航点:编辑 pc_routes.xlsx → update_nav → autoGenFilesInit → build_all。
  • pc_model_busdef[_<机型>].xlsx(工作表 pc_model_params[_<机型>]_s)把飞机对象参数 定义成一条扁平参数总线:26 个元素(19 个基础 + 7 个飞行动力学保真度系数),全部真实物理单位——KV/V_batt/k_load(电机与电池)、 D_prop/Ct/Cq/rho(螺旋桨与空气)、L_arm(力臂)、tau_m(电机时间常数)、 Jx/Jy/Jz(惯量)、Dw(角速率阻尼)、mass/g(质量与重力)、 Kd_lin/Kd_quad(机体轴阻力系数,各 3 元)、Ts/Nsub(积分设置)、 rcp_cm(压心偏移 3 元)、atm_isa/rot_inflow/rot_ge/gnd_k/gnd_c/gnd_mu(保真度系数,默认 0 = 中性), 生成 pc_model_params[_<机型>]_s_init_val。它由 tasks/data/update_model.m 从本机型的参数真源 (core/model/model_params.m 或 model_params_<机型>.m)自动导出,不要手改。飞机模型模块 <机型> 的最后一个根入端口就是这条总线(装配侧以它对应的 …_init_val 常值驱动), 块内经 core/model/model_params_unpack.m 还原成结构体供算法使用;派生量 k_T = Ct·ρ·D⁴/(4π²)、k_Q = Cq·ρ·D⁵/(4π²)、ω_max = KV·V_batt·(2π/60)·k_load 不进总线,运行时由原生块算出。 换飞机 = 改参数真源 + 重建模型(update_model('<机型>') → autoGenFilesInit → build_model('<机型>') → build_all({'', '<机型>'})),因为 mass/Jx/Jy/Jz 要在生成时烘进 6DoF 掩码(见下一条);其余参数(桨/电机/阻力…)也确实只经这条总线影响模型。SIL 侧同步 gcs-ng/sil/pc/main_headless.c 里的 g_plant_params 默认值即可(无需改飞控、无需重编飞控)。 注意:改转动惯量 Jx/Jy/Jz、螺旋桨/电机(Ct/Cq/D_prop/KV/…)、L_arm 或 tau_m 后, 需同步该机型整定真源(core/control_law/ctl_params_quad_x.m)的 角速率环 b0(b0_rate = 4·k_T·ω_max²·L_arm·mix / (J·tau_m));t_axis_margin 逐机型 断言这条一致性(容差 1%)。
  • 飞机模型模块的「结构」真源是 models/<机型>.xml(v2 方言,权威规格见 libraries/mbd-tools/README.md)。tasks/build/build_model.m 是薄驱动:读该 XML → xml2mdl_v2 生成 models/<机型>.slx(绑本机型的 pc_model_busdef[_<机型>].sldd、定步 ode4、生成内编译自检,并断言根端口名/顺序/维度与总线类型对齐 utilities/spec_model.m 契约)。改模型结构 = 改 XML(不再手写 add_block);6DoF (Quaternion) 的 Mass/Inertia 在生成时由机型参数真源解析成数值(该块无可变质量/惯量输入),故 换飞机必须重建模型 —— 每机型一份 models/<机型>.xml + 一份参数真源,注册在 core/model/aircraft_registry.m。 生成后跑 tasks/verify/compare_model.m 做新旧模型 12 路输出等价性回归(XML 化前的旧模型已作为 回归资产入库 test/assets/model_ref.slx,故清空 work/ 后仍可复现;work/_cmp/ 下的同名文件只作临时覆盖用)。
  • pc_io_busdef.xlsx(工作表 pc_act_s / pc_sns_s)定义 SIL/HIL 装配的边界帧: pc_act_s = 执行机构帧 pwm[8](归一化 [0,1],控制律 → 设备/硬件);pc_sns_s = 传感器/外设帧 29 元素(设备/硬件 → 控制律)。SIL 与 HIL 共用同一份边界帧定义。装配模型以文件名 绑定字典(DataDictionary = pc_sil_busdef[_<机型>].sldd / pc_hil_busdef[_<机型>].sldd),解析依赖 MATLAB 路径,所以 data/autoGenFiles/ 必须常驻路径(startup.m 已加入)。该字典通过 dd.addDataSource 引用 pc_params_busdef.sldd / pc_nav_busdef.sldd(供 autopilot 解析 pc_params_s / pc_nav_params_s / pc_route_s)。
  • pc_sil_busdef[_<机型>].xlsx(工作表 sil_params[_<机型>]_s)定义 SIL 专属参数(10 个元素): 起降点 home_lat_deg / home_lon_deg / home_alt_m(设备模型由 NED 位置递推经纬/海拔; 即"初始位置 x0"的地理基准——对象模型在 NED 原点起步,home 就是该原点对应的经纬高。 当前值:广西南宁东站附近 22.842 / 108.4135,海拔 80 m)、 ins_valid(惯导有效占位)、常值风 wind_n/wind_e/wind_d、机体扰动力矩 dist_r/dist_p/dist_y。它由 core/sim/sim_params.m 的 S.sil 表经 tasks/data/update_sim.m 生成,改 core/sim/sim_params.m。 sil 装配以 pc_sil_params_s_init_val 常值驱动,经 Bus Selector 分发:风/扰动 → model, home / ins_valid → 设备模型 DEV(pc_dev_step)。该字典引用 pc_io_busdef.sldd 与 pc_model_busdef.sldd——即"SIL 有自己的参数,飞机有自己的参数,而 SIL 又用到飞机参数"。
  • pc_hil_busdef[_<机型>].xlsx(工作表 hil_params[_<机型>]_s)定义 HIL 专属参数(11 个元素): 起降点 home_lat_deg / home_lon_deg / home_alt_m(与 SIL 同值,作飞机模型 NED 原点的 地理基准)、常值风 wind_n/wind_e/wind_d、扰动力矩 dist_r/dist_p/dist_y 与链路占位 link_rx_byte / link_rx_valid(真实 HIL 由硬件帧提供 —— 属 HIL 真实 I/O 替换点清单的 ASM-LINK-RX,见 tasks/build/+mbd/hil_io_points.m)。同样由 core/sim/sim_params.m 的 S.hil 表经 tasks/data/update_sim.m 生成, 并引用 pc_io_busdef.sldd 与 pc_model_busdef.sldd。HIL 的位姿来自硬件帧,故无 ins_valid。

改了某机型的整定真源(core/control_law/ctl_params_quad_x.m)后重跑 update_pc_params → autoGenFilesInit(写该机型取值变量、并与真源逐字段核对)→ build_all; C 侧还要跑 gencode_params_c 把 .inc 复制到 auxpilot/middleware/model/autopilot/ 与 gcs-ng/sil/pc/,再重出码内核(gencode_autopilot_c)并重编固件 / SIL 运行器; 改了 core/nav/nav_params.m 或 data/bus_define/pc_routes.xlsx(航点表)后重跑 update_nav → autoGenFilesInit → build_all;改了 core/model/model_params.m(飞机对象参数)后重跑 update_model → autoGenFilesInit → build_all(SIL 再跑 gencode_sim_c 并重编);改了 SIL/HIL 专属参数后重跑 update_sim → autoGenFilesInit → build_all;改了 data/bus_define/ 下的其它 Excel 后重跑 autoGenFilesInit(会清空并重建 data/autoGenFiles/,并按引用图重建字典引用关系)。 以上产物(*.xlsx 与 *.sldd)都要一并提交。

% 0) 打开工程(推荐)——工程路径与四个快捷方式自动就绪(startup.m 自动执行)
openProject('<repo>\planecontrol\planecontrol.prj');
%    在 MATLAB 的 "Project" 面板可直接点:BuildAll / GenCode / RunTests / SimCloseLoop
%    不用工程时,改为自举环境(一条命令顶掉全部 addpath;并把构建产物指到 work/):
%    addpath('utilities'); path_bootstrap;
%    命令行走法:matlab -batch "addpath('utilities'); path_bootstrap; run_tests"

% 1) 单元测试 + 闭环仿真(不需要 Simulink,先确认算法对)
run_tests;
sim_adrc_axis;
sim_closedloop;
sim_nav;                 % 航线管理闭环:起飞→巡航→盘旋→返航→降落

% 2) 一键生成全部 Simulink 模型(数据链 → 模型链;产物不入库)
%    ★ gen_models = 真源 → .xlsx/.sldd/生成头 → 全部 .slx(10 个),约 2~3 分钟
gen_models;                % 一键:数据链 + 模型链 + 汇总(推荐,任何状态都能跑)
%    只建模型链(数据字典已就绪时):build_all;
%    只增量重建过期的模型链:pc('all','kind','build')
%    单独一个模型:build_model; build_autopilot; build_ap; build_sil; build_hil;
%    强制全部重建:gen_models('force', true)
%    产物:models/model.slx;controllers/autopilot/{autopilot,ctl,nav,ap_comm,ap_cmd,ap_param}.slx;
%          mainModels/{ap,sil,hil}.slx(Model Reference 引用前两者)

% 3) (可选)改了 core/*_params.m、core/sim/sim_params.m 或 data/bus_define 下的 Excel
%    后,重建数据字典(按域:控制律 / 导航 / 飞机 / 边界 / SIL / HIL;机型各自一份)
update_pc_params;        % 默认机型整定真源 ctl_params_quad_x.m -> data/bus_define/pc_params_busdef.xlsx
update_nav;              % core/nav/nav_params.m + pc_routes.xlsx -> data/bus_define/pc_nav_busdef.xlsx
update_model;            % 默认机型的参数真源 -> data/bus_define/pc_model_busdef.xlsx
update_model('<机型id>');  % 指定机型:参数真源 -> data/bus_define/pc_model_busdef_<机型id>.xlsx
update_sim;              % SIL/HIL 专属参数 -> data/bus_define/pc_sil_busdef.xlsx / pc_hil_busdef.xlsx
update_sim('<机型id>');    % 该机型 SIL/HIL 参数 -> pc_sil_busdef_<机型id>.xlsx / pc_hil_busdef_<机型id>.xlsx
autoGenFilesInit;        % Excel -> data/autoGenFiles/*.sldd(并按机型建字典引用图)

% 4) 生成 C 代码(输出到 work/codegen*/)
gencode_ctl;             % 控制律(含接口契约自检)
gencode_nav;             % 航线管理模块
gencode_model;           % 飞机模型模块
gencode_autopilot_c;     % ★ SIL/HIL 共用内核:autopilot → work/codegen_autopilot/
gencode_sim_c;           % ★ SIL/HIL 共用:设备模型 + 飞机模型 → work/codegen_sim/

% 5) 生成控制律并把代码同步到 auxpilot/middleware/model/
gencode_ctl(true);

第 5 步之后,只需在 auxpilot/middleware/model/ctl_model_mbd.h 里把 CTL_MODEL_USE_MBD 与 CTL_MBD_MAPPING_DONE 置 1,重新编译固件即可。 ctl_model_impl.c 的字段映射就是按本模型接口写的,不需要改动。

SIL / HIL 出码(σ 同源):gencode_autopilot_c + gencode_sim_c 是 SIL 与 HIL 唯一的内核出码路径——两侧都编译这同一份 work/codegen_autopilot/ + work/codegen_sim/。SIL / HIL 只是 gcs-ng 里的两个"瘦框架"(sil/pc、hil/pc), 共用同一份运行器 main_headless.c 与同一份内核,仅以 -DPC_IFACE_HIL 切换对外接口: SIL 接口由对象真值合成惯导、遥控/电池来自框架;HIL 接口经 HAL 硬件边界 (pc_hal.c,与固件 fc_task.c 同源)。不再有 gencode_sil / gencode_hil 的 Simulink 装配出码路径(那是每种仿真方式各出一份源的旧做法)。

rem 编译 SIL(接口 = SIL)→ gcs-ng\bin\sil\pc\SIL_PC.exe
gcs-ng\sil\pc\build.bat
rem 编译 HIL(接口 = HIL)→ gcs-ng\bin\hil\pc\HIL_PC.exe
gcs-ng\hil\pc\build.bat

代码生成脚本(一目标一脚本)

脚本 生成的代码 用途
gencode_ctl 控制律模块 pc_ctl(临时模型 ← build_ctl) 烧飞控(gencode_ctl(true) 同步到固件)
gencode_nav 导航模块 pc_nav(临时模型 ← build_nav) 单独作为制导/管理层使用
gencode_model 飞机模型模块 model 单独作为被控对象使用
gencode_autopilot_c ★ SIL/HIL 共用内核 pc_autopilot_step(MATLAB Coder ← core/autopilot/pc_autopilot_step.m) SIL / HIL 两侧唯一的飞控内核源
gencode_sim_c ★ SIL/HIL 共用 pc_dev_step / pc_model_step(MATLAB Coder) SIL / HIL 两侧共用的设备/对象模型

gencode_ctl/nav/plant 共用 tasks/gen/gen_ert.m 内核(配置 ert.tlc、设置输出目录、 slbuild、定位生成目录、还原设置);gencode_autopilot_c / gencode_sim_c 走 MATLAB Coder(core/ 纯算法),产物供 gcs-ng 的 SIL / HIL 框架编译。

出码环境(R2024a):需要 Embedded Coder(ert.tlc)+ 一个 MATLAB 认识的 C 编译器。

  • gencode_ctl / gencode_nav 已随 autopilot 内联化改为临时模型出码: 用同一份内容构建器(build_ctl('', tmpdir) / build_nav('', tmpdir))在临时目录 生成 pc_ctl.slx / pc_nav.slx 出码,出码后清理——内容与 autopilot 内的 CTL / NAV 子系统同源,固件侧 pc_ctl_* / pc_nav_* 接口契约不变。
  • pc_ctl / pc_nav / model 都是纯 Simulink 模型,gencode_ctl/nav/plant 在 R2024a 下可直接出码。
  • 顶层 gencode_autopilot 含 C Caller 自定义代码 (pc_ap_comm.c / pc_hal.c),构建时要真正调用 C 编译器;R2024a 需先装 「MATLAB Support for MinGW-w64 C/C++ Compiler」附加功能(或 VS2022)并 mex -setup, 否则报 No supported compiler detected。
  • GCC 16 及以上需在 mex 配置里显式指定 C 语言标准:Simulink 的「自定义代码解析 (SLCC)」用内部 clang 前端按 mex 配置里的语言标准解析 pc_ap_comm.c。GCC 16 默认 C23(__STDC_VERSION__=202311L),内部前端不识别,C Caller 端口解析失败 (报 Command-line error: language modes specified are incompatible,随后表现为 Simulink 对象名称无效: 'COMM_RX/1')。修法:在 %APPDATA%\MathWorks\MATLAB\<ver>\mex_C_win64.xml 的 CFLAGS 前加 -std=gnu11, 即 CFLAGS="-std=gnu11 -fexceptions -fno-omit-frame-pointer"(改前备份原件)。 注意 SimCustomCompilerFlags 无效——解析标准取自 mex 配置,不是模型参数。
  • 无 Embedded Coder 授权时(如 R2026a)build_all 仍能完成「模型构建」,只有 gencode_* 会报错;此时走 MATLAB Coder 兜底路径 tasks/gen/gencode_autopilot_c.m (← core/autopilot/pc_autopilot_step.m)与 tasks/gen/gencode_sim_c.m——这条路径 正是 SIL / HIL 实际使用的唯一内核源。
  • 模型引用要求父/引用模型的代码生成配置一致,故 ERT 配置统一放在 tasks/build/+mbd/ert_config.m,由 mbd.new_model(建模型时)与 gen_ert (出码时)共用,避免只设顶层、引用模型仍为默认 grt 而导致的配置不匹配。

4. 控制结构

        ┌──────────────┐   ┌────────────────┐   ┌──────────────┐   ┌───────┐
 rc/指令 →│ Cmd_Process  │→ │ Attitude_ADRC  │→ │  Rate_ADRC   │→ │ Mixer │→ 4×PWM
        └──────────────┘   └────────────────┘   └──────────────┘   └───────┘
          油门 + 期望姿态       姿态角 ADRC×3        角速率 ADRC×3       X 型混控
          运行许可(安全门)     (roll/pitch/yaw)    (p/q/r)
  • 外环被控量是姿态角,输出是角速率指令;内环被控量是机体角速率,输出是归一化 力矩指令;混控把油门与三轴力矩合成 4 路归一化电机指令 [0,1](0 = 怠速, 1 = 满油门);µs 换算只在固件/HIL 硬件边界做(见第 7 节量纲约定)。
  • 每一轴 ADRC = TD(设定值过渡)+ ESO(状态与总扰动观测)+ NLSEF(误差反馈)

导航 / 制导(NAV 子系统,内置于 autopilot)

NAV 是控制律上游的飞行管理层,是 autopilot.slx 内部的子系统(不再是独立模型): 读取航线(航点序列)+ 惯导估计,按航线类型跑飞行阶段状态机,解算成期望姿态/油门 setpoint,交给同在 autopilot 内的 CTL 自动分支(mode 为自动类时 CTL/Cmd 直接吃 roll_sp/pitch_sp/yaw_sp + throttle)。需要单独出码时由 gencode_nav 用同一份内容 构建器(build_nav)在临时目录生成 pc_nav.slx:

 航线(pc_route_s) ┐
 参数(pc_nav_params_s) ┤
 惯导估计 ───────┴→ NAV(阶段状态机 → 横向/速度制导 → 高度保持)
                        └→ roll_sp / pitch_sp / yaw_sp / throttle ─→ CTL(自动分支)
  • 航线类型 / 航点类型 / 飞行阶段枚举(core/shared/nav_types.m)数值刻意对齐参考工程 t2000_proj,便于航线数据互换与遥测对照;航线数据经 Excel→.sldd 流水线管理(见第 2 节)。
  • 阶段状态机:航线类型决定初始阶段(TAKEOFF→起飞、MISSION→巡航、RETURN→返航、 LANDING→降落 …),到点 / 盘旋 / 返航 / 降落切换都在 core/flight_mgmt/nav_stage_step.m;横向用 L1 制导(nav_lat_guidance)、高度用归一化油门控制(nav_alt_hold)、航段几何在 nav_leg_geom。
  • 姿态 / 速率环对航线不可见,因此 NAV 不修改 CTL 的端口契约(自动分支早已就位); 纯 MATLAB 闭环验证见 sim/sim_nav.m(起飞→巡航→盘旋→返航→降落)。

5. SIL / HIL 装配

两种形态,一份内核:本节描述的是 sil.slx / hil.slx 两个 Simulink 装配 (用于在 Simulink 里直接跑/验证)。而 gcs-ng 下交付运行的 SIL / HIL 是与之同构的 C 瘦框架(gcs-ng/sil/pc、gcs-ng/hil/pc):两者都编译同一份 MATLAB Coder 内核 (work/codegen_autopilot + work/codegen_sim),只以 -DPC_IFACE_HIL 切换对外接口。 内核(autopilot + plant)只有一份——SIL 接口由对象真值合成惯导、HIL 接口经 HAL 硬件边界;不再有"每种仿真方式各出一份源"。

build_sil.m 与 build_hil.m 用 Model Reference 把 autopilot(内含 NAV / CTL) 与 model 「包在里面」,装配本身不复制任何算法。SIL 与 HIL 共用同一 AUTOPILOT / MODEL,唯一差异是中间那个 DEV 子系统:

        ┌──────────────────────── sil / hil ─────────────────────┐
        │                                                              │
        │  激励源 ──▶ ┌──────────────┐ pc_sns_s ┌───────┐ pwm ┌───────┐ │
        │             │ autopilot │ ◀────────│  DEV  │────▶│ MODEL │ │
        │             │  (NAV → CTL) │          └───────┘     └───────┘ │
        │             └──────────────┘   pc_act_s ──┘ 真值[12] ──┘ (SIL) │
        └──────────────────────────────────────────────────────────────┘

中间一帧一拍:CTL → pc_act_s(pwm[8], 归一化 [0,1]) → DEV → MODEL,MODEL → 真值[12] → DEV → pc_sns_s(29) → CTL。pc_act_s / pc_sns_s 的类型真源是数据字典 data/autoGenFiles/pc_io_busdef.sldd;装配模型以文件名绑定自己域的字典 (pc_sil_busdef.sldd / pc_hil_busdef.sldd),经字典引用解析边界帧与飞机对象参数。

  • SIL(sil):DEV = 设备模型(mbd.add_dev_sim)。它把飞机真值 truth[12] 与装配级指令源(遥控 / 电池 / 期望姿态 / 模式)合成为传感器/外设帧 pc_sns_s,并把执行机构帧透传给飞机模型。其中惯导估计(姿态 / 速率 / 速度 / 经纬高)由 C Caller 块 SIM_SNS(C 真源 controllers/autopilot/pc_sim.c,数学 同 core/device/pc_dev_step.m)从真值合成——与 HIL 的 pc_hal(HAL 边界)对称: 两侧都只换 DEV 那一层,AUTOPILOT / MODEL 完全一致。lat/lon 由真值 NED 位置 (pn/pe)从 home 换算、alt_msl_m = alt_home + (-pd)(与 sim_nav 同口径), 使位置回路在 SIL 下真正闭环;home / ins_valid 不再硬编码,改由 pc_sil_params_s 参数总线供(入端口 16)。常值风与扰动力矩同样来自 pc_sil_params_s,在装配顶层 取用后送 model。导航 setpoint 由 autopilot 内部的 NAV 子系统(块路径 autopilot/NAV)以航线(pc_route_s 常值,来自 pc_routes.xlsx)+ 估计量解算后 在 autopilot 内部接到 CTL 自动分支,装配侧不再单独接 NAV。纯桌面仿真。
  • HIL(hil):DEV = 硬件帧边界(mbd.add_dev_hw),端口与 SIL 的 DEV 一一对应,内部把收发做成占位块(接收帧常值 / 发送帧透传),已用「★ 替换点」 标注。做真实 HIL 时把占位块换成你的真实 I/O(串口 / CAN / UDP / 接收机 / 电压采集的收发 S-Function)即可。风/扰动/链路占位取自 pc_hil_params_s。模型已按 200 Hz 开启实时配速。
  • pwm 链上有 Unit Delay,代表数字控制回路固有的一拍执行延迟,同时断开 CTL↔MODEL 间的代数环。
  • 若采用「真实飞控跑控制律 + 本模型只跑飞机模型」的拓扑,删除 hil 里的 autopilot 引用块,让 DEV 的硬件帧直接对接串口对象。

6. 整定入口

只改两处:

  1. core/control_law/ctl_params_quad_x.m(每机型一份真源)里各轴的 wc(控制器带宽)、w0(观测器带宽)与 b0; ESO / NLSEF 增益由 adrc_axis_params.m 按带宽自动生成,不需要逐个试凑。 ※ b0 必须取二阶模型 y''=f+b0·u 的高频增益(速率环 = 4·k_T·ω_max²·L_arm·mix / (J·tau_m),角环 ≈ 速率环闭环带宽),不是直流增益; 取错量纲会导致力矩指令长期饱和、阶跃大幅超调。详见 doc/architecture.md 第 7 节。
  2. 同上文件里 p.mix.* 的力矩→电机差动比例(按机型力矩系数调)。

本工程采用线性 ADRC(ESO 的 fal 幂次 alpha1=alpha2=1,NLSEF 用线性反馈)。 原因见 doc/architecture.md 第 2 节:带宽参数化的 beta=3w0,3w0²,w0³ 只对线性 ESO 成立,改用 alpha<1 的非线性 fal 会在 Ts=1/200 下激发极限环。

改完先跑 run_tests 与 sim_closedloop,再 update_pc_params + autoGenFilesInit + build_all + 对应的 gencode_*(参数经参数总线 pc_params_s 进模型)。

7. 接口契约(摘要)

NAV / CTL 现为 autopilot.slx 内部子系统;下表描述其出码契约——由 gencode_ctl / gencode_nav 用同一份内容构建器在临时模型上出码,接口与下文完全一致。

项目 值
模块 pc_ctl(autopilot/CTL 子系统)
根输入 31 个 Inport(前 30 个标量 + 末位参数总线 pc_params_s),名字即 pc_ctl_U 字段名
根输出 pwm,宽 8(= FC_PWM_N),归一化电机指令 [0,1](0 = 1000 µs 怠速,1 = 2000 µs 满油门)
步长 1/200 s(定步长离散,非可重入)
入口函数 pc_ctl_initialize() / pc_ctl_step() / pc_ctl_terminate()
固件开关 CTL_MODEL_USE_MBD / CTL_MBD_MAPPING_DONE

导航模块 pc_nav(autopilot/NAV 子系统,不上飞控):

项目 值
模块 pc_nav(autopilot/NAV 子系统)
根输入 19 个 Inport:dt + 16 路估计/指令(ins_valid / 经纬高 / gs/hdg / vn/ve/vd / 姿态 / armed/mode / route_type / nav_cmd)+ 末两位总线 pc_nav_params_s / pc_route_s
根输出 10 路:roll_sp/pitch_sp/yaw_sp [rad] + throttle [0,1] + 遥测 active/stage/wp_current/dist_wp/xtrack/bearing
步长 1/200 s(与 pc_ctl 同频)
入口函数 pc_nav_initialize() / pc_nav_step() / pc_nav_terminate()

量纲约定:模型根 IO 统一用工程量 / 归一化量,µs 只出现在与硬件打交道的边界 (对齐 t2000_proj)。遥控 4 通道不以 µs 进模型,而是在 ctl_model_impl.c 里按 参数总线的 rc_mid/rc_half/rc_min/rc_max 折算成归一化杆量 [-1,1] / 油门 [0,1]; 输出 pwm 由 ctl_model_impl.c 按 pwm_min/pwm_max 换算回 µs 送 hal_pwm_write。

字段清单、单位与生成配置见 doc/architecture.md。

8. 备注

  • 打开 planecontrol.prj 即可开工:工程里带有四个快捷方式(build_all / gencode_ctl / run_tests / sim_closedloop);搜索路径与缓存目录由 utilities/startup.m 在其内部 调用 utilities/path_bootstrap.m 一次配齐(<root>/work 作 Simulink 缓存与代码生成目录), 关闭时由 utilities/shutdown.m 还原。 ※ 重排把数据与任务脚本换了位置(data/、tasks/{data,build,gen,verify} 等),工程元数据 (resources/,MATLAB 维护)里指向旧位置的登记项会在 Project 面板显示为 Missing —— 在面板里右键 Remove from Project 清理一次即可;不影响构建(路径由 path_bootstrap 提供, 且面板里本来就已有若干历史失效项)。
  • *.slx 既可由 tasks/build/build_*.m 程序化重建,也已入库随工程分发; .gitattributes 已把 *.slx 声明为二进制 + mlAutoMerge。合并冲突时以脚本为准 ——重跑 build_all 覆盖即可。改了脚本(build_*.m / blk_*.m / core/*.m)请重跑 build_all 再提交。
  • work/ 已在 .gitignore 中忽略(Simulink 缓存与代码生成产物不入库)。
  • 本仓库与 auxpilot 的交叉校验:各 build_*.m 会读取 auxpilot/driver/board/fc_board.h 的 BOARD_CTL_HZ 和 auxpilot/middleware/state/fc_state.h 的 FC_PWM_N,不一致直接报错。
S
Description
No description provided
Readme
25 MiB
Languages
MATLAB 87.3%
C 7.2%
PowerShell 5.4%