Quicktune Max Attitude Error (QWIK_ANGLE_MAX)

Description

QWIK_ANGLE_MAX is the "Emergency Kill Switch" for the tuning process.

If the drone's actual tilt angle differs from your stick command by more than this many degrees (indicating that the drone is losing control or oscillating wildly), Quicktune will instantly abort the tune and revert to your original safe gains.

Tuning & Behavior

• Default Value: 10 degrees.
• Recommendation: If you get "Attitude Error - Aborting" messages during tuning even when the drone seems stable, try increasing this to 15 or 20.
• Safety: Do not set this too high (e.g. >30), as it protects the drone from a bad tune that could lead to a crash.

Quicktune Auto Filter Enable (QWIK_AUTO_FILTER)

Description

QWIK_AUTO_FILTER automates one of the most confusing parts of tuning: the PID filters.

For a sharp, high-performance tune, the PID filters (FLTT, FLTD, FLTE) should be related to the INS_GYRO_FILTER. When this parameter is enabled, Quicktune will automatically update your filter settings at the start of the tuning process to ensure they are optimal for your current hardware configuration.

Tuning & Behavior

• Default Value: 1 (Enabled).
• Recommendation: Keep enabled. It ensures that your filter settings evolve alongside your PID gains for a balanced tune.

Quicktune Auto Save Time (QWIK_AUTO_SAVE)

Description

QWIK_AUTO_SAVE allows the autopilot to permanently store the new PID gains without requiring a separate "Save" command from the pilot.

Normally, you have to toggle a switch on your remote to save the tune. If you set this parameter to 10, the drone will wait for 10 seconds after it finishes tuning all axes and then automatically save the values to memory.

• 0 (Default): Auto-save disabled. You must save manually using an RC switch or the Ground Station.

Quicktune Axes (QWIK_AXES)

Description

QWIK_AXES defines which flight axes the Quicktune assistant will attempt to optimize.

• Bit 0 (1): Roll
• Bit 1 (2): Pitch
• Bit 2 (4): Yaw

Tuning & Behavior

• Default Value: 7 (All axes).
• Recommendation: Usually, it is best to tune all three axes in one flight. However, if you are experiencing issues with a specific axis (like a vibrating tail), you can uncheck Yaw to focus only on Roll and Pitch.

Quicktune Doubling Time (QWIK_DOUBLE_TIME)

Description

QWIK_DOUBLE_TIME controls the "Aggression" of the tuning process.

It determines how fast the autopilot increases the PID gains while searching for the oscillation point.

• Low Value (5s): Fast tune. The gains increase rapidly. Good for experienced pilots and stable frames.
• High Value (20s): Slow tune. Safer for large, heavy, or expensive drones where a sudden oscillation could be dangerous.

Tuning & Behavior

• Default Value: 10 seconds.
• Recommendation: If you get "Attitude Error - Aborting" messages during tuning, increase this value to 15 or 20 to give the drone more time to stabilize between gain steps.

Quicktune Enable (QWIK_ENABLE)

Description

QWIK_ENABLE activates an automated, in-flight PID tuning assistant.

Quicktune is a C++ implementation of the popular "QuickTune" Lua script. It works by slowly increasing your drone's P and D gains while you fly until it detects a small oscillation. It then backs off the gain to a safe margin. This allows you to get a high-performance tune in minutes without needing to use the full AutoTune mode.

Tuning & Behavior

• Default Value: 0 (Disabled).
• Usage: Once enabled, you must assign an RC channel to RCx_OPTION = 129 (QuickTune) to start/stop the tuning process in flight.
• Reboot Required: Yes.

Quicktune Gain Margin (QWIK_GAIN_MARGIN)

Description

QWIK_GAIN_MARGIN determines how "Conservative" or "Aggressive" the final tune will be.

During the tuning process, Quicktune increases your gains until the drone starts to shake (oscillate). It then takes that "Limit" value and reduces it by this percentage to find a safe, stable flying gain.

• Higher Value (80%): More conservative. The final gains will be lower and the drone will feel smoother but less "Locked in."
• Lower Value (40%): More aggressive. The final gains will be closer to the oscillation point, resulting in a very sharp, high-performance feel.

Tuning & Behavior

• Default Value: 60%.
• Recommendation: Start with 60%. If the drone still feels a bit loose after tuning, try 50%.

Quicktune options (QWIK_OPTIONS)

Description

This parameter provides additional configuration for the Quicktune automated tuning system. Its primary use is to simplify the control logic for pilots who prefer using a standard 2-position toggle switch rather than the default 3-position behavior.

The Mathematics

The parameter is a bitmask ($B$):

• Bit 0 (Value 1): Use Two-Position Switch.
  • Disabled (0): Default 3-position logic.
    • Low: Abort/Revert.
    • Mid: Start Tuning.
    • High: Save Tune.
  • Enabled (1): Simplified 2-position logic.
    • Low: Disable/Abort.
    • High: Start Tuning.
    • (Note: Requires QWIK_AUTO_SAVE to be configured to save the results automatically).

The Engineer's View

In AP_Quicktune::update() (libraries/AP_Quicktune/AP_Quicktune.cpp), the logic branches based on the OPTIONS_TWO_POSITION flag.
If Bit 0 is set:

1. The sw_pos_tune target is shifted to SwitchPos::HIGH.
2. The sw_pos_save target is set to SwitchPos::NONE, meaning the switch itself cannot trigger a save.
3. The system relies on the tune_done_time_ms timer and the auto_save parameter to commit the learned gains to EEPROM after the tuning session successfully completes.

Tuning & Behavior

• Default Value: 0 (Standard 3-position switch logic).
• When to Use: If you are short on auxiliary channels or prefer a simple "Tune ON / Tune OFF" switch.
• Safety Hint: If using the 2-position mode, ensure QWIK_AUTO_SAVE is set to a non-zero value (e.g., 10 seconds), otherwise your new tune will be lost the moment you flip the switch back to Low.

Quicktune Oscillation Threshold (QWIK_OSC_SMAX)

Description

QWIK_OSC_SMAX defines how much "Shaking" the autopilot allows before it decides the gain is too high.

The system monitors the "Slew Rate" (how fast the motors are changing speed) to detect the onset of high-frequency oscillations.

• Lower Value (1-2): Very sensitive. Quicktune will stop increasing gains at the first hint of a vibration.
• Higher Value (6-10): Less sensitive. Allows the drone to shake more violently before backing off.

Tuning & Behavior

• Default Value: 4.
• Recommendation: Leave at 4. Only increase this if you find that Quicktune is stopping prematurely due to noise from imbalanced propellers or a loose frame.

Quicktune Max Gain Reduction (QWIK_REDUCE_MAX)

Description

QWIK_REDUCE_MAX is a "Safety Floor" for the tuning process.

If your drone already flies reasonably well, you don't want a "False Positive" oscillation detection (caused by wind or a bump) to trick the system into dropping your gains to dangerously low levels. This parameter prevents Quicktune from lowering your original gains by more than the specified percentage.

• Default: 20%.
• 0: No reduction allowed. Quicktune can only increase your gains or leave them as they are.

Quicktune roll/pitch PI ratio (QWIK_RP_PI_RATIO)

Description

This parameter defines the fixed relationship (ratio) between the Proportional (P) and Integral (I) gains that Quicktune maintains while it searches for the optimal tune for Roll and Pitch.

In many flight control systems, the P and I gains are "coupled"—as you increase the responsiveness (P), you must also increase the "correction force over time" (I) to maintain a balanced feel and prevent drift. This parameter automates that coupling, ensuring that as Quicktune pushes for higher performance, it keeps the integrator balanced.

The Mathematics

During the tuning process, whenever Quicktune adjusts the P gain ($K\_p$), it automatically calculates the new I gain ($K\_i$) using this ratio ($\gamma$):

$$ K\_i = \frac{K\_p}{\gamma} $$

Where $\gamma$ is QWIK_RP_PI_RATIO.

For example, if the ratio is 1.0, the I gain will always equal the P gain. If the ratio is 2.0, the I gain will be exactly half of the P gain.

The Engineer's View

In AP_Quicktune::adjust_gain() (libraries/AP_Quicktune/AP_Quicktune.cpp):

1. The code identifies when a P gain is being modified.
2. It checks if FeedForward (FF) is present. If FF > 0, the system assumes a more advanced control model where I is matched to FF for a 1-second time constant, and this ratio is ignored.
3. If no FF is used, it reads rp_pi_ratio and performs the division: set_param_value(iname, value/pi_ratio).
4. This ensures that the "Integrator Time Constant" remains consistent throughout the entire automated tuning session, preventing the aircraft from becoming sluggish or "drifty" while the P gain is being swept.

Tuning & Behavior

• Default Value: 1.0 (Balanced).
• Range: 1.0 to 2.0.
• Effect of Increasing: Results in a lower relative I gain. This can make the vehicle feel less "locked-in" but reduces the risk of low-frequency oscillations.
• Effect of Decreasing: Results in a higher relative I gain, providing stronger resistance to external disturbances (like wind) but potentially causing slow "wandering" if set too low.

Quicktune Yaw D max (QWIK_YAW_D_MAX)

Description

This parameter defines the maximum limit for the Yaw Derivative (D) gain that the Quicktune system is allowed to set.

The D-gain is primarily used to "dampen" the tail of the aircraft, preventing it from overshooting when you stop a turn. However, yaw dynamics involve a lot of inertia, and setting the D-gain too high can cause high-frequency vibrations that result in hot motors or ESC failures. This parameter ensures that the automated tuning process never enters that dangerous high-gain territory.

The Mathematics

The system monitors for oscillations while increasing the D-gain, but will stop immediately if the gain reaches this ceiling:

$$ K\_{d\_yaw} = \min(K\_{target}, QWIK\_YAW\_D\_MAX) $$

A value of 0.01 is a common starting point for medium-sized multirotors.

The Engineer's View

In AP_Quicktune::gain_limit() (libraries/AP_Quicktune/AP_Quicktune.cpp):

1. The code checks the tuning axis.
2. For the YAW axis, it specifically retrieves the _yaw_d_max parameter value.
3. This ceiling is used in the limited check within the update() function to terminate the "Search" phase for the D-gain stage of the tune.
4. By providing a hard limit, ArduPilot protects against "false negatives" where the algorithm might not detect a subtle high-frequency vibration that is still damaging to the hardware.

Tuning & Behavior

• Default Value: 0.01.
• Range: 0.001 to 1.0.
• When to Increase: If your vehicle has very little damping and "bounces" at the end of a yaw rotation after a Quicktune session.
• When to Decrease: If your motors are warm after a flight where you used Quicktune, or if you hear high-frequency "chirping" from the motors during yaw maneuvers.
• Note: Most vehicles require very little Yaw D-gain compared to Roll or Pitch.

Quicktune Yaw P max (QWIK_YAW_P_MAX)

Description

This parameter sets a "Safety Ceiling" for the Yaw Proportional (P) gain during the Quicktune process. It prevents the automated tuning algorithm from increasing the yaw responsiveness beyond a point that might be physically dangerous or cause mechanical fatigue, even if the software does not detect any oscillations.

Yaw control on many aircraft (especially multirotors) is achieved via motor torque differential, which is less efficient than roll or pitch. Setting a maximum limit ensures that the tune remains conservative and doesn't demand more from the motors than is safe for long-term operation.

The Mathematics

The tuning algorithm calculates an incremental target gain ($K\_{target}$), but the final value applied to the vehicle's PID controller is always capped:

$$ K\_{p\_yaw} = \min(K\_{target}, QWIK\_YAW\_P\_MAX) $$

This prevents the algorithm from "running away" if the oscillation detection threshold is set too high or if the airframe is exceptionally stiff.

The Engineer's View

In AP_Quicktune::gain_limit() (libraries/AP_Quicktune/AP_Quicktune.cpp):

1. The code checks if the axis being tuned is AxisName::YAW.
2. If true, it returns the value of yaw_p_max.
3. In the update() loop, this limit is used to check if the current test gain has reached the user-defined boundary (limited = (limit > 0.0 && pval >= limit)).
4. If the limit is hit, the tuning stage for that gain is marked as "Done" and the system moves to the next parameter.

Tuning & Behavior

• Default Value: 0.5.
• Range: 0.1 to 3.0.
• When to Increase: If the vehicle still feels "lazy" or slow to hold heading after a Quicktune session, and you are certain the mechanics can handle more aggressive torque changes.
• When to Decrease: If you have a very powerful, high-torque vehicle where even small gains result in violent yaw kicks.
• Dependencies: Works in conjunction with QWIK_Y_PI_RATIO to determine the final $K\_i$ for the yaw axis.

Quicktune Yaw PI ratio (QWIK_Y_PI_RATIO)

Description

This parameter defines the fixed relationship (ratio) between the Proportional (P) and Integral (I) gains for the Yaw axis during the Quicktune process.

Because yaw dynamics are typically much slower and less sensitive than roll or pitch, the integrator gain ($K\_i$) is usually set much lower than the proportional gain. Maintaining this ratio ensures that Quicktune doesn't over-power the yaw integrator, which could lead to slow, oscillating "wagging" of the tail.

The Mathematics

During the tuning process, whenever Quicktune adjusts the Yaw P gain ($K\_{p\_yaw}$), it automatically calculates the new Yaw I gain ($K\_{i\_yaw}$) using this ratio ($\gamma\_{yaw}$):

$$ K\_{i\_yaw} = \frac{K\_{p\_yaw}}{\gamma\_{yaw}} $$

Where $\gamma\_{yaw}$ is QWIK_Y_PI_RATIO.

For example, with the default ratio of 10.0, if Quicktune finds an optimal Yaw P of 0.5, it will automatically set the Yaw I to 0.05.

The Engineer's View

In AP_Quicktune::adjust_gain() (libraries/AP_Quicktune/AP_Quicktune.cpp):

1. The code identifies when the Yaw axis P gain is being modified.
2. It checks for FeedForward (FF). If FF > 0, the integrator is typically handled independently of P, and this ratio is bypassed.
3. Otherwise, it applies the y_pi_ratio specifically.
4. This high default value (10.0 vs 1.0 for roll/pitch) reflects the engineering reality that Yaw requires a much wider gap between instantaneous response (P) and long-term error correction (I) to remain stable on most airframes.

Tuning & Behavior

• Default Value: 10.0.
• Range: 1.0 to 20.0.
• Effect of Increasing: Results in a much lower relative I gain for yaw. Recommended for vehicles that "tail-wag" or feel nervous in the yaw axis.
• Effect of Decreasing: Results in a higher relative I gain. Only recommended if the vehicle fails to hold its heading against constant torque or wind.