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)都要一并提交。
3. 快速开始(需要 MATLAB + Simulink + Embedded Coder)
% 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(误差反馈)
- 扰动补偿
u = (u0 - z3)/b0,详见 doc/architecture.md。
- 扰动补偿
导航 / 制导(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. 整定入口
只改两处:
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 节。- 同上文件里
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,不一致直接报错。