Document fixed wing control smoothing and course lock on level (INAV 10.0)

docs/05-core-features/flight-modes-navigation.mdx

@@ -95,7 +95,7 @@ Max. navigation dive angle | [nav_fw_dive_angle](https://github.com/iNavFlight/i
 Cruise Yaw Rate | [nav_cruise_yaw_rate](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_cruise_yaw_rate) | Max YAW rate when NAV COURSE HOLD/CRUISE mode is enabled. Set to 0 to disable on fixed wing (Note: On multirotor setting to 0 will disable Course Hold/Cruise mode completely) [dps]
 Loiter radius | [nav_fw_loiter_radius](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_loiter_radius) = 5000 | The radius of the orbit that will be used in Poshold. Values are in cm.
 Loiter direction | [fw_loiter_direction](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#fw_loiter_direction) | The direction the airplane will turn for the loiter orbit. It can turn either left or right.
-Control smoothness | [nav_fw_control_smoothness](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_control_smoothness) = 0 | How smoothly the autopilot controls the airplane to correct the navigation error. The max value is 9 and the min is 0. The default is 0.
+Control smoothness | [nav_fw_control_smoothness](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_control_smoothness) = 0 | How gently the autopilot enters a manoeuvre, 0 to 9. From INAV 10.0 the roll axis eases abrupt bank changes over `value × 100 ms` and adds no lag in steady flight, see [Fixed Wing Control Smoothing](../06-advanced-features/fixed-wing-control-smoothing.mdx).
 Soaring mode stop | [nav_fw_soaring_motor_stop](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_soaring_motor_stop) | When enabled, stops the motor when [Soaring mode](./flight-modes-standard.mdx#soaring-fw) is enabled.
 Soaring Mode Pitch Deadband | [nav_fw_soaring_pitch_deadband](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_soaring_pitch_deadband) | Pitch Angle deadband when soaring mode is enabled (deg). Angle mode is inactive within the deadband allowing pitch to free float whilst soaring.
 Altitude Control Response Factor | [nav_fw_alt_control_response](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_alt_control_response) | Adjusts the deceleration response of fixed wing altitude control as the target altitude is approached. Decrease value to help avoid overshooting the target altitude. Default is 40.
@@ -332,6 +332,9 @@ If the mode is enabled in conjunction with NAV ALTHOLD, the current altitude wil
 Altitude can be adjusted as usual via the pitch stick for a fixed wing or the throttle stick for a multirotor.
 ANGLE mode is automatically activated so the craft will auto level and the heading will also be held on both platforms.
 
+From INAV 10.0 a fixed wing locks its new course only once it has rolled out level after a stick input or a banked mode entry, instead of the moment the stick is released.
+This avoids overshooting the course during the level-off and is controlled by [nav_cruise_lock_on_level](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_cruise_lock_on_level), see [Course lock on level](../06-advanced-features/fixed-wing-control-smoothing.mdx#course-lock-on-level).
+
 ## NAV CRUISE
 
 This mode is equivalent to the combination of [NAV COURSE HOLD](./flight-modes-navigation.mdx#nav-course-hold) and [NAV ALTHOLD](./flight-modes-navigation.mdx#nav-althold) 
@@ -419,7 +422,7 @@ These setting can be found in the _Advanced Tuning Tab_ or the _CLI_.
 * [nav_fw_bank_angle](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_bank_angle) - The sustained bank that all turn and loiter radii are planned for, so a higher value gives tighter turns.
 From INAV 10.0 this is a planning target rather than a hard limit, see [Fixed Wing Waypoint Turns](../06-advanced-features/fixed-wing-waypoint-turns.mdx#what-nav_fw_bank_angle-means-now).
 Set it to the bank your plane can hold comfortably and continuously.
-* [nav_fw_control_smoothness](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_control_smoothness) - Lower values can produce a more abrupt banking motion, but will also allow the plane to react faster to navigation, course, and heading commands.
+* [nav_fw_control_smoothness](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_control_smoothness) - Shapes how gently the plane rolls into a new leg. From INAV 10.0 it only acts on the start of a manoeuvre and no longer delays steady tracking, see [Fixed Wing Control Smoothing](../06-advanced-features/fixed-wing-control-smoothing.mdx).
 * [nav_use_fw_yaw_control](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_use_fw_yaw_control) - If your plane has a form of yaw control **e.g. Rudder or Differential Thrust**, this setting allows the plane to yaw as well as bank when making a turn.
 A lower `nav_fw_bank_angle` (35°) should be used, for a flatter turn.
 * [nav_fw_cruise_thr](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_cruise_thr) - Waypoint overshoot is more likely to occur if the plane is holding a higher velocity, especially if it is traveling on a down-wind or lateral leg before the turn.

docs/06-advanced-features/fixed-wing-control-smoothing.mdx

@@ -0,0 +1,98 @@
+---
+title: Fixed Wing Control Smoothing
+description: What nav_fw_control_smoothness does in INAV 10.0, how to choose a value, and the related course lock behaviour
+---
+
+`nav_fw_control_smoothness` decides how gently the autopilot moves a plane when a navigation mode asks for a new bank or pitch.
+It has been in INAV for a long time, but INAV 10.0 changed how the roll axis works, so the setting deserves a fresh look even if you have used it before.
+
+:::note
+This page is about fixed wing only.
+Multicopters do not use this setting.
+:::
+
+## What the setting does
+
+[nav_fw_control_smoothness](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_control_smoothness) takes a value from `0` to `9`.
+The default is `0`.
+It acts on two things:
+
+- **Roll.** When a navigation mode suddenly asks for a different bank angle, the change is eased in over a short window instead of being applied at once.
+  The window is `100 ms` per step, so `3` gives `300 ms` and `9` gives the maximum of `900 ms`.
+  At `0` the roll command is passed straight through.
+- **Pitch.** The pitch command is run through a low-pass filter whose cut-off drops as the value rises.
+  This part is unchanged from earlier versions.
+
+The throttle correction that follows pitch has its own knob, [nav_fw_pitch2thr_smoothing](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_pitch2thr_smoothing), and is not affected by this setting.
+
+## How the roll easing works
+
+Up to INAV 9.x the roll command was low-pass filtered.
+That gave a soft feel, but the filter was always in the loop: every course correction was delayed, including the small ones during steady tracking, and the delay grew with the setting.
+
+From INAV 10.0 the roll axis uses a triggered S-curve instead.
+The easing only starts when the commanded bank changes abruptly — a jump of more than 20 % of your configured roll rate from one navigation loop to the next.
+Typical triggers are:
+
+- A new leg at a waypoint.
+- Engaging RTH, POSHOLD or a waypoint mission from level flight.
+- Releasing the roll or yaw stick in COURSE HOLD or CRUISE.
+- Switching from a banked turn into another navigation mode.
+
+From that moment the command follows a smooth S-shaped ramp from where it was to where the autopilot wants it, over the configured window.
+Once the window has elapsed the command is passed 1:1 again.
+The window does not restart if the target keeps moving during the ramp, so the plane can never get stuck in a permanently damped state.
+
+In practice this means the setting shapes the *start* of a manoeuvre and stays out of the way afterwards.
+Steady course tracking, holding a loiter or following a leg is not delayed at any value.
+
+:::info
+The [coordinated waypoint turns](./fixed-wing-waypoint-turns.mdx) introduced in INAV 10.0 use the same window when they plan their roll-in and roll-out.
+Raising `nav_fw_control_smoothness` therefore makes waypoint corners and loiter entries start slightly earlier and roll more gently as well.
+:::
+
+## Choosing a value
+
+There is no airframe-specific magic here.
+Because the easing is purely time based, a plane whose natural roll response is slower than the window will simply not notice it.
+Start with the default and increase in steps if a manoeuvre entry feels too abrupt:
+
+| Value | Window | Typical use |
+| --- | --- | --- |
+| `0` | off | Small, agile planes and wings. The default. |
+| `2` – `4` | 200 – 400 ms | Most sport and FPV planes. Softens RTH engage and stick release without a visible delay. |
+| `5` – `7` | 500 – 700 ms | Larger or heavier models, planes with slow servos. |
+| `8` – `9` | 800 – 900 ms | Big, structurally sensitive airframes such as large gliders or twins with a lot of wing loading. |
+
+The setting can be changed in flight with the *Control Smoothness Adjustment* function on the Configurator's Adjustments tab, and the current value can be shown on the OSD with the `OSD_NAV_FW_CONTROL_SMOOTHNESS` element (labelled `CTL S`).
+That makes it easy to compare values on the same flight.
+
+:::tip
+If you carried a high value over from INAV 9.x because navigation felt twitchy in steady flight, try a lower value now.
+The steady-state lag that made higher values attractive is gone; what remains is the entry shaping, and a plane that felt fine at `7` before often flies just as well at `3` or `4`.
+:::
+
+## Course lock on level
+
+In COURSE HOLD and CRUISE the plane holds whatever course was current when you last let go of the sticks.
+A plane that is still banked at that moment keeps turning while it levels off, so locking the course right at stick release means it ends up pointing past the locked course and has to turn back to it.
+
+From INAV 10.0 [nav_cruise_lock_on_level](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_cruise_lock_on_level) waits for the roll-out instead and is `ON` by default.
+The course is only locked once the bank is below 10°; until then the target simply follows the actual ground course.
+This applies to all three ways a course can be locked:
+
+- Releasing the roll stick.
+- Releasing the yaw stick.
+- Entering COURSE HOLD or CRUISE while already banked, for example switching out of an RTH turn.
+
+The result is that the course locks where the plane has effectively stopped turning, with no overshoot and no reverse correction.
+If the plane does not get level within 2.5 s, for example in strong turbulence, the course is locked anyway so the mode can never hang waiting for a roll-out.
+Set it to `OFF` to get the legacy behaviour, where the course is locked as soon as the sticks are centred.
+Multicopter course hold is not affected either way.
+
+## Related settings
+
+- [nav_fw_control_smoothness](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_control_smoothness) — the smoothing level described on this page, `0` to `9`.
+- [nav_cruise_lock_on_level](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_cruise_lock_on_level) — lock the COURSE HOLD / CRUISE course only once level, `ON` by default.
+- [nav_fw_pitch2thr_smoothing](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_fw_pitch2thr_smoothing) — separate smoothing for the pitch-to-throttle correction.
+- [nav_cruise_yaw_rate](https://github.com/iNavFlight/inav/blob/master/docs/Settings.md#nav_cruise_yaw_rate) — how fast the course can be changed with the sticks in COURSE HOLD / CRUISE.

docs/07-pid-tuning/navigation-pid-tuning-fw.mdx

@@ -195,7 +195,7 @@ Navigation testing should **also** be done in windier conditions, to ensure yaw
 - `nav_fw_pos_hdg_i` - When used sparingly, it can filter-out heading target drift.
 - `nav_fw_pos_hdg_d` - Can smooth abrupt heading irregularity. But better suited to aircraft that have a means of yaw control.
 - `heading_hold_rate_limit` - Limits the yaw induced rotation rate the HEADING*HOLD controller can request from PID controller inner
-  loop. It's independent from manual yaw rate and only active when HEADING_HOLD NAV flight modes are in use. \_The default value is more suited to copters, and should be used cautiously on planes that have yaw control, if `nav_fw_control_smoothness` is default or set below 7.*
+  loop. It's independent from manual yaw rate and only active when HEADING_HOLD NAV flight modes are in use. \_The default value is more suited to copters, and should be used cautiously on planes that have yaw control, if [`nav_fw_control_smoothness`](../06-advanced-features/fixed-wing-control-smoothing.mdx) is default or set below 7.*
 - `nav_cruise_yaw_rate` - Sets the yaw rotation rate in degrees that the airplane can be commanded via stick input, while in _Cruise/CourseHold_ modes.
 - `fw_yaw_iterm_freeze_bank_angle` - When enabled, it can help reduce the effect of the rudder counteracting aileron bank turns, by reducing yaw i-term error accumulation. It is only used for ANGLE, HORIZON or ACRO modes. It is not active in navigation modes, unless TURN ASSIST is disabled.