Implement auto vtol smooth transition state

docs/MixerProfile.md

@@ -22,6 +22,34 @@ Transition input is disabled when navigation mode is activate
 
 The use of Transition Mode is recommended to enable further features and future developments like fail-safe support. Mapping motor to servo output, or servo with logic conditions is **not** recommended
 
+`MIXER TRANSITION` now behaves as a transition trigger/request (edge-triggered), not a continuous blend hold:
+
+- A rising edge starts one transition (MC->FW or FW->MC depending on current profile).
+- The transition state machine runs automatically to completion.
+- Keeping the mode ON does not repeatedly restart transitions.
+- A new transition requires mode OFF then ON again.
+- If switched OFF before hot-switch completes, the manual transition request is aborted.
+
+This edge-triggered behavior is enabled by `mixer_vtol_manualswitch_autotransition_controller`.
+Set `mixer_vtol_manualswitch_autotransition_controller = ON` in both mixer profiles (MC and FW) used for switching to keep manual transition semantics consistent after profile hot-switch.
+When `mixer_vtol_manualswitch_autotransition_controller = OFF`, manual transition keeps legacy behavior.
+With manual auto-transition enabled, Active Modes `MIXER TRANSITION` now indicates that the internal transition controller/mixing is actually active, not merely that the RC `MIXER TRANSITION` switch is active.
+Active Modes `MIXER PROFILE 2` indicates the currently active mixer profile.
+
+Important path split:
+- `MIXER PROFILE 2` remains a direct manual profile-switch path.
+- Smooth VTOL transition state-machine behavior is triggered by `MIXER TRANSITION` when `mixer_vtol_manualswitch_autotransition_controller = ON`.
+
+Recommended switch topology (explicit):
+- Use a dedicated 3-position mapping:
+  - Pos1 = MC (`MIXER PROFILE 2` OFF, `MIXER TRANSITION` OFF)
+  - Pos2 = Transition trigger (`MIXER PROFILE 2` OFF, `MIXER TRANSITION` ON)
+  - Pos3 = FW (`MIXER PROFILE 2` ON, `MIXER TRANSITION` OFF)
+- Keep `mixer_vtol_manualswitch_autotransition_controller` ON in both profiles used by this mapping.
+- Avoid overlapping FW selection and transition trigger in the same position.
+- Avoid 2-position setups where one position activates both `MIXER PROFILE 2` and `MIXER TRANSITION`.
+- Overlapping mode activation can produce order-dependent behavior (direct profile switch path vs transition-controller path), which is unpredictable and not recommended.
+
 ## Servo
 
 `Mixer Transition` is the input source for transition input; use this to tilt motor to gain airspeed.
@@ -72,6 +100,214 @@ This feature is mainly for RTH in a failsafe event. When set properly, model wil
 Set `mixer_automated_switch` to `ON` in mixer_profile for MC mode. Set `mixer_switch_trans_timer` in mixer_profile for MC mode for the time required to gain airspeed for your model before entering to FW mode.
 When `mixer_automated_switch`:`OFF` is set for all mixer_profiles(defaults). Model will not perform automated transition at all.
 
+### Unified VTOL transition controller
+
+Manual `MIXER TRANSITION` and mission-authorized VTOL transition both use the same internal transition controller.
+This controller always computes transition progress/completion and performs its own profile hot-switch only inside the authorized transition state.
+Direct manual `MIXER PROFILE 2` switching remains a separate path when no transition controller path is active.
+When `mixer_vtol_transition_dynamic_mixer = ON`, pusher/lift/authority scaling is enabled and is driven by:
+- transition progress (default), or
+- `mixer_vtol_transition_scale_ramp_time_ms` when configured (>0).
+
+### Airspeed-first completion
+
+When pitot airspeed is healthy and available, transition completion uses pitot thresholds:
+
+- `vtol_transition_to_fw_min_airspeed_cm_s` for MC->FW
+- `vtol_transition_to_mc_max_airspeed_cm_s` for FW->MC
+- If `vtol_transition_to_fw_min_airspeed_cm_s = 0`, MC->FW falls back to legacy `mixer_switch_trans_airspeed_cm_s`.
+
+If pitot is unavailable/unhealthy (or threshold is `0`), timer fallback is used (`mixer_switch_trans_timer`).
+Ground speed is not used for transition completion/progress.
+
+Optional safety timeout:
+
+- `mixer_vtol_transition_airspeed_timeout_ms` can abort transition if airspeed condition is not met in time.
+- This timeout is only active while transition completion is using trusted pitot airspeed.
+- If pitot is unavailable/unhealthy, transition completion falls back to `mixer_switch_trans_timer`; timeout does not force abort in that fallback path.
+- For airspeed-first setups, configure non-zero `mixer_switch_trans_timer` fallback (typical `40..60`, i.e. `4..6s`) so pitot-loss fallback does not complete immediately.
+
+### Dynamic scaling (optional)
+
+When `mixer_vtol_transition_dynamic_mixer = ON`, transition progress scales:
+
+- pusher contribution (`-2.0 < throttle < -1.0` motors) from configured max toward 0/100% depending on direction,
+- lift motor throttle contribution (`vtol_transition_lift_end_percent`),
+- MC stabilization authority (`vtol_transition_mc_authority_end_percent`),
+- FW authority start level (`vtol_transition_fw_authority_start_percent`, servo transition input blend).
+
+Default is OFF to preserve existing behavior.
+With dynamic scaling enabled, `vtol_transition_fw_authority_start_percent = 100` preserves legacy FW authority handoff; lower values provide smoother ramp-in.
+
+Optional scaling ramp timer:
+
+- `mixer_vtol_transition_scale_ramp_time_ms = 0` (default): scaling remains coupled to transition progress (legacy-compatible behavior).
+- `mixer_vtol_transition_scale_ramp_time_ms > 0`: scaling uses this timer, while transition completion stays airspeed-first (or timer fallback if pitot unavailable/unhealthy).
+
+Example:
+
+- `mixer_switch_trans_timer = 50` (5s fallback completion timer)
+- `mixer_vtol_transition_scale_ramp_time_ms = 1200`
+
+Result:
+- scaling reaches target levels in ~1.2s,
+- transition completion still follows airspeed threshold when pitot is healthy,
+- timer fallback completion still uses 5s when pitot is unavailable/unhealthy.
+
+### Mission-authorized VTOL transition (waypoint User Action)
+
+INAV supports mission-requested VTOL transitions through the existing automated transition path. This is configured with:
+
+- `nav_vtol_mission_transition_user_action` (`OFF`, `USER1`, `USER2`, `USER3`, `USER4`)
+- `nav_vtol_mission_transition_min_altitude_cm` (optional, `0` disables minimum-altitude check)
+- `vtol_transition_to_fw_min_airspeed_cm_s` (preferred MC->FW threshold)
+- `mixer_switch_trans_airspeed_cm_s` (legacy MC->FW fallback when preferred threshold is `0`)
+
+Scope note:
+
+- Per-mixer-profile settings:
+  - `mixer_automated_switch`
+  - `mixer_switch_trans_timer`
+  - `mixer_switch_trans_airspeed_cm_s`
+  - `mixer_vtol_transition_dynamic_mixer`
+  - `mixer_vtol_manualswitch_autotransition_controller`
+  - `mixer_vtol_transition_airspeed_timeout_ms`
+  - `mixer_vtol_transition_scale_ramp_time_ms`
+- Global settings:
+  - `vtol_transition_to_fw_min_airspeed_cm_s`
+  - `vtol_transition_to_mc_max_airspeed_cm_s`
+  - `vtol_transition_lift_end_percent`
+  - `vtol_transition_mc_authority_end_percent`
+  - `vtol_transition_fw_authority_start_percent`
+  - `nav_vtol_mission_transition_user_action`
+  - `nav_vtol_mission_transition_min_altitude_cm`
+  - `nav_vtol_mission_transition_track_distance_cm`
+
+On each navigable mission waypoint (`WAYPOINT`, `POSHOLD_TIME`, `LAND`), the configured USER action bit is used as absolute target selector:
+
+- selected USER bit = `0` -> transition to MC / MULTIROTOR profile
+- selected USER bit = `1` -> transition to FW / AIRPLANE profile
+- When `nav_vtol_mission_transition_user_action != OFF`, each navigable waypoint encodes a target state via that selected bit.
+- This is a per-waypoint target-state declaration (not an event trigger). Users should intentionally set/clear the selected USER bit on each navigable waypoint.
+- This is **not** a toggle command.
+- If already in the requested profile type, the action is treated as complete (idempotent).
+
+The mission pauses while transition is in progress and resumes after completion.
+
+For MC -> FW mission transitions, navigation uses a straight acceleration segment (no loiter) to build speed before hot-switch.
+Mission path uses the same controller and completion logic as manual transition (airspeed-first, timer fallback).
+
+Manual RC switching (`MIXER PROFILE 2`, `MIXER TRANSITION`) remains blocked during normal active navigation. Mission VTOL transition does not bypass the hot-switch safety guard; it only authorizes switching inside the automated transition state.
+Mission VTOL transition still relies on normal profile-switch infrastructure: configure two mixer profiles and a valid `MIXER PROFILE 2` mode activation condition.
+
+### Example test presets (VTOL ~1.0m wingspan, ~1720g AUW)
+
+These are practical starting points for first validation flights. They are examples, not universal defaults.
+
+#### Test 1 - Legacy-compatible baseline (manual transition check)
+
+CLI:
+- `set mixer_vtol_manualswitch_autotransition_controller = ON`
+- `set mixer_vtol_transition_dynamic_mixer = OFF`
+- `set mixer_switch_trans_timer = 45`
+- `set vtol_transition_to_fw_min_airspeed_cm_s = 0`
+- `set mixer_switch_trans_airspeed_cm_s = 0`
+- `set vtol_transition_to_mc_max_airspeed_cm_s = 900`
+- `set mixer_vtol_transition_airspeed_timeout_ms = 0`
+- `set mixer_vtol_transition_scale_ramp_time_ms = 0`
+- `set nav_vtol_mission_transition_user_action = OFF`
+
+Behavior:
+- Preserves legacy-style transition mixing while still using the new controller path.
+- Useful as a known-safe baseline before enabling dynamic scaling.
+
+#### Test 2 - Airspeed-first + dynamic scaling (manual tuning)
+
+CLI:
+- `set mixer_vtol_manualswitch_autotransition_controller = ON`
+- `set mixer_vtol_transition_dynamic_mixer = ON`
+- `set vtol_transition_to_fw_min_airspeed_cm_s = 1300`
+- `set vtol_transition_to_mc_max_airspeed_cm_s = 850`
+- `set mixer_switch_trans_timer = 50`
+- `set mixer_vtol_transition_airspeed_timeout_ms = 6500`
+- `set mixer_vtol_transition_scale_ramp_time_ms = 1200`
+- `set vtol_transition_lift_end_percent = 30`
+- `set vtol_transition_mc_authority_end_percent = 20`
+- `set vtol_transition_fw_authority_start_percent = 20`
+- `set nav_vtol_mission_transition_user_action = OFF`
+
+Behavior:
+- Uses pitot-first completion logic with timer fallback only when pitot is unavailable/unhealthy.
+- Adds fast, smooth pusher/lift/authority ramping to reduce abrupt transitions.
+
+#### Test 3 - Mission-authorized transition (mission integration)
+
+CLI:
+- `set mixer_vtol_manualswitch_autotransition_controller = ON`
+- `set mixer_vtol_transition_dynamic_mixer = ON`
+- `set vtol_transition_to_fw_min_airspeed_cm_s = 1300`
+- `set vtol_transition_to_mc_max_airspeed_cm_s = 850`
+- `set mixer_switch_trans_timer = 50`
+- `set mixer_vtol_transition_airspeed_timeout_ms = 6500`
+- `set mixer_vtol_transition_scale_ramp_time_ms = 1200`
+- `set vtol_transition_lift_end_percent = 30`
+- `set vtol_transition_mc_authority_end_percent = 20`
+- `set vtol_transition_fw_authority_start_percent = 20`
+- `set nav_vtol_mission_transition_user_action = USER1`
+- `set nav_vtol_mission_transition_min_altitude_cm = 1200`
+- `set nav_vtol_mission_transition_track_distance_cm = 4000`
+
+Behavior:
+- Uses USER1 as per-waypoint absolute target selector (clear=MC, set=FW).
+- Pauses mission progression during transition and resumes only after transition completion.
+
+### Validation Matrix (PR / SITL / HITL)
+
+- MC->FW manual, pitot healthy/available.
+- MC->FW manual, no pitot (timer fallback).
+- FW->MC manual, pitot healthy/available.
+- FW->MC manual, no pitot (timer fallback).
+- `MIXER TRANSITION` held ON after completion (no repeated starts).
+- `MIXER TRANSITION` OFF before hot-switch (safe abort).
+- Mission transition with selected USER bit = `1` (TO_FW).
+- Mission transition with selected USER bit = `0` (TO_MC).
+- Failsafe/disarm during active transition (abort and no blind mission resume).
+
+### VTOL transition debug mode (Blackbox / OSD debug)
+
+For transition troubleshooting, use:
+
+- `set debug_mode = VTOL_TRANSITION`
+- `save`
+
+Debug channels:
+
+- `debug[0]` = transition phase (`0=IDLE`, `1=TRANSITION_INITIALIZE`, `2=TRANSITIONING`)
+- `debug[1]` = active request (`MIXERAT_REQUEST_*` enum value)
+- `debug[2]` = packed transition flags:
+    - bits 0-1: transition direction (`0=NONE`, `1=TO_FW`, `2=TO_MC`)
+    - bit2: auto-transition controller active
+    - bit3: transition mixing output active (`isMixerTransitionMixing`)
+    - bit4: RC `MIXERTRANSITION` mode active
+    - bit5: airspeed-controlled path in use
+    - bit6: hot-switch done
+    - bit7: transition aborted
+    - bit8: manual VTOL auto-transition controller enabled in current mixer config
+    - bit9: dynamic transition mixer enabled in current mixer config
+    - bits 10-11: current mixer profile index
+    - bits 12-13: next mixer profile index
+    - bit14: manual transition currently allowed by navigation state
+    - bit15: mission mode active
+    - bit16: transition mixing requested (`isMixerTransitionMixing_requested`)
+    - bit17: failsafe mode active
+    - bit18: manual VTOL auto-transition controller effective after mission gating
+    - bit19: RC `MIXERPROFILE` mode active
+- `debug[3]` = progress x1000 (`0..1000`)
+- `debug[4]` = pusher scale x1000 (`0..1000`)
+- `debug[5]` = lift scale x1000 (`0..1000`)
+- `debug[6]` = MC authority scale x1000 (`0..1000`)
+- `debug[7]` = current mixer profile pitch transition PID multiplier (`transition_PID_mmix_multiplier_pitch`)
+
 ## TailSitter (planned for INAV 7.1)
 TailSitter is supported by add a 90deg offset to the board alignment. Set the board aliment normally in the mixer_profile for FW mode(`set platform_type = AIRPLANE`), The motor trust axis should be same direction as the airplane nose. Then, in the mixer_profile for takeoff and landing set `tailsitter_orientation_offset = ON ` to apply orientation offset. orientation offset will also add a 45deg orientation offset.
 

docs/Navigation.md

@@ -102,6 +102,45 @@ Parameters:
 
   * `<flag>` - Last waypoint must have `flag` set to 165 (0xA5).
 
+### Mission VTOL transition using existing User Actions
+
+Mission VTOL transition can be requested.
+
+Configuration:
+
+- `nav_vtol_mission_transition_user_action` selects which waypoint User Action (`USER1..USER4`) is used as the mission VTOL target selector.
+- `nav_vtol_mission_transition_min_altitude_cm` optionally enforces a minimum altitude before transition start (`0` disables check).
+- `nav_vtol_mission_transition_track_distance_cm` configures straight-line MC->FW transition guidance distance.
+- VTOL transition completion logic is shared with manual MIXER TRANSITION and uses mixer transition settings:
+  - preferred MC->FW threshold: `vtol_transition_to_fw_min_airspeed_cm_s`
+  - legacy MC->FW fallback (when preferred threshold is `0`): `mixer_switch_trans_airspeed_cm_s`
+  - FW->MC threshold: `vtol_transition_to_mc_max_airspeed_cm_s`
+
+Behavior on each navigable mission waypoint (`WAYPOINT`, `POSHOLD_TIME`, `LAND`):
+
+- The configured USER bit is an **absolute target selector**:
+  - `0`: transition to MC / MULTIROTOR profile
+  - `1`: transition to FW / AIRPLANE profile
+- When `nav_vtol_mission_transition_user_action != OFF`, each navigable waypoint always encodes target state via that selected USER bit.
+- This means every navigable waypoint implicitly declares desired VTOL platform state when this feature is enabled; users must intentionally set/clear that bit on each waypoint.
+- This command is **not** a toggle.
+- The command is idempotent: if already in the requested target profile type, the mission continues immediately.
+- If a transition is needed, mission progression pauses while automated transition runs, then resumes only after completion.
+
+Transition behavior in this MVP:
+
+- MC -> FW: straight-line acceleration segment (no loiter), heading from the next waypoint bearing when available, otherwise current heading.
+- MC -> FW and FW -> MC completion uses pitot airspeed thresholds when healthy/available (`vtol_transition_to_fw_min_airspeed_cm_s`, `vtol_transition_to_mc_max_airspeed_cm_s`).
+- If pitot is unavailable/unhealthy (or threshold disabled), timer fallback (`mixer_switch_trans_timer`) is used.
+- Ground speed is not used for transition progress/completion.
+- FW -> MC: mission pauses during automated transition, then resumes after switching back to MC profile.
+- Strict altitude hold is not enforced during MC -> FW transition; natural climb is allowed.
+
+Safety and scope:
+
+- This path uses authorized automated transition state handling; it does not permit manual mixer profile switching during normal waypoint navigation.
+- It still depends on valid mixer profile switching infrastructure (two configured mixer profiles and a valid `MIXER PROFILE 2` mode activation condition).
+
 `wp save` - Checks list of waypoints and save from FC to EEPROM (warning: it also saves all unsaved CLI settings like normal `save`).
 
 `wp reset` - Resets the list, sets the number of waypoints to 0 and marks the list as invalid (but doesn't delete the waypoint definitions).