(WIP) Implement auto vtol smooth transition state

[mart1npetroff]

PR #11553 Summary: Smooth VTOL Auto-Transition Controller

This PR adds a smooth VTOL transition controller for aircraft that switch between a fixed-wing mixer profile and a multicopter mixer profile.

Please use latest docs version and specially docs/VTOL.md for main guideline for setup and testing.

The description bellow could be outdated and could contain obsolete settings from old PR commits.

The goal is to keep the existing VTOL mixer-profile workflow usable, while making transitions less abrupt, more airspeed-aware, and safer during both manual and mission-triggered operation.

At a high level, this PR adds:

• optional edge-triggered auto VTOL transitions;
• mission-authorized VTOL transitions using waypoint USER action bits;
• airspeed-first MC->FW transition completion when trusted pitot data is available;
• timer fallback when pitot is unavailable or unhealthy;
• configurable airspeed-timeout abort handling;
• optional dynamic transition scaling for pusher/lift/MC authority/FW authority;
• optional low-speed FW->MC protection;
• mission MC->FW retry logic after airspeed-timeout aborts;
• configurable transition fail actions;
• target fixed-wing stabilized servo preview before profile hot-switch;
• debug support for transition state inspection;
• USE_AUTO_TRANSITION gating so smaller flash targets can keep the pre-existing transition behavior.

This PR does not implement target fixed-wing throttle preview or tilt-motor propulsion blending. Pusher throttle during transition still uses the existing transition pusher throttle convention from the MC mixer profile but with dynamic scaling.

---

Legacy behavior vs current PR behavior

In this summary, “legacy” means the behavior that existed before this PR.

Before this PR:

• MIXER PROFILE 2 directly selected mixer profile 2 while active.

• The default mixer profile was profile 1.

• Existing VTOL examples commonly used:

  • Profile 1 = fixed-wing / FW
  • Profile 2 = multicopter / MC

• MIXER TRANSITION was used as a transition-mixing input, typically overlapping with MIXER PROFILE 2 in the middle switch position.

• A common switch layout was:

  • FW
  • MC + transition
  • MC

With this PR, when the new auto-transition controller is enabled, MIXER TRANSITION becomes an edge-triggered transition request. The transition controller decides the direction from the current active profile and performs the profile hot-switch when the transition completes.

When the auto-transition controller is disabled, manual transition should keep the pre-existing behavior.

---

Example switch topology

This PR should support the long-standing VTOL profile order and overlap-style switch topology used by existing VTOL examples:

Profile 1 = FW
Profile 2 = MC

Example 3-position switch:

Position 1: FW stable mode
  MIXER PROFILE 2 = OFF
  MIXER TRANSITION = OFF

Position 2: transition request / transition mix
  MIXER PROFILE 2 = ON
  MIXER TRANSITION = ON

Position 3: MC stable mode
  MIXER PROFILE 2 = ON
  MIXER TRANSITION = OFF

The important part is the middle position:

Position 2 overlaps:
  MIXER PROFILE 2
  +
  MIXER TRANSITION

With the new auto-transition controller enabled, MIXER TRANSITION is treated as a transition request edge. The controller determines the transition direction from the current active profile:

If currently MC:
  MIXER TRANSITION rising edge requests MC->FW.

If currently FW:
  MIXER TRANSITION rising edge requests FW->MC.

During an active auto transition session, the transition controller temporarily owns the profile-switch decision. This prevents the direct MIXER PROFILE 2 path from immediately overriding the requested smooth transition while the transition is still active.

---

Example: FW->MC using the overlap topology

Start in Position 1:
  Profile 1 / FW
  MIXER PROFILE 2 = OFF
  MIXER TRANSITION = OFF

Move to Position 2:
  MIXER PROFILE 2 = ON
  MIXER TRANSITION = ON

The transition controller sees MIXER TRANSITION rising edge while currently in FW.
It starts a smooth FW->MC transition.
When the transition completes, it hot-switches to MC / Profile 2.

Move to Position 3:
  MIXER PROFILE 2 = ON
  MIXER TRANSITION = OFF

The aircraft remains in MC stable mode.

---

Example: MC->FW using the overlap topology

Start in Position 3:
  Profile 2 / MC
  MIXER PROFILE 2 = ON
  MIXER TRANSITION = OFF

Move to Position 2:
  MIXER PROFILE 2 = ON
  MIXER TRANSITION = ON

The transition controller sees MIXER TRANSITION rising edge while currently in MC.
It starts a smooth MC->FW transition.
When the transition completes, it hot-switches to FW / Profile 1.

Move to Position 1:
  MIXER PROFILE 2 = OFF
  MIXER TRANSITION = OFF

The aircraft remains in FW stable mode.

This overlap topology is important because it matches the established VTOL workflow and user expectations.

---

Automated transition controller

The optional automated controller is enabled with:

mixer_vtol_manualswitch_autotransition_controller = ON

When enabled, auto MIXER TRANSITION becomes edge-triggered:

MIXER TRANSITION OFF -> ON:
  starts one transition request

MIXER TRANSITION ON -> OFF before hot-switch:
  aborts the auto transition request

A new transition request requires:
  OFF -> ON again

The setting should be enabled in both mixer profiles used for VTOL switching.

The controller has a session latch so that the transition does not unexpectedly change behavior immediately after the profile hot-switch. This matters because mixer settings are profile-specific, but an active transition session must remain consistent across the source and destination profiles.

---

Direct profile switching vs transition-controller switching

The current PR keeps two separate paths:

MIXER PROFILE 2:
  direct manual profile selection path

MIXER TRANSITION:
  smooth transition-controller request path when auto-transition is enabled

During an active auto transition session, the transition controller owns profile switching.

Outside an active transition session, direct MIXER PROFILE 2 selection remains available.

This distinction is important for the overlap topology. In the middle switch position, both MIXER PROFILE 2 and MIXER TRANSITION can be active. The controller must prevent the direct profile-switch path from immediately defeating the requested smooth transition.

---

Mission-authorized VTOL transitions

This PR adds mission-authorized VTOL transitions through a configured waypoint USER action bit:

nav_vtol_mission_transition_user_action = USER1 / USER2 / USER3 / USER4

The selected USER bit acts as an absolute target selector on each navigable waypoint:

selected USER bit = 0:
  target is MC / MULTIROTOR

selected USER bit = 1:
  target is FW / AIRPLANE

This is not a toggle. It is a per-waypoint target-state declaration.

Example:

Waypoint A:
  USER1 clear
  target = MC

Waypoint B:
  USER1 set
  target = FW

Waypoint C:
  USER1 set
  target = FW
  already in FW, so action is idempotent

Waypoint D:
  USER1 clear
  target = MC

During mission transition, mission progression pauses while the transition is in progress and resumes only after transition completion.

---

Airspeed-first completion

For MC->FW transitions, this PR can use trusted pitot airspeed as the primary completion condition.

Example:

vtol_transition_to_fw_min_airspeed_cm_s = 1400

Behavior:

MC->FW transition starts.
Forward propulsion / transition mixing starts.
If trusted pitot is available, completion waits until the target airspeed is reached.
Only then does the controller hot-switch to the FW profile.

If pitot is unavailable or unhealthy, or the configured threshold is disabled, transition completion falls back to the configured timer path.

The key point is that airspeed is used for transition completion only when trusted pitot data is available.

---

Timer fallback and airspeed timeout

The PR distinguishes between:

mixer_switch_trans_timer

and:

mixer_vtol_transition_airspeed_timeout_ms

They serve different purposes.

mixer_switch_trans_timer is the fallback completion timer. It is used when airspeed-controlled completion is not active.

mixer_vtol_transition_airspeed_timeout_ms is an abort timeout for the airspeed-controlled path. It only applies while the controller is waiting for trusted pitot airspeed to satisfy the transition threshold.

Example:

Trusted pitot available:
  completion waits for airspeed threshold

Airspeed threshold not reached before timeout:
  transition aborts or follows configured failure handling

Pitot unavailable/unhealthy:
  controller uses timer fallback instead

For airspeed-first setups, reviewers should check that the fallback timer is non-zero and reasonable, so pitot-loss fallback does not complete immediately.

---

Dynamic transition scaling

The PR adds optional dynamic scaling:

mixer_vtol_transition_dynamic_mixer = ON

When enabled, transition progress can scale:

forward propulsion / pusher contribution
lift motor contribution
MC stabilization authority
FW stabilization authority
target-FW stabilized servo preview outputs

The current setting names use “min” semantics, for example:

vtol_transition_lift_min_percent
vtol_transition_mc_authority_min_percent
vtol_transition_fw_authority_min_percent

These values should be understood as minimum/floor authority values.

Example:

MC->FW:
  FW authority starts at its configured minimum and ramps toward 100%.

FW->MC:
  FW authority starts at 100% and fades down toward its configured minimum.

The optional scale ramp timer controls the ramping of transition scaling independently from airspeed completion. For example, forward propulsion can ramp in quickly while the final MC->FW hot-switch still waits for airspeed.

---

Target fixed-wing stabilized servo preview

The PR adds new servo input sources:

INPUT_AUTOTRANSITION_TARGET_STABILIZED_ROLL
INPUT_AUTOTRANSITION_TARGET_STABILIZED_PITCH
INPUT_AUTOTRANSITION_TARGET_STABILIZED_YAW

These are intended for fixed-wing control surfaces that should become active during MC->FW transition before the actual profile hot-switch.

Example:

MC profile:
  elevator servo rule uses INPUT_AUTOTRANSITION_TARGET_STABILIZED_PITCH

During MC->FW:
  the elevator starts receiving a target-FW pitch stabilization preview
  the output is scaled by FW authority
  the eventual hot-switch to FW should have less servo discontinuity

For FW->MC, matching FW stabilized authority fades down instead of being removed abruptly.

This preview is intended to approximate the target FW control behavior closely enough for a smoother transition.

---

Tilt servos and transition geometry

Tilt servos, nacelles, and other mechanical transition geometry should continue to use:

INPUT_MIXER_TRANSITION

This is the transition-progress input.

Example:

MC->FW:
  INPUT_MIXER_TRANSITION moves from MC position toward FW position
  tilt servos move motors/nacelles forward

FW->MC:
  INPUT_MIXER_TRANSITION moves back toward MC position
  tilt servos move motors/nacelles vertical

The new INPUT_AUTOTRANSITION_TARGET_STABILIZED_* inputs are not for tilt geometry. They are for stabilized fixed-wing control outputs such as elevator, aileron, or rudder-like surfaces.

---

Pusher throttle behavior

This PR keeps the existing transition pusher throttle model.

Dedicated transition pusher behavior still uses the existing MC mixer throttle convention but adds dynamic scaling , for example:

throttle value between -1 and -2

This PR does not add:

target-FW throttle preview
tilt-motor propulsion blending

Those features are intentionally out of scope for this PR because PR is big enough so far and they require mixer Configurator UI changes.

Future work could add explicit target-FW propulsion preview:

Dedicated pusher:
  target FW throttle output * transition propulsion scale

Tilt motor:
  MC lift/control contribution
  +
  target FW propulsion contribution

But that will be a separate PR later. Current testing with pusher VTOL is giving great results even with throttle value between -1 and -2 in mixer.

---

Low-speed FW->MC protection

The PR adds optional low-speed FW->MC protection:

vtol_fw_to_mc_auto_switch_airspeed_cm_s

When configured, if the aircraft is in FW mode, valid pitot is available, and airspeed drops below the configured threshold, the controller can request a smooth FW->MC transition automatically.

Example:

Aircraft is flying in FW profile.
Airspeed drops below configured threshold.
Controller starts FW->MC transition.
When complete, it switches to MC profile.
A latch prevents direct MIXER PROFILE 2 state from immediately forcing the aircraft back into FW.
Pilot must make a deliberate switch action to resume normal profile selection.

This latch is important for the overlap topology, because the RC switch may still physically indicate the previous stable profile position when the protection transition completes.

---

Mission MC->FW retry and fail actions

The PR adds configurable retry behavior for mission MC->FW transitions that abort due to airspeed timeout.

Example:

Mission requests MC->FW.
Transition starts.
Airspeed threshold is not reached before timeout.
Transition aborts.
If retry is enabled and pitot is valid, aircraft performs a heading scan.
The controller samples trusted pitot airspeed during the scan.
Best heading is selected.
One retry is attempted.
If retry fails, configured fail action is executed.

The retry scan includes safeguards:

valid pitot required
trusted airspeed sample required
per-heading-step timeout
overall retry scan timeout
no infinite yaw-scan hang

Fail actions are configurable separately for MC->FW and FW->MC failures. The current PR should ensure that “LOITER” style FW->MC failure behavior maps to a local position-hold style behavior, not an unexpected RTH path.

Those retries and fail actions are implemented mainly to provide stable "PLAN B, C..." in case when automated mission is executing and one of both (lift motors or pusher) fails for some reason (blown motor for example)

---

USE_AUTO_TRANSITION gating

The smooth transition functionality is conditionally compiled behind:

USE_AUTO_TRANSITION

The intended split is:

Targets with enough flash:
  smooth auto-transition features enabled

Small / 512 KB targets:
  pre-existing transition behavior retained
  smooth auto-transition settings hidden/unavailable

Reviewers should verify both build paths:

USE_AUTO_TRANSITION enabled target:
  new controller builds and works

USE_AUTO_TRANSITION disabled target:
  no references to auto-transition-only fields/functions/settings
  pre-existing transition behavior still builds and works

This is one of the most important review areas because the PR adds conditional fields, settings, enums, and code paths.

---

Practical examples

Example 1: Existing overlap-style VTOL switch

Profile 1 = FW
Profile 2 = MC

Switch position 1:
  FW stable
  MIXER PROFILE 2 OFF
  MIXER TRANSITION OFF

Switch position 2:
  transition request
  MIXER PROFILE 2 ON
  MIXER TRANSITION ON

Switch position 3:
  MC stable
  MIXER PROFILE 2 ON
  MIXER TRANSITION OFF

This is the example reviewers should keep in mind when checking auto transition behavior.

Example 2: MC->FW with airspeed-first completion

Start in MC stable position.
Move switch to transition position.
Controller starts MC->FW.
Pusher/transition propulsion ramps in.
Lift/MC/FW authority scales according to configuration.
If trusted pitot is healthy, completion waits for target airspeed.
Controller hot-switches to FW.
Pilot moves switch to FW stable position.

Example 3: FW->MC from the same switch topology

Start in FW stable position.
Move switch to transition position.
Controller starts FW->MC.
FW authority fades down.
MC/lift authority returns.
Controller hot-switches to MC.
Pilot moves switch to MC stable position.

Example 4: Tilt servo transition geometry

Tilt servo rule uses INPUT_MIXER_TRANSITION.

MC->FW:
  tilt servo moves gradually from vertical to forward position.

FW->MC:
  tilt servo moves gradually from forward to vertical position.

Example 5: Target-FW elevator preview

MC profile has an elevator servo rule:
  INPUT_AUTOTRANSITION_TARGET_STABILIZED_PITCH

During MC->FW:
  elevator begins receiving target-FW pitch stabilization preview.
  Output scales with FW authority.
  Hot-switch to FW should produce a smaller servo step.

Out of scope:
Do not expect target-FW throttle preview or tilt-motor propulsion blending in this PR.

[Jetrell]

Thanks for your VTOL contribution to INAV. They will be welcome improvements

I have a couple of questions.

I noticed you have an edge trigger for the transition switch, along with the legacy 3Pos manual method.
I'm wondering if this might be less intuitive for users who are familiar with the legacy 3Pos toggle switch ? Which could cause confusion for those used to the legacy method, but still want to use the airspeed/timer method.

I also noticed your addition of Dynamic Scaling. Of which I like the idea.
However it would seem the timer for the scaling is controlled by mixer_switch_trans_timer. Which would seem to indicate the scaling is ramped over that whole time period.
I thought this could be an issue.. In the example of the 'pusher contribution' on a 4 + 1. If the plane requires 80% throttle to gain a good MC to FW transition speed. And the mixer_switch_trans_timer was set to a reasonable value of 5s. It would mean that 80% throttle would not be reached until right before transition ended, if mixer_switch_trans_airspeed_cm_s wasn't met in that time period.
I would have thought it might be more intuitive for users to have another timer that could be set to a shorter period. To specifically overcome harsh motor startup torque reaction on larger tilt-rotors / 4+1's. Or the short transition instability that occurs between mixer changes, as the plane settles into that flight state.
While leaving mixer_switch_trans_timer as just a transition time backup for mixer_switch_trans_airspeed_cm_s ?

[mart1npetroff]

Great feedback, thank you.

On the 3-position manual method question:

I agree this can be confusing if not documented clearly, so I should clarify it better in the PR/docs. The intent is not to replace legacy behaviour. The edge-triggered manual controller is optional (manual_vtol_transition_controller), and legacy 3-position/manual behaviour remains available when that setting is OFF.

my intention is still to support practical 3-position switch workflow when manual_vtol_transition_controller = ON, not to remove it.
A typical setup can still be:

Position 1: MC
Position 2: Auto Transition
Position 3: FW
When manual_vtol_transition_controller = ON, position 2 is used as a trigger to start the AUTO transition sequence.
In real use, I can fly in MC, move the switch to Transition, let the controller complete the automatic transition, then move the switch to FW after completion. For FW->MC, I do the same in reverse order.

So the goal is to keep familiar switch ergonomics, while making transition execution more deterministic and safer.

On the dynamic scaling timer point: I agree this is a good observation.
Scaling follows airspeed progress when pitot is healthy/available, and falls back to timer-based progress when pitot is unavailable. In fallback cases, using only mixer_switch_trans_timer can make ramp-up too slow for some setups.

I propose an optional separate setting:

vtol_transition_scale_ramp_time_ms

with behavior:

0 (default): keep current behavior (backward compatible)

0: use this timer only for scaling ramp (pusher/lift/authority), while transition completion logic remains unchanged (airspeed-first; mixer_switch_trans_timer still acts as fallback completion timer when pitot is unavailable/unhealthy)
Example:

mixer_switch_trans_timer = 5000 ms
vtol_transition_scale_ramp_time_ms = 1200 ms
This gives:

scaling reaches target levels in about 1.2s (smoother motor startup / less torque step),
completion still waits for airspeed threshold when pitot is healthy,
if pitot is not available, completion fallback still uses the 5s transition timer.
If this direction makes sense to you, I can implement it in a follow-up patch after agreement.

When pitot is healthy/available, transition progress is airspeed-driven (not timer-driven).

• MC -> FW:

  • progress = constrain(airspeed / to_fw_threshold, 0..1)
  • completion condition = airspeed >= to_fw_threshold

• FW -> MC:

  • capture startAirspeed when transition starts
  • progress = constrain((startAirspeed - airspeed) / (startAirspeed - to_mc_threshold), 0..1)
  • completion condition = airspeed <= to_mc_threshold

Dynamic mixer scaling (vtol_transition_dynamic_mixer = ON) uses this progress:

• MC -> FW:

  • pusher scale ramps 0 -> 1
  • lift scale ramps 1 -> vtol_transition_lift_end_percent
  • MC authority ramps 1 -> vtol_transition_mc_authority_end_percent
  • FW authority ramps vtol_transition_fw_authority_start_percent -> 1

• FW -> MC:

  • pusher scale ramps 1 -> 0
  • lift scale ramps vtol_transition_lift_end_percent -> 1
  • MC authority ramps vtol_transition_mc_authority_end_percent -> 1
  • FW authority ramps 1 -> vtol_transition_fw_authority_start_percent

For transition/pusher motors (-2.0 < throttle < -1.0), output is interpolated from idle to target:

motor = idle + (target - idle) * pusherScale

where:

• target = -mixerThrottle * 1000
• idle = throttleRangeMin

[Jetrell]

If this direction makes sense to you, I can implement it in a follow-up patch after agreement.

Position 1: MC
Position 2: Auto Transition
Position 3: FW

vtol_transition_scale_ramp_time_ms = 1200 ms

Yes I agree with both changes you have proposed.

Do you happen to have the RealFlight simulator software to test this with the SITL before an actual flight? I unfortunately don't have it.

[mart1npetroff]

Changes pushed and PR updated.

No I do not have RealFlight on my site right now but while ago I tested some scenarios with X-Plane and Alia 250 eVTOL.
I will provide update and hopfully videos after test flights.

One more question: Currently I'm using one of User Actions in WP (configurable) for target selection in mission. Do you think this is good approach or is it better to use bit 5 (which is currently reserved) from WP's p3 instead?

[github-actions]

Test firmware build ready — commit 3699c17

Download firmware for PR #11553

238 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.

[Jetrell]

I've had a bit of a look through your later commits and the docs you have added. And need to point out a few things.

In keeping with consistency. I noticed you have stated in your Docs, the use of Profile 1 for MC and Profile 2 for FW. While the legacy documentation show it to be the other way around. i.e. Profile 1 for FW and Profile 2 for MC.
I know it can work both ways. However it was originally noted that the VTOL is first a fixedwing aircraft (mixer profile 1). And secondary a multicopter (mixer profile 2).
You quoted in the docs -

Recommended switch topology (explicit):

Does explicit mean it excludes it from working in the legacy way that I mentioned above ?

I have also read through your Documents and Setting descriptions. And I have to say they are not easy to follow.
I don't say this out of criticism. But rather to inform you of how the wording of such a document is of the greatest importance. Because most users just get confused by technical terms. The documentation needs to be in simple layman's terms.
I want to see your work here add benefit to iNAV. Rather than confusing people even more than VTOL setup already does.
One of the biggest issues most people have with Ardupilot VTOL setup, is the complexity. This is why many come here.

I have made a start on rewording your documents for this pull request. And when I have them finished. If you don't mind ? I can post them here to see what you think.
In fact I have been thinking of rewording even some of the older legacy stuff too. Which also confuses some users in places.

I also have a few other function related questions, about your implementation. But I'll ask about that later.

[mart1npetroff]

Thanks, this is very helpful feedback.

You were right on both points.

I had left the newer wording inconsistent with the long-standing VTOL convention used in the older docs. I have now aligned the documentation so it consistently uses:

• Profile 1 = fixed-wing
• Profile 2 = multicopter

I also reworded the switch section. “Recommended switch topology (explicit)” was not meant to imply that other arrangements are unsupported. What I wanted to show was a clear 3-position example. The wording now reflects that more clearly, and it also notes that the firmware can still work with the profiles swapped if someone intentionally sets it up that way.

I also simplified some of the setup wording in the VTOL docs to make it easier to follow for non-technical users.

I agree that VTOL documentation needs to stay as simple and practical as possible, and I’d be happy to incorporate improvements there, including cleanup of older wording where it helps.

Feel free to send the function-related questions too when ready.

[Jetrell]

I also simplified some of the setup wording in the VTOL docs to make it easier to follow for non-technical users.
I agree that VTOL documentation needs to stay as simple and practical as possible, and I’d be happy to incorporate improvements there, including cleanup of older wording where it helps.

That sounds great.
The more you can use direct and simple wording that is applicable to the layman, the better.

Try to think of it from the perspective of someone who has no idea of what your improvements do. Don't assume they understand any of the setting operations, as you do.
Then use simple wording that the average hobbyist will be familiar with... Then expound directly on what that setting does. And don't diverge too much from the topic.

For example. In your setting explanations and docs. Perhaps use a descriptor like RPM speed ramp-up in place of SCALE.
And the name of the device (motor or servo) that is being controlled, in place of a word like AUTHORITY.

I hope that make sense.

[error414]

For 3pos switch you wrote

Position 1: MC
Position 2: Auto Transition
Position 3: FW

So I fly FW (switch position 3), then I decide go to MC. I change switch to pos 2 (auto transition), after while autotransition change profile to MC, but switch is still in pos 2 (auto transition). As I understand with this setup I can fly normaly, but what would happen if I move switch to position 3?

Does it mean direct switching from MC to FW without any transition?

BTW: can I test it on field?

[mart1npetroff]

Does it mean direct switching from MC to FW without any transition?

Yes, this is correct. I made a commit that disabled direct switch to fw if you do not reached target speed, but later after that I decided it is probably better to leave this direct switch as pilot’s decision and reverted this logic.

Currently active modes flags are updated and showing if transition is in progress or if mixer profile 2 is active. This way you could have feedback what is the actual active mode at the moment.
If both transition and mixer profile 2 flags are missing, that means mixer 1 is active at the moment.

So current logic is: doesn’t matter how you configure mixer and which one is MC or FW (pos 1 or pos 3).

When transition is activated with pos 2, then auto transition start doing its job and when finished if it is successful will switch to the opposite mixer. If it is not successful will switch back to the same mixer before you start the transition. You could see current transition state in active modes flags.

And yes, once transition complete its work you have to manually move the switch to the current active mixer position and then you could start transition again…

About test question:
I’m happy to see someone willing to test this. MC->FW transition works but today I found a bug probably I introduced with some of my latest commits where pusher stays active in FW->MC transition and it could not slow down the speed for MC switching.

So probably it is better to wait me little bit to fix this one.

[sensei-hacker]

I've done some more research and analysis and I retract my comment about 0% minimums. That was probably misguided.

More research and analysis convinced me that 20% is a solid value, for a wide range of aircraft. Solid enough that it might make sense to simply use 20% and not ask the user to figure it out.

To work through this, I used an AI to help me dig through several research papers about VTOL transition, along with my standard aerodynamics textbook I have indexed for INAV development. I had a "conversation" with the AI about various things in the research papers and this PR. Specifically I focused on the user settings, the things we'd be asking users to figure out and hopefully set correctly.

I am attaching summary recommendations that came from that interaction.
"vtol-pr11553-changes.md" has the key information directly related to this PR.
I am also attaching a longer form justification for each, "vtol-transition-recommendations.md".

These suggestions may be helpful things to think about. They are by no means authoritative.

That research also produced two other documents that are very much NOT required reading for this PR, but may be interesting if one is interested in this topic. One is notes about VTOL-related things not in scope for this PR, but adjacent VTOL things. Things we might think about for future development. That's vtol-transition-adjacent.md

The other is the VTOL portion of a larger long term goal. I have noticed that we have a very large number of settings, probably over 100, that could be derived from about four facts about the aircraft : weight, wing area (or wing loading), and a couple others. Long term, I'd like to build an expanded auto-tune where INAV measures sensor values to derive key aircraft data such as the wing loading. Given a few key values like that, we could probably derive CORRECT values for 100 different settings, and not have to ask the user to try to figure them all out.
vtol-transition-autotune.md covers the part of that directly related to VTOL transition.

key doc:
vtol-pr11553-changes.md

Extras:
vtol-transition-autotune.md
vtol-transition-recommendations.md
vtol-transition-adjacent.md

[error414]

Thank you for answer. I'm going to test it over weekend.

BTW: I don't have standart VTOL, I have tiltrotor.

[Sibre3]

@mart1npetroff Thanks for the VTOL improvements. I'm glad you have updated the documents. Many settings initially had me confused. And still do a little. But I'm slowly working it out.
I really hope you will add OSD system messages for each state completion? Without them we are guessing if an operation has been successful.

[error414]

I tested it on the bench yesterday, I struggled with weird behaviour,

Servos durring transition from MC + TRANSITION to FW made weird moving. See video. i know that in inav is known bug, if you slow down servo, and change VTOL mode if servo is not end position it makes exactly same weird move. I do not use servo slow down.

Video:
https://youtu.be/dmf__OT1qd0?si=2mpC4AkkUMCvWODB

Config:
INAV_9.1.0_cli_T1_20260609_215849-VTOL-AUTOT.txt

[mart1npetroff]

I tested it on the bench yesterday, I struggled with weird behaviour,

Thank you for your test feedback.
Probably I will get more in deep with this case tomorrow but FW profile has no servo 4/5 rules, so the hot-switch to FW removes the tilt servo command path; that may create a discontinuity unless the FW profile explicitly holds those servos at their final FW position, please try to add servos 4 and 5 in FW profile.

[error414]

In the manual you wrote that for mixer_vtol_transition_dynamic_mixer must be added tail motor to FW profile, with -1 (tuned off). So for new VTOl implementation is needed to have same amount of motors and same amount of servos in both profiles. Am I right?

And I would like to ask you if mixer_vtol_transition_dynamic_mixer = ON works for tiltmotor VTOL as well? I did not test it yet. Does it slow down tilt servos? Does it modify PIDs somehow?

[mart1npetroff]

Yes, mostly correct, but with one important distinction.

For motors, if a motor output must be kept alive during the new dynamic handoff/fade logic, then the destination profile usually needs a corresponding motor entry or placeholder. For example, the manual mentions adding the tail/pusher motor to the other profile as a -1.000 placeholder so the transition code can still address that output during preview/fade.

For servos, it is not strictly required that both profiles have the exact same number of servo rules. However, if a physical servo must keep a defined position across the MC/FW hot-switch, then both profiles should define what that servo should do. Otherwise the command path for that servo can disappear at the profile switch and create a discontinuity.

In your case, servo 4/5 are driven in the MC/TRICOPTER profile by:

STABILIZED_YAW
INPUT_MAX
INPUT_MIXER_TRANSITION

but the FW/AIRPLANE profile has no servo 4/5 rules. So when the transition completes and the FW profile becomes active, those tilt servo rules disappear. That is why I suggested adding servo 4/5 rules in the FW profile to hold them at their final FW position.

About mixer_vtol_transition_dynamic_mixer = ON:

Yes, it should also work for tiltmotor VTOL, but it is important to understand what it does and does not do.

It does not use the normal servo slowdown feature. It does not directly “slow servos” as a generic servo filter. Instead, when dynamic mixer is enabled, the transition source INPUT_MIXER_TRANSITION follows the auto-transition blend value instead of jumping immediately to full scale. So if your tilt servos use INPUT_MIXER_TRANSITION, they should move according to the transition blend/ramp rather than doing an instant step.

With mixer_vtol_transition_dynamic_mixer = OFF, the transition source effectively jumps to full transition value. With it ON, the transition source is tied to the transition scaling logic.

It also does not change PID gains. It does not retune P/I/D values. What it does is scale how much MC and FW control authority reaches the mixer during the transition. In other words, the PID controllers still compute their outputs, but the mixer blends/scales the MC/FW authority during handoff. The profile hot-switch still reinitializes the active PID controller for the new platform after the switch.

So I would test two things separately:

Add FW profile servo 4/5 rules that hold the tilt servos at the final FW position.
Then try mixer_vtol_transition_dynamic_mixer = ON and check whether the tilt motion becomes smooth.

If the strange movement disappears after adding FW servo 4/5 hold rules, then the issue was probably the servo command path disappearing at the profile switch. If it disappears only after enabling dynamic mixer, then the issue was mostly the instant INPUT_MIXER_TRANSITION step with dynamic mixer OFF.

[mart1npetroff]

Something I forgot to mention here in the comments is that after @sensei-hacker’s comment:

“So it would smoothly fade from 100% to 20%, then suddenly jump to 0% when the completion criteria is met?”

I added fade logic that gradually reduces lift throttle to 0% after the transition completes successfully.

[mart1npetroff]

I know that not everything is documented in enough detail yet. This PR is still under active testing, development, and bug fixing.

Initially, my intention was to develop this functionality in smaller parts and avoid putting everything into one large PR at once. However, it is clear that there is a lot of interest in this feature, and the expectations are also quite high — which is great, and honestly very motivating.

To meet those expectations, I am actively changing and improving the code. Because of that, there may be temporary regressions or bugs, and the PR should still be considered experimental and not fully stable yet.

Tests like the one above are extremely helpful, because they expose cases I cannot easily test myself. At the moment I only have a VTOL with a pusher configuration, so I cannot properly validate tilt motors, tricopters, and all other possible VTOL layouts on real hardware.

So I would like to ask for a bit of patience while I stabilize the functionality, and also for continued testing and feedback from anyone who has different airframe configurations. Please treat this as experimental code for now and test carefully, because I would really hate for anyone to crash an aircraft because of an unfinished edge case in this PR.

Once we stabilize the behavior and the main edge cases are handled, I promise I will document the setup and configuration requirements in much more detail.

[error414]

I test it again and exactly same behaviour is with set mixer_vtol_manualswitch_autotransition_controller = OFF, I tried to add front tilt servos to mixer in plane mixer profile but i have no idea what I should select. MIN is not there, so I tried

and

Both configuration works, I can switch to FW and MC, transition works, but still there is werid servo movement I showed on video

[mart1npetroff]

This is weird.
mixer_vtol_manualswitch_autotransition_controller = OFF should keep the legacy behavior. And new logic should not work when OFF.

Could you try to put another build from maintenance-10.x branch and confirm if behavior different?

[error414]

https://www.youtube.com/shorts/vz0_LpD-IqM it's maintenance-10.x
INAV_9.1.0_cli_T1_20260610_213523-original.txt

[mart1npetroff]

Ok, thank you. I will try to figure out what is wrong.

[mart1npetroff]

I test it again and exactly same behaviour is with set mixer_vtol_manualswitch_autotransition_controller = OFF

There is new commit that should fix this.
Also I added unit test for different scenarios.

[mart1npetroff]

Successful two way auto-transition video:
https://youtu.be/XoUi37dBnqE
Observe modes at top left corner. After auto transition is triggered in both ways the whole procedure is automated (only the down pitch during the MC->FW transition is manual input by me).
There are some wobbles during the whole flight- I think it could be because I never executed auto trim and auto tune procedures...

I had a crisis during first RTH attempt (and I think it was caused by high vertical velocity combined with high nav yaw command) If you have suggestions for this moment and for the landing smoothing I will appreciate them..
Anyway I accept this as success...
Soon I will show automated mission including take off -> transition -> flight -> transition -> landing...

btw: the two sticks at the top are antennas :D

[mart1npetroff]

PR is updated with a fix for mission automation, VTOL stabilisation fixes related to this issue: #11470

and also landing detection improvements including throttle probe, docs are also updated.

Please use latest docs version and specially docs/VTOL.md for main guideline for setup and testing.

I'm still recovering my VTOL after false positive landing detection and auto disarm on 100m above the ground, so I did not fully test VTOL stabilisation feature so still be careful with vtol_mc_protection_mode and nav_disarm_on_landing.