fw gain compression: add docs

docs/en/SUMMARY.md

@@ -56,6 +56,8 @@
     - [DJI F450 (CUAV v5 nano)](frames_multicopter/dji_f450_cuav_5nano.md)
 
 - [Planes (Fixed-Wing)](frames_plane/index.md)
+  - [Features](features_fw/index.md)
+    - [Gain compression](features_fw/gain_compression.md)
   - [Assembly](assembly/assembly_fw.md)
   - [Config/Tuning](config_fw/index.md)
     - [Auto-tune](config/autotune_fw.md)

docs/en/config_fw/pid_tuning_guide_fixedwing.md

@@ -17,6 +17,8 @@ Manual tuning is recommended for frames where autotuning does not work, or where
 - Excessive gains (and rapid servo motion) can violate the maximum forces of your airframe - increase gains carefully.
 - Roll and pitch tuning follow the same sequence.
   The only difference is that pitch is more sensitive to trim offsets, so [trimming](../config_fw/trimming_guide_fixedwing.md) has to be done carefully and integrator gains need more attention to compensate this.
+- Disable automatic [gain compression](../features_fw/gain_compression.md) ([FW_GC_EN](../advanced_config/parameter_reference.md#FW_GC_EN)) to avoid over-tuning.
+  Remember to re-enable it when tuning is done.
 
 ## Establishing the Airframe Baseline
 

docs/en/features_fw/gain_compression.md

@@ -0,0 +1,24 @@
+# Gain compression
+
+<Badge type="tip" text="main (planned for: PX4 v1.17)" />
+
+Automatic gain compression reduces the gains of the angular-rate PID whenever oscillations are detected.
+It monitors the angular-rate controller output through a band-pass filter to identify these oscillations.
+
+This approach is a safe adaptive mechanism for stable aircraft: the PID gains remain unchanged when no oscillations are present, they are never increased beyond their nominal values, and they are bounded by a minimum limit.
+
+Gain compression can help prevent actuator damage and even loss of the vehicle in cases such as airspeed-sensor failure (loss of airspeed scaling) or in-flight changes in dynamics (e.g.: CG shifts, inertia changes), or other failures that could cause the angular-rate loop to become oscillatory.
+
+![Gain compression diagram](../../assets/config/fw/gain_compression_diagram.png)
+
+## Usage
+
+Gain compression is enabled by default ([FW_GC_EN](../advanced_config/parameter_reference.md#FW_GC_EN)).
+
+It should be disabled during fixed wing [manual tuning](../config_fw/pid_tuning_guide_fixedwing.md) to avoid over-tuning.
+It does not need to be disabled when autotuning.
+
+## Parameters
+
+- [FW_GC_EN](../advanced_config/parameter_reference.md#FW_GC_EN)
+- [FW_GC_GAIN_MIN](../advanced_config/parameter_reference.md#FW_GC_GAIN_MIN)

docs/en/features_fw/index.md

@@ -0,0 +1,5 @@
+# Fixedwing-Specific Features
+
+This section lists features that are specific to (or customised for) fixed-wings:
+
+- [Gain Compression](../features_fw/gain_compression.md)

docs/en/releases/main.md

@@ -93,6 +93,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
 
 - [Fixed Wing Takeoff mode](../flight_modes_fw/takeoff.md) will now keep climbing with level wings on position loss.
   A target takeoff waypoint can be set to control takeoff course and loiter altitude. ([PX4-Autopilot#25083](https://github.com/PX4/PX4-Autopilot/pull/25083)).
+- Automatically suppress angular rate oscillations using [Gain compression](../features_fw/gain_compression.md). ([PX4-Autopilot#25840: FW rate control: add gain compression algorithm](https://github.com/PX4/PX4-Autopilot/pull/25840))
 
 ### Rover