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

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 0258521

Download firmware for PR #11553

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

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →