Propose automatic fixed-wing tuning with a model-fitting prototype

[Raffi1202]

Fixed-wing setup currently requires separate servo trim, autotune and level-trim workflows. This PR proposes one automatic sequence for INAV 10.x, with roll/pitch as the default axes for flying wings, and adds an isolated numerical prototype for reviewing the identification approach.

Included

• An implementation proposal covering phase ownership, flight-path containment, pilot/failsafe preemption, parameter rollback/persistence, rate and attitude tuning, and optional speed/altitude/throttle stages.
• A second-order discrete plant estimator with a constant trim offset, incremental QR fitting, basic conditioning/stability/static-gain checks, and free-running validation against held-out observations.

The prototype is not connected to the flight controller. There is no new flight mode, automatic manoeuvre, gain synthesis, gain change or settings write in this PR. Oscillation compression and navigation tuning are design requirements, not implemented features. Existing firmware behaviour is unchanged.

Existing work

The proposal records related INAV work, including #7461 (removing PID gains derived from FF), #7056 (acceleration discovery), and #11042 / #11222 (airspeed attenuation). Searches of open/closed autotune work and open automatic-sequence/chirp work did not find an equivalent combined sequence. This is separate from the multirotor measurement work in #12010.

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Propose automatic fixed-wing tuning and plant model prototype

✨ Enhancement 📝 Documentation 🧪 Tests 🕐 40+ Minutes

AI Description

• Proposes one preemptible fixed-wing commissioning sequence with transactional rollback and
 explicit validation gates.
• Adds an isolated second-order plant estimator using incremental QR and trim-offset fitting.
• Validates stability, gain, conditioning, and held-out prediction without changing flight behavior.

Diagram

graph TD
  P["Pilot Safety"] -->|preempts| A["Flight Adapter"] --> S["Tune Sequence"] --> E["Plant Estimator"]
  N["Nav Containment"] -->|bounds tests| A
  E -.->|future model| C["Gain Design"] -.-> T["Parameter Transaction"]
  S -.->|owns candidates| T

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Offline batch SVD fitting

• ➕ Provides stronger singular-value and rank diagnostics
• ➕ Can serve as an independent reference implementation
• ➖ Requires storing complete observation sets
• ➖ Uses more memory and computation than the incremental embedded approach
• ➖ Does not directly support eventual onboard streaming

2. Recursive least squares

• ➕ Naturally supports streaming updates and optional forgetting
• ➕ Can track operating-point changes during a flight
• ➖ Requires covariance initialization and forgetting-factor tuning
• ➖ Can be more sensitive to weak excitation and numerical drift
• ➖ Adds adaptation behavior that complicates deterministic acceptance

3. Adapt an existing autopilot tuner

• ➕ Reuses field-tested identification and synthesis concepts
• ➕ Could reduce algorithm-design effort
• ➖ PX4 and ArduPilot controller structures and parameter units differ from INAV
• ➖ Existing algorithms do not directly cover the proposed combined trim and persistence workflow
• ➖ Adaptation still requires INAV-specific signal-path and safety validation

Recommendation: Keep the isolated incremental-QR prototype as the initial embedded estimator: it provides bounded memory and better conditioning than normal equations without prematurely coupling model fitting to flight control. Use an offline batch SVD implementation as a test oracle, and defer recursive adaptation or imported gain synthesis until INAV-specific controller and signal-path requirements are validated.

Files changed (5) +796 / -0

Enhancement (2) +263 / -0

fw_tune_model.cImplement incremental fixed-wing plant identification and validation +202/-0

Implement incremental fixed-wing plant identification and validation

• Implements a second-order discrete plant estimator with a constant observation offset using incremental QR decomposition. Rejects invalid, under-excited, unstable, reversed-gain, or poorly conditioned models and computes free-running held-out prediction error.

src/main/flight/fw_tune_model.c

fw_tune_model.hExpose fixed-wing plant model fitting interfaces +61/-0

Expose fixed-wing plant model fitting interfaces

• Defines model, fitting, prediction-state, and validation structures. Exposes APIs for sample ingestion, solving, stability and static-gain checks, prediction, and held-out error calculation.

src/main/flight/fw_tune_model.h

Tests (1) +206 / -0

fw_tune_model_unittest.ccTest plant identification, rejection, and held-out validation +206/-0

Test plant identification, rejection, and held-out validation

• Exercises identification against an independently simulated continuous-time plant, trim-offset handling, static gain, prediction, and validation. Covers insufficient excitation, invalid samples and periods, instability, reversed response, wrong gain, long delay, and invariant failure behavior.

src/test/unit/fw_tune_model_unittest.cc

Documentation (1) +325 / -0

fixed-wing-automatic-tuning.mdDefine the automatic fixed-wing tuning architecture and safety gates +325/-0

Define the automatic fixed-wing tuning architecture and safety gates

• Documents a one-switch commissioning workflow covering trim, roll/pitch identification, rate and attitude tuning, validation, and optional navigation stages. Specifies session ownership, containment, preemption, transactional persistence, supported airframes, and evidence required before flight enablement.

docs/development/fixed-wing-automatic-tuning.md

Other (1) +2 / -0

CMakeLists.txtRegister the fixed-wing model implementation with unit tests +2/-0

Register the fixed-wing model implementation with unit tests

• Adds the estimator source dependency for the new fixed-wing tuning model test target.

src/test/unit/CMakeLists.txt

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can route each action level your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[github-actions]

Test firmware build ready — commit a14677c

Download firmware for PR #12013

250 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.

[github-actions]

RAM / Flash usage vs. base commit 86a0441 — commit a14677c

Target	Flash Δ	RAM Δ
MATEKF405	±0 B (±0.00%)	CCM: ±0 B (±0.00%) RAM: ±0 B (±0.00%)
MATEKF722	±0 B (±0.00%)	ITCM_RAM: ±0 B (±0.00%) RAM: ±0 B (±0.00%) TCM: ±0 B (±0.00%)
MATEKF765	±0 B (±0.00%)	DTCM_RAM: ±0 B (±0.00%) SRAM1: ±0 B (±0.00%)
MATEKH743	±0 B (±0.00%)	D2_RAM: ±0 B (±0.00%) DTCM_RAM: ±0 B (±0.00%) ITCM_RAM: ±0 B (±0.00%) RAM: ±0 B (±0.00%)

See RAM/flash optimization guide for techniques to reduce usage.

[b14ckyy]

Thanks for putting this much thought into fixed-wing tuning — it's a topic worth discussing!

However, this isn't really a pull request in its current form: the estimator isn't built into the firmware (it's only linked into the unit test), and the design document describes requirements rather than an implementation. The key parts — excitation method, gain synthesis and acceptance thresholds — are still open. Adding unused code to src/main would only create maintenance overhead.

I'd suggest the following:

1. Move the proposal to a GitHub Discussion (or a feature request issue) so the approach can be discussed with other developers before code is written. I'll close this PR for now.
2. When submitting the estimator later as step 1 of your roadmap, please target maintenance-11.x (10.x is in feature freeze since 2026-09-22) and include replay tests against real Blackbox logs, not only synthetic plants.
3. Please address closed-loop identification bias explicitly. Least-squares ARX on closed-loop data with noise gives biased estimates unless the excitation is used as an instrument or reference.

Since you've opened several larger feature PRs recently, it would help to briefly align on scope with the maintainers (e.g. on Discord in a Thread or in a Discussion on GH) before investing a lot of implementation time. That saves effort on both sides.

Thanks again, and looking forward to the discussion!