From f5f3394b646c1331004f61a9b42371fa9434292d Mon Sep 17 00:00:00 2001 From: bresch Date: Wed, 18 Mar 2026 15:39:35 +0100 Subject: [PATCH] chore(ekf2): add ground position lock documentation --- docs/en/advanced_config/tuning_the_ecl_ekf.md | 10 ++++++++++ docs/en/releases/main.md | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/en/advanced_config/tuning_the_ecl_ekf.md b/docs/en/advanced_config/tuning_the_ecl_ekf.md index c59d2913f2..a1d2d72e6e 100644 --- a/docs/en/advanced_config/tuning_the_ecl_ekf.md +++ b/docs/en/advanced_config/tuning_the_ecl_ekf.md @@ -406,6 +406,16 @@ With Valid GNSS Data: - **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. +#### Ground Position Lock + +When a vehicle equipped with dead-reckoning sensors (e.g. airspeed for fixed-wing, or optical flow) is sitting on the ground before takeoff, those sensors provide little to no aiding — airspeed and optical flow measurements are unreliable at rest. In this case, the EKF relies on _constant position fusion_ (fusing a synthetic position measurement at the last known position) to prevent the estimate from drifting. However, this is only active when the vehicle is detected as stationary, so handling the vehicle or starting the engine can interrupt it. + +To counter this, [EKF2_POS_LOCK](../advanced_config/parameter_reference.md#EKF2_POS_LOCK) can be enabled to force constant position fusion to run while landed and the global horizontal position has already been initialized. + +::: note +`EKF2_POS_LOCK` has no effect in flight. +::: + ### 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/releases/main.md b/docs/en/releases/main.md index 0370808ba8..1e0f695bdc 100644 --- a/docs/en/releases/main.md +++ b/docs/en/releases/main.md @@ -50,7 +50,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide). ### Estimation -- TBD +- Added [EKF2_POS_LOCK](../advanced_config/parameter_reference.md#EKF2_POS_LOCK) to force constant position fusion while landed, useful for vehicles relying on dead-reckoning sensors (airspeed, optical flow) that provide no aiding on the ground. ### Sensors