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_ENABLE0总开关设为 1 启用脚本QUIK_RC_FUNC300用于控制调参的 RC 辅助通道脚本功能绑定号scripting1QUIK_AXES7参与调参的轴位掩码0Roll、1Pitch、2YawQUIK_DOUBLE_TIME10增益翻倍所需时间秒越大调得越慢QUIK_GAIN_MARGIN60检测到振荡后增益回落的百分比裕度QUIK_OSC_SMAX5振荡判定阈值Hz越小调参越保守QUIK_YAW_P_MAX0.5偏航轴 P 增益上限QUIK_YAW_D_MAX0.01偏航轴 D 增益上限QUIK_RP_PI_RATIO1.0横滚/俯仰轴 P 与 I 的比例QUIK_Y_PI_RATIO10偏航轴 P 与 I 的比例QUIK_AUTO_FILTER1根据 INS_GYRO_FILTER 自动设置 PID 滤波器QUIK_AUTO_SAVE0调参完成后自动保存的延时秒0 表示关闭QUIK_MAX_REDUCE20允许相对初始增益的最大下调比例%QUIK_OPTIONS0附加选项位掩码位 0 表示使用两位置开关QUIK_ANGLE_MAX10调参中止的姿态角误差上限度0 表示不检查其中QUIK_ANGLE_MAX在原文档正文中未展开介绍但在脚本源码中完整定义VTOL-quicktune.lua属于调参过程的重要保护机制本文将一并覆盖。QUIK_ENABLE总开关必须设为 1 脚本才会运行。脚本主更新函数update()的第一行就是检查QUIK_ENABLE:get() 1时直接返回VTOL-quicktune.lua。QUIK_RC_FUNCRC 通道绑定指定用于控制开始调参 / 暂停 / 保存的 RCz_OPTIONS 脚本功能绑定号默认值为 300即RCz_OPTION 300scripting1。若 300 被其他功能占用可通过此参数改用 302scripting3等其他绑定。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.luaUPDATE_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_RATIOP/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_ratioVTOL-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. 安装脚本并启用脚本系统将 VTOL-quicktune.lua 复制到飞控 microSD 卡的APM/SCRIPTS目录可使用 MAVFtp 上传参考 AP_Scripting/README.md 中关于脚本系统的说明设置SCR_ENABLE 1启用脚本系统重启飞控然后刷新参数列表将QUIK_ENABLE设为 1。3. 矢量偏航机型特例如果使用矢量偏航机型tilt rotors 倾转旋翼或 TVBS 尾座式电机安装在倾转舵机上的 tailsitter在运行偏航调参前请先将Q_A_RAT_YAW_FLTE 设为 0。4. 绑定调参开关需要在一个空闲 RC 输入通道上设置三位置开关若设置了 QUIK_AUTO_SAVE 则两位置开关亦可来控制调参例如通道 6 空闲且装有三位开关设置RC6_OPTION 300scripting1将调参控制与开关关联若需要可通过QUIK_RC_FUNC改用其他脚本绑定例如RCz_OPTION 302scripting3。从源码看脚本通过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_DRLL_PPIT_DPIT_PYAW_DYAW_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.0VTOL-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_AQ_A_RAT_RLL_P等存在ATC_RAT_RLL_SMAX→ 判定为多旋翼参数前缀使用ATCATC_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 40VTOL-quicktune.lua。update()的完整状态机逻辑VTOL-quicktune.lua依次处理检查QUIK_ENABLE检测飞行员输入并记录时间读取开关位置未绑定开关则直接返回检查是否已解锁且在飞行否则提示 Tuning: Must be flying to tune低位置 / 未解锁 / 未飞行 → 回退全部参数并复位高位置 → 保存全部参数姿态角误差超限检查QUIK_ANGLE_MAX阶段延时STAGE_DELAY 4.0秒内执行增益斜坡slew振荡判定与增益调整或增益爬升。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与增益GainVTOL-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 181QUICKTUNE 辅助功能会更简洁使用 Lua 脚本版本则通过QUIK_参数与 RC 通道的 scripting1 绑定300。两者概念完全对应可参照本文第二、四、五节的参数与流程进行配置。八、注意事项与调参经验小结谐波陷波是前提没有把陀螺噪声降到足够低之前不要运行 QuickTune否则结果不可信且可能引发真实振荡大机型务必调低 QUIK_OSC_SMAX按机型质量参考 50kg → 3、100kg → 1.5若调参后仍有可见振荡将该参数减半重试偏航轴受上限保护QUIK_YAW_P_MAX0.5与QUIK_YAW_D_MAX0.01保证了偏航不会吃掉横滚/俯仰/推力的控制余量通常无需修改矢量偏航机型先清 YAW_FLTEtilt rotor 与 TVBS tailsitter 需在偏航调参前设Q_A_RAT_YAW_FLTE 0保存纪律三位置开关模式下降落解锁前必须拨到高位置保存否则参数自动回退两位置开关模式则依赖QUIK_AUTO_SAVE的延时自动保存已有良好调参时可设QUIK_MAX_REDUCE 0禁止下调防止低增益误报振荡后出现危险的角度环 P 振荡误报处理出现attitude error ... ABORTING时先确认是否真振荡若确认误报可提高QUIK_ANGLE_MAX或放慢QUIK_DOUBLE_TIME飞行中有人为输入会暂停调参暂停于飞行员输入结束后 4 秒因此低风、无人打扰的悬停是理想调参环境两种实现二选一Lua 版QUIK_与原生版QWIK_AUX_FUNC 181算法一致但参数前缀与绑定方式不同不要混用。完成调参并保存后建议在后续飞行中关注各轴响应与振荡余量必要时微调QUIK_GAIN_MARGIN再做一次 QuickTune即可在较低风险下获得一份贴合机体的 VTOL 速率环参数。【免费下载链接】ardupilotArduPlane, ArduCopter, ArduRover, ArduSub source项目地址: https://gitcode.com/GitHub_Trending/ar/ardupilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
