ArduPilot VTOL QuickTune 自动调参完全指南：基于脚本与源码的多旋翼/垂起固定翼速率增益自动整定

ArduPilot VTOL QuickTune 自动调参完全指南：基于脚本与源码的多旋翼/垂起固定翼速率增益自动整定

【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot

导读

VTOL QuickTune 是 ArduPilot 提供的一套面向多旋翼（multicopter）与垂起固定翼（quadplane）的自动速率环调参系统，它以 Lua 脚本形式运行在飞控的脚本环境中（同时仓库还提供了等价的 C++ 原生实现），能够自动完成原本需要人工反复试飞才能完成的"手动调参"过程，产出可靠的 VTOL 速率控制（rate control）参数。本文以仓库中的 VTOL-quicktune.md 为骨架，结合 VTOL-quicktune.lua 与 AP_Quicktune 的源码实现，完整讲解全部 QUIK_ 参数、安装部署步骤、三/两位置开关操作流程以及底层的振荡检测与增益整定原理，帮助你安全、高效地完成一次 VTOL 自动调参。

一、VTOL QuickTune 是什么

VTOL QuickTune 脚本的核心目标非常明确：自动化为 VTOL 速率控制参数生成一份良好的"手动调参"结果。它的使用场景是：

• 多旋翼（ArduCopter）：在LOITER模式中使用；
• 垂起固定翼（ArduPlane QuadPlane）：在QLOITER模式中使用；
• 其他 VTOL 模式同样可用，但悬停类模式最理想。

调参期间脚本会在受控悬停中逐步提高各轴增益，直到检测到微小振荡为止，随后将增益回落至设定的安全裕度（gain margin）并进入下一个参数，最终得到一组"恰好避开振荡点"的速率环 PID 参数。

需要特别说明：文档与脚本都明确要求，调参前必须已经配置好谐波陷波滤波器（harmonic notch filter），将陀螺仪噪声降到足够低。QuickTune 依赖干净的速率信号才能可靠工作，"噪声过高时它将会失败"（原文语）。

从仓库的发布记录（ArduPlane/ReleaseNotes.txt）可以看到，VTOL quicktune 脚本经历了长期演进：从最初的脚本加入（"added VTOL-quicktune lua script"），到后续同步、增加QUIK_MAX_REDUCE参数、提高YAW_FLTE_MAX至 8 等多次增强，功能已相当成熟。

二、参数总览：14 个 QUIK_ 控制参数

脚本通过参数表机制动态注册了一批QUIK_前缀参数（源码见 VTOL-quicktune.lua，参数表容量为 15 个）。下表汇总了全部参数及其默认值与含义，下文逐一详解。

其中QUIK_ANGLE_MAX在原文档正文中未展开介绍，但在脚本源码中完整定义（VTOL-quicktune.lua），属于调参过程的重要保护机制，本文将一并覆盖。

QUIK_ENABLE（总开关）

必须设为 1 脚本才会运行。脚本主更新函数update()的第一行就是检查QUIK_ENABLE:get() < 1时直接返回（VTOL-quicktune.lua）。

QUIK_RC_FUNC（RC 通道绑定）

指定用于控制"开始调参 / 暂停 / 保存"的 RCz_OPTIONS 脚本功能绑定号，默认值为 300，即RCz_OPTION = 300（scripting1）。若 300 被其他功能占用，可通过此参数改用 302（scripting3）等其他绑定。

QUIK_AXES（调参轴选择）

位掩码，默认 7 = 横滚 + 俯仰 + 偏航三轴全调：

• 仅横滚 + 俯仰：设为3；
• 仅偏航：设为4。

源码中axis_enabled()与get_current_axis()通过(1 << (i-1))按位判断当前轴是否参与（VTOL-quicktune.lua），轴处理顺序固定为 RLL（横滚）、PIT（俯仰）、YAW（偏航）。

QUIK_DOUBLE_TIME（增益加倍时间）

控制调参过程中增益的提升速度，单位为秒。它表示"当前增益翻一倍所需的时间"，默认 10 秒，绝大多数用户保持默认即可。调参循环中每个周期增益的乘法因子为：

gain_mul = exp( ln(2) / (UPDATE_RATE_HZ × QUIK_DOUBLE_TIME) )

对应源码 VTOL-quicktune.lua（UPDATE_RATE_HZ 为 40）。调得太快容易在噪声下误判振荡，调得太慢则浪费时间，可结合QUIK_ANGLE_MAX误报情况适当调整。

QUIK_GAIN_MARGIN（增益裕度）

找到某增益的振荡点后，将增益降低该百分比作为最终值。默认 60% 意味着最终增益约为振荡点增益的 40%，对大多数用户是合适的保守取值。若希望调参结果更激进（贴近振荡边界）可降低此值，更保守则提高。

QUIK_OSC_SMAX（振荡判定阈值）

振荡检测阈值，单位 Hz。当某轴当前实际姿态变化速率（slew rate）超过该阈值时判定为振荡（源码中oscillating = srate > QUIK_OSC_SMAX:get()，VTOL-quicktune.lua）。默认 5Hz 对大多数机型适用，但大型飞行器建议调低：

• 约 50kg 的飞行器：建议设为3；
• 约 100kg 的飞行器：建议设为1.5。

判断设置是否过高的方法：若某个参数完成调参后仍然能看到明显振荡，说明阈值太高，将该参数减半再重试。

QUIK_YAW_P_MAX / QUIK_YAW_D_MAX（偏航增益上限）

多旋翼类飞行器的偏航轴需要远低于振荡极限的 P/D 增益上限，以保证横滚、俯仰和推力方向上有足够的控制余量。默认YAW_P上限 0.5、YAW_D上限 0.01，对大多数 VTOL 机型适用。调参达到该上限时脚本直接判定"完成"而不再继续升高（对应源码reached_limit()，VTOL-quicktune.lua）。

QUIK_RP_PI_RATIO / QUIK_Y_PI_RATIO（P/I 比例）

• QUIK_RP_PI_RATIO：横滚/俯仰轴 P 与 I 的比例，默认 1。在部分大型飞行器上，若 I 项造成过多相位滞后，可提高至最高 3。
• QUIK_Y_PI_RATIO：偏航轴 P 与 I 的比例，默认 10，部分机型可能需要不同取值。

两者的共同规则：若该比例小于 1，则修改 P 时 I 将保持不变。源码中的实现逻辑是：当被调整的参数是某轴的_P时，若该轴存在非零的_FF（前馈）增益则不耦合 I（通常希望 I = FF 以得到一秒的时间常数用于配平），否则按比例同步更新 I 为value/PI_ratio（VTOL-quicktune.lua）。

QUIK_AUTO_FILTER（自动滤波器设置）

置 1（默认）时，脚本会根据INS_GYRO_FILTER自动设置 PID 滤波器。置 0 关闭。具体规则见下文"自动滤波器规则"小节。

QUIK_AUTO_SAVE（自动保存）

调参结束后经过该秒数自动保存调参结果。设为非零值后可配合两位置开关使用（低位/中位分别对应停止与调参）；设为 0 则关闭自动保存，此时必须使用三位置开关手动保存。

QUIK_MAX_REDUCE（最大增益下调限制）

限制 QuickTune 相对原始增益最多允许下调的比例（百分比），默认 20%。如果飞行器已有一份合理调参且没有振荡，可将此参数设为 0 禁止任何增益下调。设置该上限可以降低"在低增益处误判振荡"引发的风险——如果 QuickTune 在低增益误报振荡，可能把速率增益降得过低，从而诱发危险的角度环 P 振荡。源码中limit_gain()会在下调幅度超过上限时截断增益（VTOL-quicktune.lua），并在地面站输出limiting xxx yyy -> zzz提示。

QUIK_OPTIONS（附加选项）

位掩码，位 0（数值 1）表示"使用两位置开关"。开启后，开关高位开始调参、低位停止调参，并必须同时设置QUIK_AUTO_SAVE才能完成保存（详见"两位置开关"一节）。

QUIK_ANGLE_MAX（姿态误差中止保护）

调参过程中若姿态角误差超过该值（度，默认 10），脚本立即中止调参并恢复所有参数，避免算法失败时发展为失控振荡。若地面站出现Tuning: attitude error ... ABORTING且你认为属于误报，可以适当调高此参数，或提高QUIK_DOUBLE_TIME让调参更慢。设为 0 可关闭该项检查（源码见 VTOL-quicktune.lua）。

三、安装与部署步骤

1. 前置条件：谐波陷波滤波

按照 ArduPilot Wiki 的指南完成谐波陷波滤波器设置。QuickTune 依赖陷波滤波把陀螺仪噪声降到足够低才能正确工作，噪声过高时调参将失败。

2. 安装脚本并启用脚本系统

1. 将 VTOL-quicktune.lua 复制到飞控 microSD 卡的APM/SCRIPTS目录（可使用 MAVFtp 上传，参考 AP_Scripting/README.md 中关于脚本系统的说明）；
2. 设置SCR_ENABLE = 1启用脚本系统；
3. 重启飞控，然后刷新参数列表；
4. 将QUIK_ENABLE设为 1。

3. 矢量偏航机型特例

如果使用矢量偏航机型（tilt rotors 倾转旋翼）或 TVBS 尾座式（电机安装在倾转舵机上的 tailsitter），在运行偏航调参前请先将Q_A_RAT_YAW_FLTE 设为 0。

4. 绑定调参开关

需要在一个空闲 RC 输入通道上设置三位置开关（若设置了 QUIK_AUTO_SAVE 则两位置开关亦可）来控制调参：

• 例如通道 6 空闲且装有三位开关：设置RC6_OPTION = 300（scripting1）将调参控制与开关关联；
• 若需要，可通过QUIK_RC_FUNC改用其他脚本绑定，例如RCz_OPTION = 302（scripting3）。

从源码看，脚本通过rc:get_aux_cached(QUIK_RC_FUNC:get())读取开关位置（VTOL-quicktune.lua），其语义为：0 = 低位置（停止/回退）、1 = 中位置（调参）、2 = 高位置（保存）。

四、调参操作流程（三位置开关）

1. 起飞并悬停

起飞后将飞行器切入QLOITER（垂起固定翼）或LOITER（多旋翼）模式，在低风环境中稳定悬停。

2. 开始调参

将调参开关（绑定 300 或 QUIK_RC_FUNC 指定的功能）拨到中间位置，调参开始。地面站会持续显示调参进度文本消息。飞行器在逼近每个参数的振荡极限时会出现小幅振荡，随后该增益按QUIK_GAIN_MARGIN百分比回落，接着进入下一个参数。

3. 默认调参顺序

默认设置下依次调参的参数为：

• RLL_D
• RLL_P
• PIT_D
• PIT_P
• YAW_D
• YAW_P

即先调各轴的 D（微分）再调 P（比例），顺序为横滚 → 俯仰 → 偏航，与源码中stages = { "D", "P" }、axis_names = { "RLL", "PIT", "YAW" }的枚举顺序一致（VTOL-quicktune.lua）。

4. 自动滤波器规则

若QUIK_AUTO_FILTER = 1（默认），脚本按以下规则调整滤波器设置：

• FLTD 与 FLTT 设为 INS_GYRO_FILTER 值的一半；
• YAW_FLTE 最大不超过 8Hz。

此外，如果某轴速率控制器未设置 SMAX（即 SMAX 为 0），脚本会将其设为50Hz。以上常量与逻辑见源码 VTOL-quicktune.lua 与setup_filters()（VTOL-quicktune.lua）。

5. 调参完成与保存

调参全部结束后地面站显示"Tuning: done"。请务必在降落并解锁（disarm）之前，将开关拨到**高位置（Tune Save）**保存结果。保存语义细节如下：

• 调参未完成时拨到高位置保存：调参暂停，已完成参数的当前值被保存，正在调参的参数保持当前活动值；之后将开关拨回中间位置可继续调参；
• 调参未完成时拨到低位置：正在调参的参数被回退，但之前已保存的参数保持不变；
• 调参过程中任意时刻拨到低位置（在从未使用保存位置之前）：所有参数回退为原始值；
• 保存前就降落解锁（disarm）：所有参数同样回退为原始值。

6. 飞行员输入保护

调参过程中若飞行员给出横滚、俯仰或偏航输入，调参会暂停，直到飞行员输入停止 4 秒后才恢复。对应源码中have_pilot_input()与PILOT_INPUT_DELAY = 4.0（VTOL-quicktune.lua）。

五、使用两位置开关（无三位开关的遥控器）

部分遥控器只有两位置开关，QuickTune 为此提供了专门支持。请设置：

• QUIK_OPTIONS = 1：启用"两位置开关"选项；
• QUIK_AUTO_SAVE = 10：调参完成后 10 秒自动保存。

设置这两项后：

• 调参在开关给出PWM 值大于 1800（即高位置）时开始；
• 调参完成后10 秒自动保存。

源码实现上，开启OPTIONS_TWO_POSITION后，调参位置被重映射为sw_pos_tune = 2（高），保存位置为-1（禁用，即依赖自动保存），见 VTOL-quicktune.lua；自动保存逻辑在update()尾部检查tune_done_time与QUIK_AUTO_SAVE之差（VTOL-quicktune.lua）。

六、源码级原理解析

1. 脚本如何识别飞行器类型

脚本启动时通过探测参数是否存在判断载体类型（VTOL-quicktune.lua）：

• 存在Q_A_RAT_RLL_SMAX→ 判定为 quadplane，参数前缀使用Q_A（Q_A_RAT_RLL_P等）；
• 存在ATC_RAT_RLL_SMAX→ 判定为多旋翼，参数前缀使用ATC（ATC_RAT_RLL_P等）；
• 两者都不存在 → 输出 "Quicktune unknown vehicle" 并退出。

随后脚本为RLL/PIT/YAW×FF/P/I/D/SMAX/FLTT/FLTD/FLTE共 24 个速率环参数建立绑定（VTOL-quicktune.lua）。

2. 主循环与调度

脚本通过protected_wrapper()以40Hz周期调用update()（UPDATE_RATE_HZ = 40，VTOL-quicktune.lua）。update()的完整状态机逻辑（VTOL-quicktune.lua）依次处理：

1. 检查QUIK_ENABLE；
2. 检测飞行员输入并记录时间；
3. 读取开关位置，未绑定开关则直接返回；
4. 检查是否已解锁且在飞行（否则提示 "Tuning: Must be flying to tune"）；
5. 低位置 / 未解锁 / 未飞行 → 回退全部参数并复位；
6. 高位置 → 保存全部参数；
7. 姿态角误差超限检查（QUIK_ANGLE_MAX）；
8. 阶段延时（STAGE_DELAY = 4.0秒）内执行增益斜坡（slew）；
9. 振荡判定与增益调整或增益爬升。

3. 增益爬升与振荡检测

• 爬升：未达到振荡阈值时，每个周期把当前增益乘以get_gain_mul()（指数翻倍因子），同时若开启了QUIK_AUTO_FILTER则先完成滤波器设置；
• 振荡判定：通过AC_AttitudeControl:get_rpy_srate()获取各轴实际速率变化率，srate > QUIK_OSC_SMAX即判定振荡（VTOL-quicktune.lua）；
• 回落：判定振荡后，新增益 = 当前增益 ×(100 - QUIK_GAIN_MARGIN) / 100；若只是触及增益上限（如偏航的YAW_P_MAX/YAW_D_MAX）而非振荡，则按 100% 保留（即不再降低）；
• D 降则 P 同步降：当横滚/俯仰的 D 增益需要从原始值下调时，P 增益按相同比例同步下调（但下调不超过 2 倍），以避免诱发 P 振荡（VTOL-quicktune.lua）；
• 增益斜坡：新增益通过 20 步（UPDATE_RATE_HZ/2）的渐变斜坡写入，避免跳变，并在斜坡完成后判定整轴/整体是否结束（Tuning: DONE）。

4. 回退与保存的数据流

脚本在开始调参时把全部 24 个参数快照到param_saved，之后任何改动都记录在param_changed位掩码中。回退（restore_all_params()）只恢复被改动过的参数；保存（save_all_params()）则对改动过的参数执行set_and_save写入持久存储（VTOL-quicktune.lua）。整个调参期间参数以set()方式在内存中生效，因此任何时刻拨到低位置都能无损恢复原始调参。

5. 调参过程日志

脚本使用logger.write('QUIK', 'SRate,Gain,Param', ...)在调参全程记录各参数调整时的速率（SRate）与增益（Gain）（VTOL-quicktune.lua），调参后可通过 QUIK 日志块回放分析每个参数的振荡边界行为。

七、C++ 原生版本：AP_Quicktune

除了 Lua 脚本，仓库还提供了一套基于 Lua 脚本移植的 C++ 原生实现AP_Quicktune（见 AP_Quicktune.h 与 AP_Quicktune.cpp，注释明确标注 "C++ implementation of quicktune based on original lua script"）。两者算法结构一致，C++ 版本更适用于无脚本系统或希望省去脚本环境的固件。

关键差异与集成方式：

• 参数前缀不同：C++ 版本注册的是QWIK_前缀参数（QWIK_ENABLE、QWIK_AXES、QWIK_GAIN_MARGIN等），在 ArduPlane/Parameters.cpp 中通过GOBJECT(quicktune, "QWIK_", AP_Quicktune)挂载，默认值见 AP_Quicktune.cpp（注意其中OSC_SMAX默认 4、YAW_FLTE_MAX为 2.0，与 Lua 版的 5 / 8.0 略有差异）；
• RC 通道绑定：C++ 版使用独立辅助功能AUX_FUNC::QUICKTUNE（编号 181，见 RC_Channel.h），三位置开关直接映射到该辅助功能；ArduPlane 侧在 RC_Channel_Plane.cpp 中调用plane.quicktune.update_switch_pos(ch_flag)把开关位置喂给 QuickTune；
• 调度与模式检查：ArduPlane 以 40Hz 周期调度SCHED_TASK(update_quicktune, 40, 100, 163)（Plane.cpp），并通过quicktune.update(control_mode->supports_quicktune())传入"当前模式是否支持 QuickTune"——若调参过程中切入不支持的模式，会立即中止并回退参数（Plane.cpp）。在 mode.h 中，QLOITER 等 VTOL 悬停模式重写了supports_quicktune()返回true；
• 启用开关：AP_QUICKTUNE_ENABLED在 mode.h 中默认为HAL_QUADPLANE_ENABLED，即 QuadPlane 固件默认编译启用。

如果你使用的是 ArduPlane 垂起固件且固件包含 QuickTune（可查看是否出现QWIK_参数），使用原生QWIK_参数与 AUX_FUNC 181（QUICKTUNE 辅助功能）会更简洁；使用 Lua 脚本版本则通过QUIK_参数与 RC 通道的 scripting1 绑定（300）。两者概念完全对应，可参照本文第二、四、五节的参数与流程进行配置。

八、注意事项与调参经验小结

1. 谐波陷波是前提：没有把陀螺噪声降到足够低之前不要运行 QuickTune，否则结果不可信且可能引发真实振荡；
2. 大机型务必调低 QUIK_OSC_SMAX：按机型质量参考 50kg → 3、100kg → 1.5，若调参后仍有可见振荡，将该参数减半重试；
3. 偏航轴受上限保护：QUIK_YAW_P_MAX（0.5）与QUIK_YAW_D_MAX（0.01）保证了偏航不会吃掉横滚/俯仰/推力的控制余量，通常无需修改；
4. 矢量偏航机型先清 YAW_FLTE：tilt rotor 与 TVBS tailsitter 需在偏航调参前设Q_A_RAT_YAW_FLTE = 0；
5. 保存纪律：三位置开关模式下，降落解锁前必须拨到高位置保存，否则参数自动回退；两位置开关模式则依赖QUIK_AUTO_SAVE的延时自动保存；
6. 已有良好调参时：可设QUIK_MAX_REDUCE = 0禁止下调，防止低增益误报振荡后出现危险的角度环 P 振荡；
7. 误报处理：出现attitude error ... ABORTING时，先确认是否真振荡；若确认误报，可提高QUIK_ANGLE_MAX或放慢QUIK_DOUBLE_TIME；
8. 飞行中有人为输入会暂停：调参暂停于飞行员输入结束后 4 秒，因此低风、无人打扰的悬停是理想调参环境；
9. 两种实现二选一：Lua 版（QUIK_）与原生版（QWIK_，AUX_FUNC 181）算法一致但参数前缀与绑定方式不同，不要混用。

完成调参并保存后，建议在后续飞行中关注各轴响应与振荡余量，必要时微调QUIK_GAIN_MARGIN再做一次 QuickTune，即可在较低风险下获得一份贴合机体的 VTOL 速率环参数。

【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot