QGroundControl 机架设置（ArduPilot）完全指南：ArduCopter 与 ArduSub 的 Frame 配置原理与实操

QGroundControl（QGC）的 Airframe Setup（机架设置）页面用于为 ArduPilot 飞控的飞行器选择与实体结构匹配的机架类别（Frame Class）与机架类型（Frame Type）。本指南以官方文档 docs/tr/qgc-user-guide/setup_view/airframe_ardupilot.md（及英文版 docs/en/qgc-user-guide/setup_view/airframe_ardupilot.md）为骨架，结合 QGC 源码深入讲解 ArduCopter 与 ArduSub 两类机架的完整配置流程、底层参数机制与界面交互原理。读完本文，你将能够独立完成 ArduPilot 机架选型、理解 FRAME_CLASS / FRAME_TYPE / FRAME_CONFIG 三个核心参数的作用，并掌握 Sub 推力器桨叶方向的检查要点。

适用范围与前置说明

机架设置页面仅对 ArduCopter 与 ArduSub 两类飞行器可用，对 ArduPilot 的 Rover（地面车）与 Plane（固定翼）机型不显示。这一点在文档中有明确说明，也与源码逻辑一致：

• 在 APMAirframeComponentController.cc 的 _fillFrameClasses() 中，控制器只对 ArduCopterFirmwarePlugin 与 ArduRoverFirmwarePlugin 两种固件插件填充 Frame Class 列表，而 Rover/Plane 机型不会呈现该设置页。
• 在 APMAutoPilotPlugin.cc 中，APMAirframeComponent 作为 Vehicle Component 被挂载到 ArduPilot 设置流程，是后续多项配置（飞行模式、无线电、电源、ESC 等）的前置条件。

从更宏观的配置页面体系看，机架设置入口属于 ArduPilot 专属页面之一，与 Failsafes、Flight Modes、Motors、Power、Radio、Sensors、Tuning 等页面并列，入口索引见 setup_view.md；而 PX4 固件则使用独立的 Airframe 页面（airframe_px4.md），两者流程不同。

ArduCopter 机架设置

ArduCopter 的机架配置遵循“先选大类、再选细型”的两级流程，官方文档给出的步骤如下：

1. 点击顶部工具栏的齿轮图标（Vehicle Setup，即飞行器设置），然后在左侧边栏选择 Airframe。
2. 为你的飞行器选择宽泛的 Frame Class（机架类别）。需要注意的是，类别（Class）的变更必须重启飞行器后才能生效。
3. 为你的飞行器选择具体的 Frame Type（机架类型）。

下面是 Frame Class 与 Frame Type 两级界面的实际形态截图（来源于本仓库 docs/assets/setup/airframe 目录，原文档所引用的界面配图）：

ArduCopter 机架设置：Frame Class 选择界面

ArduCopter 机架设置：Frame Type 选择界面

Frame Class（机架类别）可选项

从源码 APMAirframeComponentController.h 可以看出，类别枚举与 ArduCopter 固件的 FRAME_CLASS 参数元数据严格对应：

Frame Class 数值	类别名称	说明
0	Undefined	未定义（默认值，未完成设置状态）
1	Quad	四旋翼
2	Hex	六旋翼
3	Octa	八旋翼
4	OctaQuad	共轴八旋翼（X8 结构）
5	Y6	Y6 共轴六旋翼
6	Heli	传统直升机
7	Tri	三旋翼
8	SingleCopter	单旋翼
9	CoaxCopter	共轴双旋翼
10	BiCopter	双旋翼
11	Heli_Dual	双主旋翼直升机
12	DodecaHexa	十二旋翼
13	HeliQuad	四旋翼直升机

需要特别说明：FRAME_CLASS_HELI 等直升机类别在 ArduCopter 常规固件下会被过滤掉。源码 APMAirframeComponentController.cc 中，_fillFrameClasses() 显式排除了 HELI、SINGLECOPTER、COAXCOPTER、BICOPTER、HELI_DUAL、HELIQUAD 六类——因为直升机需要独立的固件变体，无法从普通 Copter 固件直接切换过去。

Frame Type（机架类型）可选项

Frame Type 与固件 FRAME_TYPE 参数对应（APMAirframeComponentController.h）：

Frame Type 数值	类型名称	典型结构
0	Plus	“+”字形
1	X	“X”字形
2	V	V 形（宽机架）
3	H	H 形
4	V-Tail	V 尾
5	A-Tail	A 尾
10	Y6B	Y6 尾部在前布局
11	Y6F	Y6 前部在前布局
12	BetaFlightX	BetaFlight 风格 X
13	DJIX	DJI 风格 X
14	ClockwiseX	顺时针 X

并非所有类别都支持全部类型。控制器内部维护了一张“类别—类型—配图”的映射表 _rgFrameToImageCopter（APMAirframeComponentController.h），例如：

• Quad 支持 X、Plus、V、H、V-Tail、A-Tail 六种类型；
• Hex 支持 X、Plus 两种；
• Octa / OctaQuad 支持 X、Plus（以及映射为未知图的 V、H）；
• Y6 支持 Y6B、Y6F，其中 Y6A 是该类别无具体类型值时的默认形态。

在 APMAirframeComponentController.cc 中，APMFrameClass 构造器会依据映射表过滤 FRAME_TYPE 的枚举项，只向界面暴露该类别实际支持的 Frame Type；若当前 FRAME_TYPE 与所选类别不匹配（非法组合），QML 界面会显示 “Invalid setting for FRAME_TYPE. Click to Reset.” 的提示并允许一键重置（见 APMAirframeComponent.qml）。

界面交互与参数写回原理

选中类别时，界面通过隐藏的复选框将 FRAME_CLASS 参数写入飞控；在类别卡片内选择 Frame Type 时，则将对应数值写入 FRAME_TYPE 参数（APMAirframeComponent.qml）。页面顶部的提示文本会实时显示当前已设置的 Frame Class / Frame Type，并明确提示“要更改此配置，请选择下方目标类别，然后重启飞行器”（APMAirframeComponent.qml）。这印证了文档中“类别的变更需重启后生效”的注意事项。

此外，机架设置是否完成直接由 FRAME_CLASS 参数决定。在 APMAirframeComponent.cc 中，setupComplete() 返回 _frameClassFact->rawValue().toInt() != 0，即 FRAME_CLASS 为 0（未定义）时，机架设置被判定为未完成，该组件会在设置侧边栏中显示红色图标；而飞行模式、无线电、电源、ESC 等组件的设置页会以机架设置为前置条件（见 APMAutoPilotPlugin.cc）。测试用例 APMFreshFlashParamsTest.cc 也验证了：全新刷写固件后 FRAME_CLASS 为 0（且保持 INT8 类型），此时机架组件 setupComplete() 返回 false，系统会提示需要先完成设置。

ArduSub 机架（Frame）设置

ArduSub（潜水器）的机架配置流程与 ArduCopter 不同，官方文档给出的步骤如下：

1. 点击顶部工具栏的齿轮图标（Vehicle Setup），然后在侧边栏选择 Frame。
2. 选择与你的潜水器匹配的机架类型（选择即应用，无需额外确认参数写入）。
3. 检查所有绿色推进器的桨叶必须为顺时针旋转，所有蓝色推进器的桨叶必须为逆时针旋转（反之亦可），确保动力布局方向正确。

此外，还可以点击 Load Vehicle Default Parameters（加载飞行器默认参数）来为 ArduSub 载入默认参数集。

界面支持的机架型号

从 APMSubFrameComponent.qml 的界面模型可以看到，Sub 机架选择页内置的型号与 FRAME_CONFIG 参数值一一对应：

型号名称	FRAME_CONFIG 参数值	默认参数文件
BlueROV1	0	无（仅设置框架）
BlueROV2 / Vectored	1	bluerov2
Vectored-6DOF	2	bluerov2-heavy
SimpleROV-3	4	无
SimpleROV-4	5	无
SimpleROV-5	6	无

点击某个机架卡片后，界面会先写入 FRAME_CONFIG 参数（setFrameConfig()，APMSubFrameComponent.qml）；对于带默认参数文件的型号（BlueROV2 系列），会弹出确认对话框询问是否“加载该机架的默认参数集”，确认后调用 loadFrameDefaultParameters() 从 ArduPilot 官方仓库拉取对应的 .params 文件（APMSubFrameComponent.qml）。固件版本较新（≥ 4.1.0）时，固件默认参数已足够合理，选择机架会直接应用而不再弹窗建议加载参数（APMSubFrameComponent.qml）。

参数文件下载的底层实现

“Load Vehicle Default Parameters”并非本地内置文件，而是通过控制器从 ArduPilot 仓库动态下载。在 APMAirframeComponentController.cc 中，loadParameters() 首先请求 GitHub API 获取 Tools/Frame_params/<型号>-<版本>.params 的 JSON 元信息，再下载实际参数文件；版本号按飞控固件版本选择（4.0.0+ → 4_0_0，3.5.4+ → 3_5_4，3.5.2+ → 3_5_2，否则为 3_5，见 APMSubFrameComponent.qml）。下载完成后，_loadParametersFromDownloadFile() 逐行解析参数文件，跳过空行与 # 注释，对已存在的参数执行 setRawValue() 写入，最后调用 refreshAllParameters() 刷新参数缓存（APMAirframeComponentController.cc）。这意味着该功能需要网络连接，且参数仅在飞行器上已存在的参数才会被更新。

桨叶方向检查的意义

步骤 3 强调的“绿色顺时针 / 蓝色逆时针”是潜水器动力安全的关键检查项。QGC 的机架示意图中，绿色代表需安装顺时针（CW）桨叶的推进器，蓝色代表需安装逆时针（CCW）桨叶的推进器。方向装反会导致电机转动方向与实际期望相反，直接影响潜水器的姿态控制与安全性；文档同时指出“反之亦可”，即只要同类颜色桨叶保持同向、绿蓝互为反向即可满足要求，实际方向取决于具体布局定义。

机架设置的验证与后续步骤

完成机架选择后，建议按以下路径验证与收尾：

1. 重启飞行器：让 ArduCopter 的 Frame Class 变更真正生效（文档明确要求）。
2. 检查 Summary 页面：机架组件在 APMAirframeComponentSummary.qml 中汇总显示 Frame Class、Frame Type 与固件版本，若机架未完成设置，Summary 块会显示红色指示；设置全部完成后红色指示消除。
3. 继续后续设置：机架设置是 ArduPilot 后续配置（飞行模式、无线电校准、电源、ESC、传感器等）的前置步骤，未完成机架设置时，这些页面会提示先完成机架配置（APMAutoPilotPlugin.cc）。
4. 结合参数页微调：如需查看或修改 FRAME_CLASS、FRAME_TYPE、FRAME_CONFIG 的原始值，可进入 Parameters 页面（parameters.md）直接编辑。

相关源码索引

• 控制器与参数逻辑：APMAirframeComponentController.cc、APMAirframeComponentController.h
• ArduCopter 设置界面：APMAirframeComponent.qml
• ArduSub 设置界面：APMSubFrameComponent.qml
• 组件注册与前置依赖：APMAutoPilotPlugin.cc
• 机架设置完成判定：APMAirframeComponent.cc
• 相关测试：APMFreshFlashParamsTest.cc、APMFreshFlashUITest.cc