From e172f870911a4ac244f89b507fc406ee0850cbb3 Mon Sep 17 00:00:00 2001 From: Ray Morris Date: Tue, 30 Jun 2026 21:03:18 -0500 Subject: [PATCH 1/2] docs(autotune): fix fixed-wing autotune docs to match actual behavior Roll/pitch/yaw rates are described as a fixed ceiling autotune respects; in reality, with the default fw_autotune_rate_adjustment setting, autotune actively rewrites roll_rate/pitch_rate/yaw_rate while flying. The doc also claimed autotune sets P and I gains, which hasn't been true since gain the P/I/D-from-FF formula was removed in 2021. Neither yaw nor the MANUAL-mode no-op were mentioned. Rewrites the pre-flight parameter table and flying instructions to describe what the code actually does: FeedForward is tuned on all three axes, P/I are never touched, rate tuning depends on flight mode and fw_autotune_rate_adjustment, and AUTOTUNE has no effect at all in MANUAL mode. --- docs/Autotune - fixedwing.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/Autotune - fixedwing.md b/docs/Autotune - fixedwing.md index 3579e8e58d9..ff9fc11c709 100755 --- a/docs/Autotune - fixedwing.md +++ b/docs/Autotune - fixedwing.md @@ -6,9 +6,14 @@ Getting a good set of roll/pitch/yaw PIFF parameters for your aircraft is essent ## What AUTOTUNE does -The AUTOTUNE mode is a flight mode that acts on top of normal ANGLE/HORIZON/ACRO mode and uses changes in flight attitude input by the pilot to learn the tuning values for roll, pitch and yaw tuning. +AUTOTUNE is a modifier you enable on top of ANGLE, HORIZON or ACRO mode. It has no effect at all while flying in MANUAL mode - you can switch it on, but nothing will be tuned until you leave MANUAL. Where it is active, it uses the aircraft's response to your stick inputs to tune, for roll, pitch and yaw independently: -In general pilot needs to activate AUTOTUNE mode while in the air and then fly the plane for a few minutes. While flying the pilot needs to input as many sharp attitude changes as possible so that the autotune code can learn how the aircraft responds and figure out PIFF gains. +* **FeedForward (FF) gain** - in ANGLE, HORIZON or ACRO, whenever you give it enough hard stick input to learn from +* **Rate** (`roll_rate`/`pitch_rate`/`yaw_rate`) - only while flying in ACRO or HORIZON, and only if `fw_autotune_rate_adjustment` is not set to `FIXED` (see below). Rate is never adjusted while flying in ANGLE mode. + +**AUTOTUNE never adjusts P or I gains, on any axis.** Tune P and I manually, either before or after using AUTOTUNE. This is a change from older INAV versions - if you're used to AUTOTUNE also setting P/I, that's no longer how it works. + +In general the pilot needs to activate AUTOTUNE while in the air and then fly the plane for a few minutes. While flying the pilot needs to input as many sharp attitude changes as possible, on all three axes, so that the autotune code can learn how the aircraft responds. An axis that isn't given hard stick input won't be tuned - it's easy to spend a whole flight on hard rolls and pitches and forget yaw entirely. ## Before flying with AUTOTUNE @@ -16,9 +21,12 @@ Before taking off you need to set up a few parameters for your airplane: parameter | explanation --------- | ----------- -roll_rate | Maximum roll rate limit for your ariplane. Must not exceed physical limit of your plane -pitch_rate | Maximum pitch rate limit for your ariplane. Must not exceed physical limit of your plane -yaw_rate | Maximum yaw rate limit for your ariplane. Must not exceed physical limit of your plane +roll_rate | Starting roll rate for your airplane. Unless you set `fw_autotune_rate_adjustment` to `FIXED` (see below), AUTOTUNE will change this value while you fly - it's a starting point, not a ceiling it respects +pitch_rate | Starting pitch rate for your airplane. Same caveat as `roll_rate` +yaw_rate | Starting yaw rate for your airplane. Same caveat as `roll_rate` +fw_autotune_rate_adjustment | Controls whether/how AUTOTUNE changes `roll_rate`/`pitch_rate`/`yaw_rate` while tuning. `AUTO` (default) raises or lowers rates to match what the plane can achieve. `LIMIT` only ever lowers them, never above what you started with. `FIXED` leaves rates untouched - use this if you want AUTOTUNE to tune FeedForward only +fw_autotune_min_stick | Minimum stick deflection [%] (default 50) before AUTOTUNE starts recording a maneuver as tuning data +fw_autotune_max_rate_deflection | Target servo/mixer deflection [%] (default 90) AUTOTUNE aims for when calculating an achievable rate in `AUTO`/`LIMIT` fw_p_level | Self-leveling strength. Bigger value means sharper response fw_i_level | Self-leveling filtering. Usual value for airplanes is 1-5 Hz max_angle_inclination_rll | Maximum roll angle in [0.1 deg] units @@ -26,7 +34,7 @@ max_angle_inclination_pit | Maximum pitch angle in [0.1 deg] units tpa_breakpoint | Cruise throttle (expected throttle that you would be flying most of the time) tpa_rate | Amount of TPS curve to apply (usually should be in range 50-80 for most airplanes) -For most hobby-sized airplanes roll/pitch rate limits should be in range 70-120 deg/s (7-12 for `roll_rate` and `pitch_rate` values). Small and agile flying wings can reach 180-200 deg/s. +For most hobby-sized airplanes, starting roll/pitch rates in the range 70-120 deg/s (7-12 for `roll_rate` and `pitch_rate` values) work well. Small and agile flying wings can reach 180-200 deg/s. With the default `AUTO` setting, don't worry about getting this exactly right - AUTOTUNE will adjust it based on what your airplane actually does, down to a floor of 40 deg/s on roll/pitch and 10 deg/s on yaw, up to a ceiling of 720 deg/s. Other things to check: @@ -38,15 +46,16 @@ Other things to check: Once you are all setup you can take off normally and switch to AUTOTUNE mode once you have gained altitude. -When you engage AUTOTUNE mode a few things will happen: +When you engage AUTOTUNE a few things will happen: -* The autotune system will immediately setup some default values for your roll, pitch and yaw P and I gains -* The autotune system will monitor requested roll and pitch rates (as determined by your transmitter stick movements). When the demanded roll or pitch rate exceeds certain threshold the autotune system will use the response of the aircraft to learn roll or pitch tuning values -* Every 5 seconds the autotune system will store the snapshot of parameters you have. When you switch out of AUTOTUNE mode the last remembered parameters are restored +* The autotune system will monitor requested roll, pitch and yaw rates (as determined by your transmitter stick movements, once deflection passes `fw_autotune_min_stick`). When the demanded rate on an axis exceeds that threshold the autotune system will use the response of the aircraft to learn FeedForward (and, depending on `fw_autotune_rate_adjustment` and mode, Rate) for that axis +* Every 5 seconds the autotune system will store a snapshot of the current values. When you switch out of AUTOTUNE the last snapshot is restored - so if you exit within 5 seconds of enabling it, nothing changes * You may find the plane is quite sluggish when you first enter AUTOTUNE. You will find that as the tune progresses this will get better. Make sure your flight area has plenty of room for slow large-radius turns. * Don't land in AUTOTUNE mode - during landing airplane doesn't reach it full performance which may be read by autotune system as insufficient gains. -The key to a successful autotune is to input rapid movements with the transmitter sticks. You should only do one of either roll or pitch at a time, and you should move the stick rapidly to the maximum deflection. +The key to a successful autotune is to input rapid movements with the transmitter sticks. You should only exercise one of roll, pitch or yaw at a time, and you should move the stick rapidly to the maximum deflection. Don't neglect yaw - it's easy to spend the whole flight on rolls and pitches and leave yaw untuned. + +Fly in ACRO if you can - AUTOTUNE only learns Rate in modes where stick position maps directly to a commanded rotation rate (ACRO, and mostly HORIZON). In ANGLE mode the stick commands an angle instead, so AUTOTUNE will still tune FeedForward but will not touch Rate at all while you're in ANGLE. AUTOTUNE has no effect whatsoever in MANUAL mode - don't fly it there. ## Don't stop too early From f3527febd2a7c633df22c3b7937e46b26af73c07 Mon Sep 17 00:00:00 2001 From: Ray Morris Date: Thu, 2 Jul 2026 13:10:45 -0500 Subject: [PATCH 2/2] docs(autotune): fix LIMIT mode wording per Qodo review LIMIT caps rates at the starting value but isn't strictly monotonic downward - it can raise a previously-lowered rate back up toward that ceiling. --- docs/Autotune - fixedwing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Autotune - fixedwing.md b/docs/Autotune - fixedwing.md index ff9fc11c709..75391ccc8ed 100755 --- a/docs/Autotune - fixedwing.md +++ b/docs/Autotune - fixedwing.md @@ -24,7 +24,7 @@ parameter | explanation roll_rate | Starting roll rate for your airplane. Unless you set `fw_autotune_rate_adjustment` to `FIXED` (see below), AUTOTUNE will change this value while you fly - it's a starting point, not a ceiling it respects pitch_rate | Starting pitch rate for your airplane. Same caveat as `roll_rate` yaw_rate | Starting yaw rate for your airplane. Same caveat as `roll_rate` -fw_autotune_rate_adjustment | Controls whether/how AUTOTUNE changes `roll_rate`/`pitch_rate`/`yaw_rate` while tuning. `AUTO` (default) raises or lowers rates to match what the plane can achieve. `LIMIT` only ever lowers them, never above what you started with. `FIXED` leaves rates untouched - use this if you want AUTOTUNE to tune FeedForward only +fw_autotune_rate_adjustment | Controls whether/how AUTOTUNE changes `roll_rate`/`pitch_rate`/`yaw_rate` while tuning. `AUTO` (default) raises or lowers rates to match what the plane can achieve. `LIMIT` adjusts rates the same way but caps them at your starting value - it can still raise a rate it previously lowered, just never above where you started. `FIXED` leaves rates untouched - use this if you want AUTOTUNE to tune FeedForward only fw_autotune_min_stick | Minimum stick deflection [%] (default 50) before AUTOTUNE starts recording a maneuver as tuning data fw_autotune_max_rate_deflection | Target servo/mixer deflection [%] (default 90) AUTOTUNE aims for when calculating an achievable rate in `AUTO`/`LIMIT` fw_p_level | Self-leveling strength. Bigger value means sharper response