QGroundControl 机架设置指南（ArduPilot）：ArduCopter 与 ArduSub 框架选择实战

本文面向使用 QGroundControl 连接 ArduPilot 系列飞控的用户，系统讲解 机架设置（Airframe Setup） 页面的完整用法：如何为 ArduCopter 多旋翼选择"框架类别 + 框架类型"，如何为 ArduSub 水下机器人选择推进器布局，并深入解读背后由 FRAME_CLASS、FRAME_TYPE、FRAME_CONFIG 参数驱动的实现原理，帮助你正确完成装机后的第一步配置。

适用范围：ArduCopter 与 ArduSub

机架设置页面用于选择与你的载具物理结构相匹配的框架类别（Frame Class）和框架类型（Frame Type）。需要特别注意的是：

机架设置仅对 ArduCopter 与 ArduSub 两类载具开放，ArduPilot 体系下的 Rover（地面车）与 Plane（固定翼）载具不会显示该页面。

这一点在源码中有直接体现。APMAirframeComponent.h 中定义了 _requiresFrameSetup 标志，只有当参数 FRAME_CLASS 存在且载具类型不是 MAV_TYPE_HELICOPTER 时才要求机架配置；而 APMAirframeComponent.cc 中 setupComplete() 的逻辑是"FRAME_CLASS 原始值非 0 即为已完成"，也就是说机架设置是 Copter 装机流程中的必选项，未完成配置时相关后续组件（如飞行模式、传感器）会被置为未完成状态——见 APMAutoPilotPlugin.cc 中 prerequisiteSetup() 对 airframe 前置条件的检查。

另外，QGroundControl 主设置页 Airframe Setup 会根据飞控固件分流：ArduPilot 走本文所述流程，PX4 则走 机架设置（PX4） 的"分组选择 + Apply and Restart"流程，两者界面与参数机制完全不同。

ArduCopter 机架设置：三步完成框架选择

为 Copter 选择机架的步骤如下：

1. 点击顶部工具栏中的齿轮（Gear）图标（即机架设置/载具设置入口），然后在侧边栏中首先选择 Airframe（机架）。
2. 为你的载具选择宽泛的框架类别（Frame Class）。
3. 为你的载具选择具体的框架类型（Frame Type）。

其中第 2 步有一个关键注意事项：

框架类别变更后必须重启载具才能生效。

框架类别决定飞控的运动学模型（多旋翼的轴数与布局），是底层参数，因此 QGroundControl 在 APMAirframeComponent.qml 的提示文本中同样写明："选择下方期望的框架类别，然后重启载具"。而框架类型（如 X 型、十字型）属于同一类别下的细分几何布局，选择后随即写入。

框架类别与类型的参数映射

界面上的一切选择最终都落到两个参数上：

参数名	作用	说明
FRAME_CLASS	框架类别	必须设置，类别切换后需重启载具
FRAME_TYPE	框架类型	仅在多旋翼（multiRotor）载具上可用，部分 Rover 版本不存在该参数

在 APMAirframeComponent.qml 中，两个 Fact 分别通过 controller.getParameterFact(-1, "FRAME_CLASS") 与 getParameterFact(-1, "FRAME_TYPE", false) 获取（第二个参数为 false 表示该参数缺失时不告警，因为并非所有固件都有 FRAME_TYPE）。点击某类别卡片时，QML 会先写入该类别的默认框架类型，再写入 FRAME_CLASS；而框架类型下拉框的值则直接写入 FRAME_TYPE。

类别与类型对应的枚举值定义在 APMAirframeComponentController.h 中，注释明确说明"应与 ArduCopter 的 FRAME_CLASS/FRAME_TYPE 参数枚举元数据保持一致"，部分取值如下：

• FRAME_CLASS 类别取值：0 未定义、1 Quad（四轴）、2 Hex（六轴）、3 Octa（八轴）、4 OctaQuad（共轴八轴）、5 Y6、6 Heli（直升机）、7 Tri（三轴）、12 DodecaHexa（十二轴/六轴共轴）等；
• FRAME_TYPE 类型取值：0 Plus（十字型）、1 X（X 型）、2 V（宽 V 型）、3 H（H 型）、4 V-Tail、5 A-Tail、10 Y6B、11 Y6F 等。

其中，类别 1（Quad）与类型 1（X 型）的组合是默认项（QuadRotorX），这可以从源码的图片映射表 _rgFrameToImageCopter 看出——每条记录都标注了"// Default"的默认组合，例如 Hex 的默认类型同样是 X 型。Copter.OfflineEditing.params（离线参数文件）中也记录了默认出厂值：FRAME_CLASS=1、FRAME_TYPE=0。

直升机类别的特殊处理

在 APMAirframeComponentController.cc 的 _fillFrameClasses() 中，对 ArduCopter 固件做了两处特殊处理：

• FRAME_CLASS_HELI（直升机）被直接跳过，原因是直升机需要独立的固件变体，无法从 Copter 变体固件切换过去；
• FRAME_CLASS_HELI_DUAL、FRAME_CLASS_HELIQUAD、FRAME_CLASS_SINGLECOPTER、FRAME_CLASS_COAXCOPTER、FRAME_CLASS_BICOPTER 等类别被标记为不支持，不会出现在类别卡片中。

同时，每个类别卡片右侧会显示一张真实线框图（如 QuadRotorX、HexaRotorX），图片由 _findImageResourceCopter() 根据"类别 + 类型"二元组查表得到，若组合无效则回退到 AirframeUnknown.svg 占位图——这也是判断你所选框架组合是否合法的直观手段。

ArduSub 机架设置：推进器布局与颜色约定 {#ardusub}

ArduSub（水下机器人/ROV）的框架选择流程与 Copter 不同：

1. 点击顶部工具栏中的齿轮（Gear）图标，然后在侧边栏中首先选择 Frame（框架）。
2. 选择与你的载具匹配的框架类型（选择即立即应用，无需重启）。
3. 检查推进器布局：确保所有绿色推进器安装顺时针螺旋桨，所有蓝色推进器安装逆时针螺旋桨（反之亦可，但需整体对调）。

第 3 点的颜色约定用于保证各推进器的旋转方向与飞控推力模型一致，属于 ArduSub 装机中的硬性检查项。此外：

你还可以点击 Load Vehicle Default Parameters（加载载具默认参数）按钮，为 ArduSub 载入一整套默认参数。

Sub 框架的内置清单

与 Copter 从参数枚举动态生成类别卡片不同，Sub 的框架列表在 APMSubFrameComponent.qml 中以 ListModel 硬编码，内置了以下 6 种框架：

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

选择框架写入的是 FRAME_CONFIG 参数（注意与 Copter 的 FRAME_CLASS/FRAME_TYPE 是两套完全不同的参数体系），FRAME_CONFIG 的默认值在 Sub.OfflineEditing.params 中记录为 1。

默认参数的自动下载逻辑

点击"加载载具默认参数"后，QGroundControl 会按以下链路从 ArduPilot 官方仓库拉取对应版本的参数文件（实现见 APMAirframeComponentController.cc 的 loadParameters() / _githubJsonDownloadComplete() / _paramFileDownloadComplete()）：

1. 根据固件版本号选择参数文件命名：Sub/<框架名>-<版本>.params，版本号依次取 4_0_0（≥ 4.0.0）、3_5_4（≥ 3.5.4）、3_5_2（≥ 3.5.2），否则回退到 3_5；
2. 向 GitHub API 请求 Tools/Frame_params/ 目录下的 JSON 元数据，解析出 download_url 后再下载真正的 .params 文本文件；
3. 逐行解析 参数名,值 格式的内容（跳过空行与 # 注释），通过 setRawValue() 写入对应参数，最后调用 refreshAllParameters() 刷新参数面板。

另外在 ArduSub 3.5.0 及以上版本中，Frame 组件会作为独立组件出现在设置列表中（见 APMAutoPilotPlugin.cc 中对 APMSubFrameComponent 的创建条件）；对于较旧的固件（低于 3.5.2），选择框架时还会弹出确认对话框询问是否同时加载默认参数，而 4.1.0 以上的固件则认为出厂默认值已足够合理，直接应用框架选择、不再提示。Sub 用户还可以参考电机测试（ArduSub）页面——如果电机方向异常，第一步就是回到本文所述的 Frame 标签页确认框架选择是否正确。

常见问题与排错提示

• 页面不显示 Airframe：说明当前连接的不是 ArduCopter / ArduSub 载具（Rover、Plane 或 PX4 固件不显示该页面），请先确认固件类型。
• 切换类别后行为未变化：框架类别必须重启载具后才生效，这是设计预期而非故障。
• 出现 "Invalid setting for FRAME_TYPE" 提示：当前 FRAME_CLASS 与 FRAME_TYPE 组合非法（如把 Copter 的 X 型值用在了不支持该类型的类别上），点击该提示即可重置。
• 电机/推进器方向与期望不符：Sub 请核对绿/蓝推进器的螺旋桨旋转方向约定；Copter 请在确认框架选择后进入电机测试页面逐项验证。

小结

机架设置是 ArduPilot 载具装机的第一道关卡：Copter 通过 FRAME_CLASS + FRAME_TYPE 两个参数描述多旋翼几何构型，类别变更需重启生效；Sub 则通过 FRAME_CONFIG 参数配合内置的框架清单与颜色约定完成推进器布局，并可一键下载官方默认参数。理解这些参数与界面背后的映射关系（可参考 APMAirframeComponentController.h 中的枚举表），能让你在排查电机、传感器等后续设置时更加得心应手。