Improve VTOL RTH approach timing and post-transition capture

docs/VTOL.md

@@ -407,6 +407,10 @@ With this global option enabled, an armed manual switch from one VTOL mixer prof
 
 Leave `vtol_autotransition_always = OFF` if you want the pilot to keep the explicit choice between a direct profile switch and a separate `MIXER TRANSITION` request.
 
+After leaving a mission, RTH, or automatic landing while armed, the physical switch may disagree with the actual mixer profile. INAV keeps the actual profile until you move the switch to its matching endpoint with `MIXER TRANSITION` OFF. Passing through the middle position does not start a transition or confirm the switch, even if the profile bit happens to match there. This also applies if you interrupt an automatic transition: match the profile that is actually active, not the one the transition intended to reach. Output completion still in progress does not bypass this protection.
+
+Once the endpoint matches, subsequent switch movements work normally, including `vtol_autotransition_always = ON`. Starting another mission/RTH gives control back to navigation; disarming releases the switch-matching requirement for preflight checks. Active Modes reports the actual mixer profile and actual transition/mixing activity, not simply the physical switch position.
+
 Optional two-position layout with instant FW -> MC:
 
 Some pilots want an automated MC -> FW transition, but want FW -> MC to switch almost immediately when they request multicopter mode. This can still be done with `vtol_autotransition_always = ON` by making the FW -> MC transition complete by timer with a zero timer.
@@ -519,6 +523,68 @@ It can be used in two contexts:
 
 This setting decides when the emergency FW -> MC fallback starts. `vtol_transition_to_mc_max_airspeed_cm_s` still decides when the FW -> MC profile switch is safe to complete during an airspeed-controlled FW -> MC transition.
 
+### Early FW -> MC start during RTH
+
+When RTH is allowed to land and the armed aircraft is approaching the active Home or SafeHome in FW mode, INAV can start FW -> MC before the aircraft reaches the landing point. No additional radius setting is required.
+
+INAV estimates the distance needed from information that is already available:
+
+1. It projects the current trusted GPS ground velocity toward Home. This produces the **closing speed**: only the part of the ground movement that is actually reducing the remaining distance. A crosswind therefore does not incorrectly count all sideways speed as approach speed.
+2. It builds a time budget from the FW/source profile. `mixer_switch_trans_timer` contributes its value in `100ms` units. If `mixer_vtol_transition_dynamic_mixer = ON`, `mixer_vtol_transition_scale_ramp_time_ms` is added because the target MC outputs can still be moving after the profile switch.
+3. It multiplies closing speed by that time budget. For example, `mixer_switch_trans_timer = 50`, `mixer_vtol_transition_scale_ramp_time_ms = 1200`, and dynamic scaling ON produce a `6.2s` planning budget. At a closing speed of `20m/s`, the predicted start distance is about `124m`.
+4. The result is never smaller than `nav_fw_loiter_radius`. If ground velocity is not trusted, the aircraft is moving sideways, or it is moving away from Home, `nav_fw_loiter_radius` becomes the conservative staging distance.
+5. The aircraft must remain inside the calculated start distance for `300ms` before INAV starts the transition. This prevents one noisy GPS velocity sample from starting FW -> MC far from Home.
+
+For the example above, with the global `nav_fw_loiter_radius = 7500` (`75m`):
+
+| Ground movement toward Home | Time budget | Start boundary |
+| --- | --- | --- |
+| `20m/s` | `6.2s` | `124m` |
+| `10m/s`, for example with more headwind | `6.2s` | `75m`, because the calculated `62m` is inside the staging boundary |
+| `25m/s`, for example with more tailwind | `6.2s` | `155m` |
+| No trusted velocity, purely sideways movement, or movement away from Home | Staging fallback | `75m` |
+
+The boundary is recalculated during the approach; the extra `300ms` confirmation means the actual start can be slightly inside it. Ground velocity already reflects the aircraft's movement in the prevailing wind, so this calculation does not require a separate wind estimate. It cannot predict a later gust.
+
+The mixer timers above belong to the **FW/source mixer profile**. A longer timer or a longer enabled output ramp moves the calculated boundary farther out; a shorter value moves it closer, down to the loiter-radius boundary. With dynamic scaling OFF, the output ramp is excluded from the calculation. With both times at zero, only `nav_fw_loiter_radius` is used. Setting that radius to zero also removes the minimum staging distance; the original arrival/landing path remains available if the early trigger has not fired.
+
+For an airspeed-controlled transition, this time budget is only a planning estimate. The configured backup timer does not measure how long this airframe actually needs to slow down. In particular, a zero backup timer with a valid pitot does not imply an immediate transition: the airspeed condition can still take several seconds to satisfy. The estimate does not include the later time needed to stop and turn in MC, and cannot guarantee that the aircraft will stop before Home.
+
+Ground speed only decides **when the procedure starts**. It does not bypass the configured transition safety condition. If `vtol_transition_to_mc_max_airspeed_cm_s` is non-zero and a usable real or virtual pitot source is available, airspeed still decides when the FW -> MC profile switch is safe. If no usable airspeed source is available, the normal `mixer_switch_trans_timer` fallback completes the transition. `mixer_vtol_transition_airspeed_timeout_ms` remains a failure timeout and is not treated as expected transition time.
+
+This early start is used only for an RTH that is allowed to land. It does not change mission waypoint transitions, manual transitions, RTH configured to loiter without landing, or the separate low-speed FW -> MC safety protection. The source FW profile must have `mixer_automated_switch = ON`, and the paired target profile must be a supported MC profile.
+
+It runs on the direct Home/SafeHome approach after the RTH climb/trackback stages. While following geozone avoidance waypoints, the early trigger is suspended. Loss of usable position, a route interruption, or a NAV state change clears its confirmation timer. Returning to the approach requires a fresh confirmation.
+
+Failsafe RTH uses the same approach when landing is allowed. `nav_rth_fs_landing_delay` still delays landing at Home; the earlier profile change can already have happened before this delay starts. Existing transition failure actions still apply if FW -> MC fails. Tailsitter autonomous-transition restrictions also remain in force.
+
+An RTH-owned transition, including its retry wait/scan, is still part of the same RTH procedure even when the OSD shows altitude hold during the transition. An already selected SafeHome is not replaced with the arming point just because the transition starts. The established RTH altitude plan is retained too: EXTRA altitude is not added again, and the linear-descent plan is not recalculated as though RTH had been switched off. Normal SafeHome permissions and trackback restrictions still apply.
+
+A brief loss of the position estimate does not by itself deselect an RTH-owned transition. If the existing navigation position-failure timeout expires, or the heading estimate becomes unavailable, INAV aborts the transition and enters its existing emergency-landing procedure. A disabled position-failure timeout keeps its existing meaning; this change adds no new timeout. Pilot cancellation and higher-priority emergency requests still take precedence.
+
+RC `HOME RESET` is blocked during navigation-owned RTH, mission and LAND transitions, including retry, just as it is blocked during normal RTH/mission flight. This does not block Home reset solely because a manual transition is active, and does not change the separate rules for changing Home through other interfaces.
+
+### RTH behavior after FW -> MC
+
+An airplane can pass Home or SafeHome while FW -> MC is still completing. INAV does not immediately command the new MC profile to fly backwards or sideways toward the landing point.
+
+After a navigation-owned FW -> MC switch during the RTH approach, INAV now performs these steps:
+
+1. It commands zero climb/descent and keeps the post-switch heading while the MC controller removes the remaining fixed-wing ground speed. The altitude target follows the current altitude during this step to avoid chasing a pre-transition height. The XY target follows the current position, so the aircraft is not pulled back toward the point where the profile switch happened.
+2. Once horizontal/vertical speed and roll/pitch remain stable, INAV holds that position and turns the nose toward Home. If already inside the stricter VTOL landing capture radius, it uses the configured Home landing heading instead.
+3. The heading and settle conditions must then remain acceptable continuously before normal RTH approach resumes.
+4. The aircraft approaches Home nose-first, enters the existing landing settle gate, and only then starts descent.
+
+During alignment, the direction toward Home is updated from the actual position. A substantial increase in horizontal speed or excessive roll/pitch returns the sequence to braking before attempting another turn. The existing RTH position-sensor timeout and `nav_rth_abort_threshold` checks remain active. There is no timer that forces the aircraft to approach Home while it still fails the settle/heading conditions.
+
+The braking/alignment stages pause ordinary RTH altitude targeting, including EXTRA climb or linear descent. After they finish, normal RTH altitude management resumes on the approach to Home. If the RTH safe altitude has not yet been reached, it may command a climb again. Changing to another navigation mode clears the old braking/alignment target.
+
+After RTH selects MC for the landing approach, it stays in MC for that RTH procedure rather than requesting FW again just because Home is still far away. Leaving RTH clears this normal landing choice: for example, RTH -> POSH -> mission can request FW again at a waypoint. This is separate from a genuine low-speed safety switch, whose existing protection continues to prevent automatic FW requests until navigation returns to idle. Changing to POSH alone does not clear that safety protection.
+
+This sequence uses the existing VTOL settle limits and does not add another CLI setting. It is applied after the successful navigation-owned profile switch even when `vtol_mc_protection_mode = OFF`. When VTOL MC protection is `NAV` or `NAV_AND_STABILIZED`, its throttle reserve, altitude anti-windup bounds, and bailout protection remain active throughout the MC braking, alignment, approach, and landing states.
+
+The early prediction is intended to reduce overshoot. This post-switch sequence handles an inaccurate prediction by stopping and facing Home before the return approach. Validate the chosen timer values and the resulting stopping distance on the actual airframe; these calculations are not a model of its braking performance.
+
 ## 2. Manual switch auto transition with dynamic scaling
 
 Dynamic scaling is the optional smooth part of the new transition system. It lets INAV change motor power and stabilisation strength gradually instead of making one large step at the profile switch.

src/main/flight/mixer_profile.c

@@ -1271,7 +1271,6 @@ void outputProfileUpdateTask(timeUs_t currentTimeUs)
             navigationProfileSwitchWasOwned,
             navigationOwnsProfileSwitch,
             mixerProfileModePresent,
-            mixerAT_inuse,
             transitionModeActive,
             currentMixerProfileIndex,
             requestedProfileIndex);

src/main/flight/mixer_transition_logic.h

@@ -239,15 +239,15 @@ static inline bool mixerTransitionNavigationHandbackShouldHoldProfile(
     bool navigationOwnedProfileSwitchPreviousUpdate,
     bool navigationOwnsProfileSwitch,
     bool mixerProfileModePresent,
-    bool autoTransitionActive,
     bool transitionModeActive,
     int currentProfileIndex,
     int requestedProfileIndex)
 {
+    // Capture the ownership edge even if transition outputs are still finishing.
+    // Waiting for an idle transition would lose this edge on the next update.
     return navigationOwnedProfileSwitchPreviousUpdate &&
            !navigationOwnsProfileSwitch &&
            mixerProfileModePresent &&
-           !autoTransitionActive &&
            (transitionModeActive || currentProfileIndex != requestedProfileIndex);
 }