diff --git a/docs/en/advanced_config/tuning_the_ecl_ekf.md b/docs/en/advanced_config/tuning_the_ecl_ekf.md index 8a68bc05dc..d2c0ada7fb 100644 --- a/docs/en/advanced_config/tuning_the_ecl_ekf.md +++ b/docs/en/advanced_config/tuning_the_ecl_ekf.md @@ -348,6 +348,60 @@ The `hpos_drift_rate`, `vpos_drift_rate` and `hspd` are calculated over a period Note that `ekf2_gps_drift` is not logged! ::: +#### GNSS Fault Detection + +PX4's GNSS fault detection protects against malicious or erroneous GNSS signals using selective fusion control based on measurement validation. + +The fault detection logic depends on the GPS mode, and also operates differently for horizontal position and altitude measurements. +The mode is set using the [EKF2_GPS_MODE](../advanced_config/parameter_reference.md#EKF2_GPS_MODE) parameter: + +- **Automatic (`0`)** (Default): Assumes that GNSS is generally reliable and is likely to be recovered. + EKF2 resets on fusion timeouts if no other source of position is available. +- **Dead-reckoning (`1`)**: Assumes that GNSS might be lost indefinitely, so resets should be avoided while we have other estimates of position data. + EKF2 may reset if no other sources of position or velocity are available. + If GNSS altitude OR horizontal position data drifts, the system disables fusion of both measurements simultaneously (even if one would still pass validation) and avoids performing resets. + +##### Detection Logic + +Horizontal Position: + +- **Automatic mode**: Horizontal position resets to GNSS data if no other horizontal position source is currently being fused (e.g., Auxiliary Global Position - AGP). +- **Dead-reckoning mode**: Horizontal position resets to GNSS data only if no other horizontal position OR velocity source is currently being fused (e.g., AGP, airspeed, optical flow). + +Altitude: + +- The altitude logic is more complex due to the height reference sensor ([EKF2_HGT_REF](../advanced_config/parameter_reference.md#EKF2_HGT_REF)) parameter, which is typically set to GNSS or baro in GNSS-denied scenarios. +- If height reference is set to baro, GNSS-based height resets are prevented (except when baro fusion fails completely and height reference automatically switches to GNSS). +- When height reference is set to GNSS: +- **Automatic mode**: Resets occur on drifting GNSS altitude measurements. +- **Dead-reckoning mode**: When validation starts failing, the system prevents GNSS altitude resets and labels the GNSS data as faulty. + +##### Faulty GNSS Data During Boot + +The system cannot automatically detect faulty GNSS data during vehicle boot as no baseline comparison exists. + +If GNSS fusion is enabled ([EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL)), operators will observe incorrect positions on maps and should disable GNSS fusion, then manually set the correct position via ground control station. +The global position gets corrected, and if [SENS_BAR_AUTOCAL](../advanced_config/parameter_reference.md#SENS_BAR_AUTOCAL) was enabled, baro offsets are automatically adjusted (through bias correction, not parameter changes). + +##### Enabling GNSS Fusion Mid-Flight + +With Faulty GNSS Data: + +- **Automatic mode**: Vehicle will reset to faulty position - potentially dangerous. +- **Dead-reckoning mode**: Large measurement differences cause GNSS rejection and fault detection activation. + +With Valid GNSS Data: + +- **Automatic mode**: Vehicle will reset to GNSS measurements. +- **Dead-reckoning mode**: If estimated position/altitude is close enough to measurements, fusion resumes; if too far apart, data gets labeled as faulty. + +##### Notes + +- **Dual Detection**: Horizontal and altitude checks run completely separately but both lead to the same result when triggered - all GNSS fusion gets disabled. +- **Recovery**: Only the specific check that labeled data as invalid can re-enable fusion. +- **Alternative Sources**: Dead-reckoning mode provides enhanced protection by requiring absence of alternative navigation sources before allowing resets. +- **Boot Vulnerability**: Initial faulty GNSS data cannot be detected automatically; requires operator intervention and manual position correction. + ### Range Finder [Range finder](../sensor/rangefinders.md) distance to ground is used by a single state filter to estimate the vertical position of the terrain relative to the height datum. diff --git a/docs/en/sensor/barometer.md b/docs/en/sensor/barometer.md index 46f77a8d8b..598bdc3d11 100644 --- a/docs/en/sensor/barometer.md +++ b/docs/en/sensor/barometer.md @@ -30,17 +30,51 @@ If needed, you can: - Change the selection order of barometers using the [CAL_BAROx_PRIO](../advanced_config/parameter_reference.md#CAL_BARO0_PRIO) parameters for each barometer. - Disable a barometer by setting its [CAL_BAROx_PRIO](../advanced_config/parameter_reference.md#CAL_BARO0_PRIO) value to `0`. -## Calibration +## Baro Auto-Calibration (Developers) -Barometers don't require calibration. +::: tip +This section documents the automated calibration mechanisms that ensure accurate altitude measurements throughout flight operations. +It is intended primarily for a developer audience who want to understand the underlying mechanisms. +::: - +The system implements two complementary calibration approaches that work together to maintain altitude measurement precision. +Both calibrations are initiated at the beginning after a system boot. +Relative calibration is performed first, followed by GNSS-barometric calibration. -## Developer Information +### Relative Calibration + +Relative baro calibration is **always enabled** and operates automatically during system initialization. +This calibration establishes offset corrections for all secondary baro sensors relative to the primary (selected) sensor. + +This calibration: + +- Eliminates altitude jumps when switching between baro sensors during flight. +- Ensures consistent altitude readings across all available baro sensors. +- Maintains seamless sensor redundancy and failover capability. + +### GNSS-Baro Calibration + +::: info +GNSS-baro calibration requires an operational GNSS receiver with vertical accuracy (EPV) ≤ 8 meters. +Relative calibration must already have completed. +::: + +GNSS-baro calibration adjusts baro sensor offsets to align with absolute altitude measurements from the GNSS receiver. +This calibration is controlled by the [SENS_BAR_AUTOCAL](../advanced_config/parameter_reference.md#SENS_BAR_AUTOCAL) parameter (enabled by default). + +The algorithm monitors GNSS quality, collects altitude differences over a 2-second filtered window, and verifies stability within 4m tolerance. +Once stable, it uses binary search to calculate pressure offsets that align baro altitude with GNSS altitude (0.1m precision), then applies the offset to all sensors and saves the parameters. + +Notes: + +- **EKF Independence**: GNSS-baro calibration operates independently of EKF2 altitude fusion settings. +- **Execution Timing**: Calibration runs even when [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) altitude fusion is disabled. +- **One-Time Process**: Each calibration session completes once per system startup. +- **Persistence**: Calibration offsets are saved to parameters and persist across reboots. +- **Faulty GNSS Vulnerability**: If GNSS data is faulty during boot, the calibration will use incorrect altitude reference. + See [Faulty GNSS Data During Boot](../advanced_config/tuning_the_ecl_ekf.md#faulty-gnss-data-during-boot) for mitigation strategies. + +## See Also - [Baro driver source code](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/barometer) - [Modules Reference: Baro (Driver)](../modules/modules_driver_baro.md) documentation. diff --git a/src/modules/ekf2/params_gnss.yaml b/src/modules/ekf2/params_gnss.yaml index b8168e494a..319846316d 100644 --- a/src/modules/ekf2/params_gnss.yaml +++ b/src/modules/ekf2/params_gnss.yaml @@ -20,8 +20,8 @@ parameters: EKF2_GPS_MODE: description: short: Fusion reset mode - long: 'Automatic: reset on fusion timeout if no other source of position is available - Dead-reckoning: reset on fusion timeout if no source of velocity is available' + long: 'Automatic: reset on fusion timeout if no other source of position is available. + Dead-reckoning: reset on fusion timeout if no source of velocity is available.' type: enum values: 0: Automatic