shota3527 · shota3527 · Aug 9, 2023 · Aug 10, 2023 · Aug 11, 2023 · Aug 12, 2023
diff --git a/docs/MixerProfile.md b/docs/MixerProfile.md
@@ -133,6 +133,9 @@ save
 When `mixer_automated_switch`:`OFF` is set for all mixer_profiles(defaults). Model will not perform automated transition at all.
 
 
+### TailSitter support
+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 platform_type = TAILSITTER`. The `TAILSITTER` platform type is same as `MULTIROTOR` platform type, expect for a 90 deg board alignment offset. In `TAILSITTER` mixer_profile, when motor trust/airplane nose is pointing to the sky, 'airplane bottom'/'multi rotor front' should facing forward in model preview. Set the motor/servo mixer according to multirotor orientation, Model should roll around geography's longitudinal axis, the roll axis of `TAILSITTER` will be yaw axis of `AIRPLANE`. In addition, When `MIXER TRANSITION` input is activated, a 45deg offset will be add to the target angle for angle mode.
+
 ## Happy flying
 
 Remember that this is currently an emerging capability:

diff --git a/docs/Screenshots/mixerprofile_4puls1_mix.png b/docs/Screenshots/mixerprofile_4puls1_mix.png
diff --git a/docs/Screenshots/mixerprofile_flow.png b/docs/Screenshots/mixerprofile_flow.png
diff --git a/docs/Screenshots/mixerprofile_fw_mixer.png b/docs/Screenshots/mixerprofile_fw_mixer.png
diff --git a/docs/Screenshots/mixerprofile_mc_mixer.png b/docs/Screenshots/mixerprofile_mc_mixer.png
diff --git a/docs/Screenshots/mixerprofile_servo_transition_mix.png b/docs/Screenshots/mixerprofile_servo_transition_mix.png
diff --git a/docs/Settings.md b/docs/Settings.md
@@ -1222,16 +1222,6 @@ Iterm is not allowed to grow when stick position is above threshold. This solves
 
 ---
 
-### fw_iterm_throw_limit
-
-Limits max/min I-term value in stabilization PID controller in case of Fixed Wing. It solves the problem of servo saturation before take-off/throwing the airplane into the air. By default, error accumulated in I-term can not exceed 1/3 of servo throw (around 165us). Set 0 to disable completely.
-
-| Default | Min | Max |
-| --- | --- | --- |
-| 165 | FW_ITERM_THROW_LIMIT_MIN | FW_ITERM_THROW_LIMIT_MAX |
-
----
-
 ### fw_level_pitch_gain
 
 I-gain for the pitch trim for self-leveling flight modes. Higher values means that AUTOTRIM will be faster but might introduce oscillations
@@ -1924,7 +1914,7 @@ Calculated 1G of Acc axis Z to use in INS
 
 ### iterm_windup
 
-Used to prevent Iterm accumulation on during maneuvers. Iterm will be dampened when motors are reaching it's limit (when requested motor correction range is above percentage specified by this parameter)
+Used to prevent Iterm accumulation on during maneuvers. Iterm accumulation will be dampened when motors are reaching it's limit (when requested motor correction range is close percentage specified by this parameter, when value is set below 50 no accumulation occors when iterm_windup+50 of motor correction range is reached)
 
 | Default | Min | Max |
 | --- | --- | --- |
@@ -4802,6 +4792,16 @@ Video system used. Possible values are `AUTO`, `PAL`, `NTSC`, `HDZERO`, 'DJIWTF'
 
 ---
 
+### pid_iterm_limit_percent
+
+Limits max/min I-term value in stabilization PID controller. It solves the problem of servo saturation before take-off/throwing the airplane into the air. Or multirotors with low authority. By default, error accumulated in I-term can not exceed 33% of total pid throw (around 165us on deafult pidsum_limit of pitch/roll). Set 0 to disable completely.
+
+| Default | Min | Max |
+| --- | --- | --- |
+| 33 | 0 | 200 |
+
+---
+
 ### pid_type
 
 Allows to set type of PID controller used in control loop. Possible values: `NONE`, `PID`, `PIFF`, `AUTO`. Change only in case of experimental platforms like VTOL, tailsitters, rovers, boats, etc. Airplanes should always use `PIFF` and multirotors `PID`
@@ -5602,6 +5602,16 @@ Delay before disarming when requested by switch (ms) [0-1000]
 
 ---
 
+### tailsitter_orientation_offset
+
+Apply a 90 deg pitch offset in sensor aliment for tailsitter flying mode
+
+| Default | Min | Max |
+| --- | --- | --- |
+| OFF | OFF | ON |
+
+---
+
 ### telemetry_halfduplex
 
 S.Port telemetry only: Turn UART into UNIDIR for usage on F1 and F4 target. See Telemetry.md for details
@@ -5702,9 +5712,19 @@ See tpa_rate.
 
 ---
 
+### tpa_on_yaw
+
+Throttle PID attenuation also reduces influence on YAW for multi-rotor, Should be set to ON for tilting rotors.
+
+| Default | Min | Max |
+| --- | --- | --- |
+| OFF | OFF | ON |
+
+---
+
 ### tpa_rate
 
-Throttle PID attenuation reduces influence of P on ROLL and PITCH as throttle increases. For every 1% throttle after the TPA breakpoint, P is reduced by the TPA rate.
+Throttle PID attenuation reduces influence of PDFF on ROLL and PITCH of multi-rotor, PIDFF on ROLL,PITCH,YAW OF fixed_wing as throttle increases. For every 1% throttle after the TPA breakpoint, P is reduced by the TPA rate.
 
 | Default | Min | Max |
 | --- | --- | --- |

diff --git a/docs/VTOL.md b/docs/VTOL.md
@@ -0,0 +1,206 @@
+# Welcome to INAV VTOL Testing
+
+Thank you for participating in the INAV VTOL testing phase.
+
+## Who Should Use This Tutorial?
+
+This tutorial is designed for individuals who have prior experience with **both INAV multi-rotor and INAV fixed-wing configurations/operations.** If you're not familiar with them, this tutorial might be not for you.
+
+## Firmware Status
+
+The firmware is in a flyable state, but it hasn't undergone extensive testing yet. This means there may be potential issues that have not yet been discovered.
+
+## Future Changes
+
+Please be aware that both the setup procedure and firmware may change in response to user feedback and testing results. 
+## Your Feedback Matters
+
+We highly value your feedback as it plays a crucial role in the development and refinement of INAV VTOL capabilities. Please share your experiences, suggestions, and any issues you encounter during testing. Your insights are invaluable in making INAV VTOL better for everyone.
+
+# VTOL Configuration Steps
+
+### The VTOL functionality is achieved by switching/transitioning between two configurations stored in the FC. VTOL specific configurations are Mixer Profiles with associated PID profiles. One profile set is for fixed-wing(FW) mode, One is for multi-copter(MC) mode. Configuration/Settings other than Mixer/PID profiles are shared among two modes 
+![Alt text](Screenshots/mixerprofile_flow.png)
+
+0. **Find a DIFF ALL file for your model and start from there if possible**
+   - Be aware that `MIXER PROFILE 2` RC mode setting introduced by diff file can get your stuck in a mixer_profile. remove or change channel to proceed
+1. **Setup Profile 1:**
+   - Configure it as a normal fixed-wing/multi-copter.
+
+2. **Setup Profile 2:**
+   - Configure it as a normal multi-copter/fixed-wing.
+
+3. **Mode Tab Settings:**
+   - Set up switching in the mode tab.
+
+4. *(Recommended)* **Transition Mixing (Multi-Rotor Profile):**
+   - Configure transition mixing to gain airspeed in the multi-rotor profile.
+
+5. *(Recommended)* **VTOL-Specific Settings:**
+   - Configure VTOL-specific settings.
+
+6. *(Optional)* **Automated Switching (RTH):**
+   - Optionally, set up automated switching in case of failsafe.
+
+# STEP1&2: Configuring as a Normal fixed-wing/Multi-Copter in two profiles separately
+
+1. **Select the fisrt Mixer Profile and PID Profile:**
+   - In the CLI, switch to the mixer_profile and pid_profile you wish to set first:
+     ```
+     mixer_profile 1 #in this example, we set profile 1 first
+     set mixer_pid_profile_linking = ON  # Let the mixer_profile handle the pid_profile switch on this mixer_profile
+     set platform_type = AIRPLANE
+     save
+     ```
+
+2. **Configure the fixed-wing/Multi-Copter:**
+   - Configure your fixed-wing/Multi-Copter as you normally would, or you can copy and paste default settings to expedite the process.
+   - Dshot esc protocol availability might be limited depends on outputs and fc board you are using. change the motor wiring or use oneshot/multishot esc protocol and calibrate throttle range.
+   - You can use throttle = -1 as a placeholder for the motor you wish to stop if the motor isn't the last motor
+   - Consider conducting a test flight to ensure that everything operates as expected. And tune the settings, trim the servos.
+
+![Alt text](Screenshots/mixerprofile_fw_mixer.png)
+
+3. **Switch to Another Mixer Profile with PID Profile:**
+   - In the CLI, switch to another mixer_profile along with the appropriate pid_profile:
+     ```
+     mixer_profile 2
+     set mixer_pid_profile_linking = ON
+     set platform_type = MULTIROTOR
+     save
+     ```
+
+4. **Configure the Multi-Copter/fixed-wing:**
+   - Set up your multi-copter/fixed-wing as usual, this time for mixer_profile 2 and pid_profile 2.
+   - Utilize the 'MAX' input in the servo mixer to tilt the motors without altering the servo midpoint.
+   - At this stage, focus on configuring profile-specific settings. You can streamline this process by copying and pasting the default PID settings.
+   - compass is required to enable navigation modes for multi-rotor profile.
+   - Consider conducting a test flight to ensure that everything operates as expected. And tune the settings.
+   - It is advisable to have a certain degree of control surface (elevon / elevator) mapping for stabilization even in multi-copter mode. This helps improve control authority when airspeed is high.
+
+![Alt text](Screenshots/mixerprofile_mc_mixer.png)
+
+5. **Tailsitters:**
+Working in progress. 
+   - Configure the fixed-wing mode/profile sets normally. Use MultiCopter platform type for tail_sitting flying mode/profile sets. 
+   - The baseline board aliment is FW mode(ROLL axis is the trust axis). So set `tailsitter_orientation_offset = ON ` in the tail_sitting MC mode.
+   - Configure mixer ROLL/YAW mixing according to tail_sitting orientation in the tail_sitting MC mode. YAW axis is the trust axis.
+   - Conduct a bench test and see the orientation of the model changes in inav-configurator setup tab
+
+# STEP3: Mode Tab Settings:
+### We recommend using an 3-pos switch on you radio to activate these modes, So pilot can jump in or bell out at any moment.
+### Here is a example, in the bottom of inav-configurator Modes tab:
+![Alt text](Screenshots/mixer_profile.png)
+|  1000~1300 |  1300~1700  | 1700~2000 |
+| :-- | :-- | :-- |
+| Profile1(FW) with transition off |  Profile2(MC) with transition on  | Profile2(MC) with transition off |
+
+- Profile file switching becomes available after completing the runtime sensor calibration(15-30s after booting). And It is **not available** when a navigation mode or position hold is active.
+
+- By default, `mixer_profile 1` is used. `mixer_profile 2` is used when the `MIXER PROFILE 2` mode is activate. Once configured successfully, you will notice that the profiles and model preview changes accordingly when you refresh the relevant INAV Configurator tabs. 
+
+- Use the `MIXER TRANSITION` mode to gain airspeed in MC profile, set `MIXER TRANSITION` accordingly.
+
+Conduct a bench test on the model (without props attached). The model can now switch between fixed-wing and multi-copter modes while armed. Furthermore, it is capable of mid-air switching, resulting in an immediate stall upon entering fixed-wing profile
+
+# STEP4: Transition Mixing (Multi-Rotor Profile)(Recommended)
+### Transition Mixing is typically useful in multi-copter profile to gain airspeed in prior to entering the fixed-wing profile. When the `MIXER TRANSITION` mode is activated, the associated motor or servo will move according to your configured Transition Mixing. 
+
+Please note that transition input is disabled when a navigation mode is activated. The use of Transition Mixing is necessary to enable additional features such as VTOL RTH with out stalling.
+## Servo 'Transition Mixing': Tilting rotor configuration.
+Add new servo mixer rules, and select 'Mixer Transition' in input. Set the weight/rate according to your desired angle. This will allow tilting the motor for tilting rotor model.
+
+![Alt text](Screenshots/mixerprofile_servo_transition_mix.png)
+
+## Motor 'Transition Mixing': Dedicated forward motor configuration
+In motor mixer set:
+- -2.0 < throttle < -1.0: The motor will spin regardless of the radio's throttle position at a speed of `abs(throttle) - 1` multiplied by throttle range only when Mixer Transition is activated.
+
+![Alt text](Screenshots/mixerprofile_4puls1_mix.png)
+
+## TailSitter 'Transition Mixing': 
+No additional settings needed, 45deg off set will be added to target pitch angle for angle mode in the firmware.
+
+### With aforementioned settings, your model should be able to enter fixed-wing profile without stalling.
+
+# STEP5: VTOL-Specific Settings (Recommended):
+### recommended settings, more based on field experience are coming
+```
+set nav_disarm_on_landing = OFF #band-aid for false landing detection in NAV landing of multi-copter
+set airmode_type = STICK_CENTER_ONCE
+set ahrs_inertia_comp_method = ADAPTIVE # will automatically use VELNED in mc mode
+set tpa_on_yaw = ON #For yaw control by tilt rotor in the MC pid_profile
+set servo_pwm_rate = 160 #For yaw control by tilt rotor model
+set servo_lpf_hz = 30 #For yaw control by tilt rotor model
+```
+
+# Automated Switching (RTH) (Optional):
+### This is one of the least tested features. This feature is primarily designed for Return to Home (RTH) in the event of a failsafe. 
+When configured correctly, the model will use the Fixed-Wing (FW) mode to efficiently return home and then transition to Multi-Copter (MC) mode for easier landing.
+
+To enable this feature, type follwoing command in cli
+
+1. In your MC mode mixer profile (e.g., mixer_profile 2), set `mixer_automated_switch` to `ON`. leave it to `OFF` if burning remaining battery capacity on the way home is acceptable.
+```
+mixer_profile 2or1
+set mixer_automated_switch= ON
+```
+
+2. Set `mixer_switch_trans_timer` ds in cli in the MC mode mixer profile to specify the time required for your model to gain sufficient airspeed before transitioning to FW mode. 
+```
+mixer_profile 2or1
+set mixer_switch_trans_timer = 30 # 3s, 3000ms
+```
+3. In your FW mode mixer profile (e.g., mixer_profile 1), also set `mixer_automated_switch` to `ON`. leave it to `OFF` if automated landing in fixed-wing is acceptable.
+```
+mixer_profile 1or2
+set mixer_automated_switch = ON
+```
+4. Save your settings. type `save` in cli. 
+
+If you set `mixer_automated_switch` to `OFF` for all mixer profiles (the default setting), the model will not perform automated transitions. You can always enable navigation modes after performing a manual transition.
+
+
+# Notes and Experiences 
+## General
+- VTOL model operating in multi-copter (MC) mode may encounter challenges in windy conditions. Please exercise caution when testing in such conditions.
+
+## Tilting-rotor
+- In some tilting motor models, you may experience roll/yaw coupled oscillations when `MIXER TRANSITION` is activated. To address this issue, you can try the following:
+    1. try hard on pid
+    1. try different prop direction, prop size.
+    2. you can add servo mixing rules to decouple the control input. such use tilt servo for roll control
+    3. Use a logic condition to ensure that these compensation servo mixing rules are active only when `MIXER TRANSITION` is activated. You can achieve this by checking the value of 'Flight:MixerTransition Active' in programming tab.
+    4. Add a little roll mixing in tilt motors.
+## Dedicated forward motor 
+- waiting for reports
+
+# Parameter list (Partial List)
+###  Please be aware of what parameter is shared among FW/MC modes and what isn't. 
+## Shared Parameters
+
+- **Timer Overrides**
+- **Outputs [Servo]:**
+  - Servo min-point, mid-point, max-point settings
+- **Motor Configuration:**
+  - motor_pwm_protocol
+  - motor_poles
+- **Servo Configuration:**
+  - servo_protocol
+  - servo_pwm_rate
+- **Board Alignment**
+- ·······
+## Profile-Specific Parameters in VTOL
+- **Mixer Profile**
+    - **Mixer Configuration:**
+        - platform_type
+        - motor_stop_on_low
+        - motor_direction_inverted, and more·······
+    - **Motor Mixing (mmix)**
+    - **Servo Mixing (smix)**
+- **PID Profile**
+  - PIDs for Roll, Pitch, Yaw
+  - PIDs for Navigation Modes
+  - TPA (Throttle PID Attenuation) Settings
+  - Rate Settings
+  - ·······
diff --git a/src/main/common/maths.h b/src/main/common/maths.h
@@ -91,6 +91,7 @@
         )
 #define MIN(a, b) _CHOOSE(<, a, b)
 #define MAX(a, b) _CHOOSE(>, a, b)
+#define SIGN(a) ((a >= 0) ? 1 : -1)
 
 #define _ABS_II(x, var)             \
     ( __extension__ ({              \

diff --git a/src/main/fc/controlrate_profile.c b/src/main/fc/controlrate_profile.c
@@ -44,6 +44,7 @@ void pgResetFn_controlRateProfiles(controlRateConfig_t *instance)
                 .rcMid8 = SETTING_THR_MID_DEFAULT,
                 .rcExpo8 = SETTING_THR_EXPO_DEFAULT,
                 .dynPID = SETTING_TPA_RATE_DEFAULT,
+                .dynPID_on_YAW = SETTING_TPA_ON_YAW_DEFAULT,
                 .pa_breakpoint = SETTING_TPA_BREAKPOINT_DEFAULT,
                 .fixedWingTauMs = SETTING_FW_TPA_TIME_CONSTANT_DEFAULT
             },

diff --git a/src/main/fc/controlrate_profile_config_struct.h b/src/main/fc/controlrate_profile_config_struct.h
@@ -29,6 +29,7 @@ typedef struct controlRateConfig_s {
         uint8_t rcMid8;
         uint8_t rcExpo8;
         uint8_t dynPID;
+        bool dynPID_on_YAW;
         uint16_t pa_breakpoint;                // Breakpoint where TPA is activated
         uint16_t fixedWingTauMs;               // Time constant of airplane TPA PT1-filter
     } throttle;