docs: add "first flight" docs for airspeed scale handling (#25987)

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Silvan Fuhrer <silvan@auterion.com>

docs/en/SUMMARY.md

@@ -61,6 +61,7 @@
     - [Auto-tune](config/autotune_fw.md)
     - [Rate/Attitude Controller Tuning Guide](config_fw/pid_tuning_guide_fixedwing.md)
     - [Altitude/Position Controller Tuning Guide](config_fw/position_tuning_guide_fixedwing.md)
+    - [Airspeed Scale Estimate Handling](config_fw/airspeed_scale_handling.md)
     - [Weight & Altitude Tuning](config_fw/weight_and_altitude_tuning.md)
     - [Trimming Guide](config_fw/trimming_guide_fixedwing.md)
   - [Flying (Basics)](flying/basic_flying_fw.md)

docs/en/advanced_config/airspeed_validation.md

@@ -10,36 +10,13 @@ By default, the [Missing Data](#missing-data-check), [Data Stuck](#data-stuck-ch
 You can configure which checks are active using the [ASPD_DO_CHECKS](#aspd_do_checks_table) parameter.
 :::
 
-## Airspeed in PX4
-
-PX4 handles multiple types of airspeed:
-
-- **IAS (Indicated Airspeed):** The raw measurement from the airspeed sensor, directly influenced by sensor characteristics and installation effects (e.g., pitot-static errors).
-
-- **CAS (Calibrated Airspeed):** IAS corrected for sensor-specific and installation-related errors.
-
-- **EAS (Equivalent Airspeed):** _Not explicitly handled by PX4_ - Calibrated airspeed corrected for compressibility effects.
-  While PX4 does not currently model EAS separately, this correction is negligible at low speeds and altitudes, so EAS is treated as equivalent to CAS for simplicity.
-
-- **TAS (True Airspeed):** CAS adjusted for atmospheric effects such as air pressure and temperature (i.e., altitude and atmospheric conditions).
-
-The standard conversion chain used in PX4 is: `IAS → CAS (= EAS) → TAS`.
-
 ## CAS Scale Estimation
 
-PX4 estimates the IAS to CAS scale (referred to as the CAS scale) during flight using GNSS ground speed and wind estimation.
-To compute the final TAS, standard environment conversions are applied (CAS → TAS).
-
-This CAS scaling plays an important role in keeping the [innovation check](#innovation-check) reliable, since a well-estimated CAS is key to spotting inconsistencies between measured and predicted airspeed.
+Calibrated Airspeed (CAS) is the measured Indicated Airspeed (IAS) scaled to correct for sensor-specific and installation-related errors.
+CAS scaling plays an important role in keeping the [innovation check](#innovation-check) reliable, since a well-estimated CAS is key to spotting inconsistencies between measured and predicted airspeed.
 If the estimated CAS scale is inaccurate, it can mask real airspeed faults or trigger false positives.
 
-If you observe that the CAS scale estimate is consistently off, or if it is converging too slowly, you can manually set it using [ASPD_SCALE_n](#aspd_scale_n_table) (where `n` is the sensor number).
-[ASPD_SCALE_APPLY](#aspd_scale_apply_table) can be used to configure when/if the estimated scale is applied.
-
-::: info
-For a quick manual CAS scale estimate, compare groundspeed minus windspeed (from the [VehicleLocalPosition](../msg_docs/VehicleLocalPosition.md) and [Wind](../msg_docs/Wind.md) messages, respectively) to indicated airspeed values (in the [Airspeed](../msg_docs/Airspeed.md) message).
-The ratio of indicated airspeed to groundspeed minus windspeed can provide a reasonable starting estimate for [ASPD_SCALE_n](#aspd_scale_n_table).
-:::
+If you observe that the CAS scale estimate is consistently off, or if it is converging too slowly, follow the steps outlined in [Airspeed Scale Handling](../config_fw/airspeed_scale_handling.md#recommended-first-flight-process).
 
 ## Validation Checks
 

docs/en/config_fw/airspeed_scale_handling.md

@@ -0,0 +1,104 @@
+# Airspeed Scale Handling
+
+::: info
+This section complements the existing [Airspeed Validation](../advanced_config/airspeed_validation.md) documentation.
+:::
+
+The airspeed scale is used by PX4 to convert the measured airspeed (indicated airspeed) to the calibrated airspeed.
+This scale can be set by [ASPD_SCALE_n](../advanced_config/parameter_reference.md#ASPD_SCALE_1) (where `n` is the sensor number), and logged in [AirspeedWind.msg](../msg_docs/AirspeedWind.md).
+
+Note that the airspeed scale is different from the airspeed sensor offset calibration done on the ground at 0 m/s. The airspeed scale accounts for errors in the airspeed measurement during flight, such as those caused by sensor placement or installation effects.
+
+This topic describes how to set an initial airspeed scale for a new fixed-wing vehicle during its first flight. Correct scale calibration ensures reliable airspeed data, accurate TAS calculation, robust PX4 airspeed validation, and consistent controller performance.
+
+## Airspeed in PX4
+
+PX4 handles multiple types of airspeed:
+
+- **IAS (Indicated Airspeed):** The raw measurement from the airspeed sensor, directly influenced by sensor characteristics and installation effects (e.g., pitot-static errors).
+- **CAS (Calibrated Airspeed):** IAS corrected for sensor-specific and installation-related errors.
+- **EAS (Equivalent Airspeed):** _Not explicitly handled by PX4_ - Calibrated airspeed corrected for compressibility effects.
+  While PX4 does not currently model EAS separately, this correction is negligible at low speeds and altitudes, so EAS is treated as equivalent to CAS for simplicity.
+- **TAS (True Airspeed):** CAS adjusted for atmospheric effects such as air pressure and temperature (i.e., altitude and atmospheric conditions).
+
+The standard conversion chain used in PX4 is: `IAS → CAS (= EAS) → TAS`.
+
+## CAS Scale Estimation
+
+PX4 estimates the IAS to CAS scale (referred to as the CAS scale) during flight using GNSS ground speed and wind estimation.
+To compute the final TAS, standard environment conversions are applied (CAS → TAS).
+
+:::warning Important
+A GNSS is required for scale estimation.
+:::
+
+PX4 uses a two-stage approach to robustly estimate the scale:
+
+1. **Continuous EKF Estimation**: A wind estimator constantly compares your measured airspeed against what it expects based on ground velocity (from GNSS) and estimated wind.
+   If there's a consistent bias, it adjusts the scale estimate.
+   The estimated scale is logged in the `AirspeedWind.msg` as the `tas_scale_raw`.
+2. **Validation**: To ensure robustness, PX4 collects airspeed and ground speed data across 12 different heading segments (every 30°).
+   This averages out wind estimation errors.
+   The validated scale is only updated when the new estimate demonstrably reduces the error between predicted and actual ground speeds across all headings.
+   The validated scale is logged in the `AirspeedWind.msg` as the `tas_scale_validated`.
+
+### Understanding the Scale: Physical Intuition
+
+The CAS scale is essentially a correction factor that accounts for systematic errors in your airspeed sensor installation.
+
+- A scale of 1.0 means your sensor reads perfectly (no correction needed)
+- A scale > 1.0 (e.g., 1.1) means your sensor _under-reads_ by 10%, so measured airspeed (IAS) must be multiplied by 1.1
+- A scale < 1.0 (e.g., 0.9) means your sensor _over-reads_ by ~11%, so measured airspeed (IAS) must be multiplied by 0.9
+
+### What Affects the Airspeed Scale
+
+The primary factor influencing the airspeed scale is **sensor placement**.
+
+Biased readings can be reflected in the scale estimate for pitot tubes installed:
+
+- In regions experiencing disturbed flow (commonly near blunt aircraft noses)
+- Near propellers
+- Under aerodynamic surfaces
+- At an angle with respect to the airflow
+
+### Symptoms of Incorrect Scale
+
+Symptoms of an incorrectly scaled airspeed measurement include:
+
+- Stalling or overspeeding
+- Persistent under- or overestimation of the TAS relative to wind-corrected groundspeed
+- False positives or missed detections in [airspeed innovation checks](../advanced_config/airspeed_validation.md#innovation-check)
+- Degraded tracking of the rate controllers
+
+## Recommended First Flight Process
+
+During the first flight of a new fixed-wing vehicle, allocate time for the CAS scale to converge to a reasonable initial estimate.
+Follow these steps:
+
+1. **Set an Initial Scale**
+
+   Use a conservative starting point: set the CAS scale (`ASPD_SCALE_n`) slightly under 1.0 (for example 0.95).
+   This biases the system toward over-speed rather than under-speed, reducing stall risk.
+
+2. **Perform a Flight**
+
+   After takeoff, place the vehicle in loiter for about 15 minutes to allow the scale estimation to converge.
+
+3. **Check Scale Convergence**
+
+   After the flight, review the estimated scale in logs.
+   Verify that:
+   - `tas_scale_validated` in `AirspeedWind.msg` converged during flight.
+   - `true_airspeed_m_s` (TAS) in [AirspeedValidated.msg](../msg_docs/AirspeedValidated.md) is consistent with groundspeed corrected for wind.
+
+4. **Update the Airframe Configuration**
+
+   If using an [airframe configuration file](../dev_airframes/adding_a_new_frame.md): update `ASPD_SCALE_n`with the estimated CAS scale for future flights.
+   For similar vehicles with similarly mounted sensors, this value is typically a reliable starting point.
+
+::: info
+If you are not able to perform the steps outlined above ...
+
+For a quick manual CAS scale estimate, compare groundspeed minus windspeed (from the [VehicleLocalPosition](../msg_docs/VehicleLocalPosition.md) and [Wind](../msg_docs/Wind.md) messages, respectively) to indicated airspeed values (in the [Airspeed](../msg_docs/Airspeed.md) message).
+The ratio of indicated airspeed to groundspeed minus windspeed can provide a reasonable starting estimate for `ASPD_SCALE_n`.
+:::

docs/en/config_fw/index.md

@@ -3,7 +3,7 @@
 Fixed-wing configuration and calibration follows the same high level steps as other frames: selection of firmware, configuration of the frame including actuator/motor geometry and output mappings, sensor configuration and calibration, configuration of safety and other features, and finally tuning.
 
 ::: info
-This topic is the recommended entry point when performing first-time configuration and calibration of a new multicopter frame.
+This topic is the recommended entry point when performing first-time configuration and calibration of a new fixed-wing frame.
 :::
 
 The main steps are:
@@ -17,3 +17,4 @@ The main steps are:
 
 - [Fixed-wing Altitude/Position Controller Tuning Guide](../config_fw/position_tuning_guide_fixedwing.md)
 - [Fixed-wing Trimming Guide](../config_fw/trimming_guide_fixedwing.md)
+- [Fixed-Wing Airspeed Scale Handling](../config_fw/airspeed_scale_handling.md)