docs(autotune): fix fixed-wing autotune docs to match actual behavior

[sensei-hacker]

Summary

The fixed-wing AUTOTUNE documentation no longer matched the current implementation in src/main/flight/pid_autotune.c. A user reported confusion after their rates changed significantly during an AUTOTUNE flight, which they didn't expect based on the docs.

Changes

• Corrected the pre-flight parameter table: roll_rate/pitch_rate/yaw_rate are described as fixed limits AUTOTUNE respects, but by default (fw_autotune_rate_adjustment = AUTO) AUTOTUNE actively rewrites them while flying. Documented all three fw_autotune_* settings that control this.
• Removed the claim that AUTOTUNE sets P and I gains - that formula (P/I/D derived from FF) was removed from the code in 2021 (9dcf985b0c, "Don't change P, I and D during autotune"). AUTOTUNE only ever tunes FeedForward gain and, conditionally, rate.
• Added yaw to the flying instructions - the code tunes yaw identically to roll/pitch (own FF, own rate, own minimum rate floor), but the doc only described roll/pitch maneuvers.
• Documented the flight-mode dependency: rate is tuned in ACRO/HORIZON but not ANGLE mode (FF still is), and AUTOTUNE has no effect at all - not even FeedForward - while flying in MANUAL mode (pid.c:881).

Testing

Documentation-only change; no firmware behavior changed, so no build/SITL testing applies. Every factual claim was checked directly against the source:

• src/main/flight/pid_autotune.c (core tuning logic, rate/FF update conditions, min/max rate constants)
• src/main/flight/pid.c (pidApplyFixedWingRateController, HORIZON-mode rate blending)
• src/main/fc/fc_core.c (ANGLE_MODE/HORIZON_MODE/MANUAL_MODE flag semantics)
• src/main/fc/settings.yaml (fw_autotune_rate_adjustment, fw_autotune_min_stick, fw_autotune_max_rate_deflection defaults and valid values)

Code Review

Reviewed with the inav-code-review agent, used specifically to independently verify every claim in this doc against the code above. It caught one real error in a companion wiki doc (AUTOTUNE incorrectly described as active in MANUAL mode) before this was opened; that's fixed in the companion inavwiki PR.

Related

Companion doc fix in the inavwiki repo (AUTOTUNE section of Modes.md) covers the same inaccuracies for the wiki's mode reference page.

[qodo-code-review]

PR Summary by Qodo

Fix fixed-wing AUTOTUNE docs to match current firmware behavior

📝 Documentation 🕐 10-20 Minutes

AI Description

• Clarify AUTOTUNE tunes FF always, and rate only in ACRO/HORIZON
• Correct pre-flight parameters: rates are starting points unless rate adjustment is FIXED
• Document MANUAL-mode no-op and include yaw maneuvers in flight instructions

Diagram

graph TD
  P[Pilot] --> D["Autotune - fixedwing.md"] --> M[AUTOTUNE modifier] --> L[PID autotune logic]
  M --> S[Settings/params]
  S --> R[Rate & FF updates]
  L --> R

  subgraph Legend
    direction LR
    _usr[Pilot] ~~~ _doc[Documentation] ~~~ _mod[Mode/feature] ~~~ _cfg[Configuration] ~~~ _logic[Logic]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Auto-generate parameter table from settings metadata

• ➕ Reduces drift between docs and defaults/valid values
• ➕ Makes future parameter additions/renames harder to miss
• ➖ Requires tooling and a doc generation pipeline
• ➖ Does not cover behavioral/mode-gating narrative text

2. Add firmware-side, versioned behavior notes and link from docs

• ➕ Clearly communicates behavior changes across releases (e.g., P/I no longer tuned)
• ➕ Gives users a canonical source tied to code version
• ➖ Adds ongoing maintenance overhead to keep notes current
• ➖ Doesn’t prevent doc text from drifting if not enforced

3. Add a lightweight doc validation checklist in CI

• ➕ Encourages verifying docs against source during code changes
• ➕ Can catch obvious contradictions early (e.g., MANUAL-mode no-op)
• ➖ Hard to automate semantic correctness beyond simple assertions
• ➖ May add process friction without strong signal

Recommendation: The PR’s approach (directly correcting the narrative to match current implementation) is the right immediate fix for user confusion. If this area continues to churn, consider auto-generating the parameter/defaults table from settings metadata to prevent future drift, while keeping the higher-level behavioral guidance manual and version-aware.

Files changed (1) +20 / -11

Documentation (1) +20 / -11

Autotune - fixedwing.mdAlign fixed-wing AUTOTUNE behavior docs with current tuning logic +20/-11

Align fixed-wing AUTOTUNE behavior docs with current tuning logic

• Rewrites the AUTOTUNE behavior description to reflect current firmware: FF is tuned on all axes when stick input is sufficient, rate changes are conditional (ACRO/HORIZON and non-FIXED adjustment), and MANUAL mode is a no-op. Updates the pre-flight parameter table to clarify that roll/pitch/yaw rates are starting points (unless FIXED) and documents the fw_autotune_* settings, plus adds yaw maneuvers and mode-specific flying guidance.

docs/Autotune - fixedwing.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Rate-mode docs mismatch 🐞 Bug ≡ Correctness

Description

The docs state rate (roll_rate/pitch_rate/yaw_rate) is only tuned in ACRO/HORIZON, but the
implementation updates rates in any non-ANGLE mode (including ANGLEHOLD) when
fw_autotune_rate_adjustment != FIXED, so users can still have rates adjusted outside ACRO/HORIZON.

Code

docs/Autotune - fixedwing.md[R11-13]

+* **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.
+

Evidence

Rate adjustment is gated by !FLIGHT_MODE(ANGLE_MODE) (not by ACRO/HORIZON), and ANGLEHOLD is a
distinct flight mode that does not set ANGLE_MODE, so AUTOTUNE can still update rates there when
active.

src/main/flight/pid_autotune.c[189-224]
src/main/fc/fc_core.c[686-699]
src/main/flight/pid.c[1276-1296]
src/main/flight/pid.c[880-883]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The documentation claims that AUTOTUNE rate adjustment happens only in ACRO/HORIZON, but the firmware gates rate adjustment only on `!ANGLE_MODE` (and not MANUAL). This makes the docs inaccurate for modes like `ANGLEHOLD_MODE`.

### Issue Context
- `autotuneFixedWingUpdate()` adjusts rates whenever `fw_rate_adjustment != FIXED` and `!FLIGHT_MODE(ANGLE_MODE)`.
- `ANGLEHOLD_MODE` is enabled separately from `ANGLE_MODE`, so rate adjustment can occur while flying in ANGLEHOLD.

### Fix Focus Areas
- docs/Autotune - fixedwing.md[11-13]
- docs/Autotune - fixedwing.md[56-58]

Suggested doc direction:
- Replace “only in ACRO/HORIZON” with “in any non-ANGLE mode” (and still recommend ACRO/HORIZON for best results), or explicitly mention ANGLEHOLD as also allowing rate changes.
- Keep the “no effect in MANUAL” statement.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Rate-mode docs mismatch 🐞 Bug ≡ Correctness

The docs state rate (roll_rate/pitch_rate/yaw_rate) is only tuned in ACRO/HORIZON, but the
implementation updates rates in any non-ANGLE mode (including ANGLEHOLD) when
fw_autotune_rate_adjustment != FIXED, so users can still have rates adjusted outside ACRO/HORIZON.

Agent Prompt

### Issue description
The documentation claims that AUTOTUNE rate adjustment happens only in ACRO/HORIZON, but the firmware gates rate adjustment only on `!ANGLE_MODE` (and not MANUAL). This makes the docs inaccurate for modes like `ANGLEHOLD_MODE`.

### Issue Context
- `autotuneFixedWingUpdate()` adjusts rates whenever `fw_rate_adjustment != FIXED` and `!FLIGHT_MODE(ANGLE_MODE)`.
- `ANGLEHOLD_MODE` is enabled separately from `ANGLE_MODE`, so rate adjustment can occur while flying in ANGLEHOLD.

### Fix Focus Areas
- docs/Autotune - fixedwing.md[11-13]
- docs/Autotune - fixedwing.md[56-58]

Suggested doc direction:
- Replace “only in ACRO/HORIZON” with “in any non-ANGLE mode” (and still recommend ACRO/HORIZON for best results), or explicitly mention ANGLEHOLD as also allowing rate changes.
- Keep the “no effect in MANUAL” statement.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools