Implement auto vtol smooth transition state

[mart1npetroff]

No description provided.

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