From 8e8fd485b953412ab49cacc5fa1b1109e747c883 Mon Sep 17 00:00:00 2001 From: Mahima Yoga Date: Thu, 27 Nov 2025 10:51:54 +0100 Subject: [PATCH] docs: add "first flight" docs for airspeed scale handling (#25987) Co-authored-by: Hamish Willee Co-authored-by: Silvan Fuhrer --- docs/en/SUMMARY.md | 1 + .../en/advanced_config/airspeed_validation.md | 29 +---- docs/en/config_fw/airspeed_scale_handling.md | 104 ++++++++++++++++++ docs/en/config_fw/index.md | 3 +- 4 files changed, 110 insertions(+), 27 deletions(-) create mode 100644 docs/en/config_fw/airspeed_scale_handling.md diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md index 8cbcaa427d..5cf35ff858 100644 --- a/docs/en/SUMMARY.md +++ b/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) diff --git a/docs/en/advanced_config/airspeed_validation.md b/docs/en/advanced_config/airspeed_validation.md index f2cd82ea6a..7b4a708ea3 100644 --- a/docs/en/advanced_config/airspeed_validation.md +++ b/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 diff --git a/docs/en/config_fw/airspeed_scale_handling.md b/docs/en/config_fw/airspeed_scale_handling.md new file mode 100644 index 0000000000..fe70a37b38 --- /dev/null +++ b/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`. +::: diff --git a/docs/en/config_fw/index.md b/docs/en/config_fw/index.md index 4dbc48ecb1..a81760edf6 100644 --- a/docs/en/config_fw/index.md +++ b/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)