diff --git a/en/SUMMARY.md b/en/SUMMARY.md
index 1123c1148efc..592a630a9e4a 100644
--- a/en/SUMMARY.md
+++ b/en/SUMMARY.md
@@ -388,7 +388,7 @@
- [PX4 Ethernet Setup](advanced_config/ethernet_setup.md)
- [Standard Configuration](config/index.md)
- [Advanced Configuration](advanced_config/index.md)
- - [ECL/EKF Overview & Tuning](advanced_config/tuning_the_ecl_ekf.md)
+ - [Using PX4's Navigation Filter (EKF2)](advanced_config/tuning_the_ecl_ekf.md)
- [Finding/Updating Parameters](advanced_config/parameters.md)
- [Full Parameter Reference](advanced_config/parameter_reference.md)
diff --git a/en/_sidebar.md b/en/_sidebar.md
index 6e9da93cf4b5..5acbb43431ed 100644
--- a/en/_sidebar.md
+++ b/en/_sidebar.md
@@ -384,7 +384,7 @@
- [PX4 Ethernet Setup](/advanced_config/ethernet_setup.md)
- [Standard Configuration](/config/index.md)
- [Advanced Configuration](/advanced_config/index.md)
- - [ECL/EKF Overview & Tuning](/advanced_config/tuning_the_ecl_ekf.md)
+ - [Using PX4's Navigation Filter (EKF2)](/advanced_config/tuning_the_ecl_ekf.md)
- [Finding/Updating Parameters](/advanced_config/parameters.md)
- [Full Parameter Reference](/advanced_config/parameter_reference.md)
diff --git a/en/advanced/computer_vision.md b/en/advanced/computer_vision.md
index a8c5c1dd324f..a87182f6b918 100644
--- a/en/advanced/computer_vision.md
+++ b/en/advanced/computer_vision.md
@@ -28,7 +28,7 @@ For information about MoCap see:
- [External Position Estimation](../ros/external_position_estimation.md)
- [Flying with Motion Capture (VICON, NOKOV, Optitrack)](../tutorials/motion-capture.md)
-- [EKF > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
+- [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
## Visual Inertial Odometry (VIO)
@@ -43,7 +43,7 @@ One difference between VIO and [MoCap](#motion-capture) is that VIO cameras/IMU
For information about configuring VIO on PX4 see:
-- [EKF > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
+- [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
- [T265 Setup guide](../peripherals/camera_t265_vio.md)
## Optical Flow
@@ -53,7 +53,7 @@ For information about configuring VIO on PX4 see:
For information about optical flow see:
- [Optical Flow](../sensor/optical_flow.md)
-- [EKF > Optical Flow](../advanced_config/tuning_the_ecl_ekf.md#optical-flow)
+- [Using PX4's Navigation Filter (EKF2) > Optical Flow](../advanced_config/tuning_the_ecl_ekf.md#optical-flow)
## Comparisons
diff --git a/en/advanced_config/index.md b/en/advanced_config/index.md
index 919c6acaefa3..71d8459ce75f 100644
--- a/en/advanced_config/index.md
+++ b/en/advanced_config/index.md
@@ -9,7 +9,7 @@ This topic lists configuration topics that are not particularly vehicle specific
## Feature configuration
-- [ECL/EKF Overview & Tuning](../advanced_config/tuning_the_ecl_ekf.md)
+- [Using PX4's Navigation Filter (EKF2)](../advanced_config/tuning_the_ecl_ekf.md)
- [Flight Termination Configuration](../advanced_config/flight_termination.md)
- [Land Detector Configuration](../advanced_config/land_detector.md)
- [Prearm/Arm/Disarm Configuration](../advanced_config/prearm_arm_disarm.md)
diff --git a/en/advanced_config/static_pressure_buildup.md b/en/advanced_config/static_pressure_buildup.md
index 645951b81ddf..343d7c2b2559 100644
--- a/en/advanced_config/static_pressure_buildup.md
+++ b/en/advanced_config/static_pressure_buildup.md
@@ -34,7 +34,7 @@ Aim for a barometer altitude drop of less than 2 metres at maximum horizontal sp
## Dynamic Calibration
After modifying the hardware, you can then use the [EKF2_PCOEF\_\*](../advanced_config/parameter_reference.md#EKF2_PCOEF_XN) parameters to tune for expected barometer variation based on relative air velocity.
-For more information see [ECL/EKF Overview & Tuning > Correction for Static Pressure Position Error](../advanced_config/tuning_the_ecl_ekf.md#correction-for-static-pressure-position-error).
+For more information see [Using PX4's Navigation Filter (EKF2) > Correction for Static Pressure Position Error](../advanced_config/tuning_the_ecl_ekf.md#correction-for-static-pressure-position-error).
::: info
The approach works well if the relationship between the error due to static pressure and the velocity varies linearly.
diff --git a/en/advanced_config/tuning_the_ecl_ekf.md b/en/advanced_config/tuning_the_ecl_ekf.md
index e59bac38da5a..3223079b2ad2 100644
--- a/en/advanced_config/tuning_the_ecl_ekf.md
+++ b/en/advanced_config/tuning_the_ecl_ekf.md
@@ -1,23 +1,27 @@
-# Using the ECL EKF
+# Using PX4's Navigation Filter (EKF2)
-This tutorial answers common questions about use of the ECL EKF algorithm.
+This tutorial answers common questions about use of the EKF algorithm used for navigation.
:::tip
-The [PX4 State Estimation Overview](https://youtu.be/HkYRJJoyBwQ) video from the _PX4 Developer Summit 2019_ (Dr. Paul Riseborough) provides an overview of the estimator, and additionally describes both the major changes from 2018/2019, and the expected improvements through 2020.
+The [PX4 State Estimation Overview](https://youtu.be/HkYRJJoyBwQ) video from the _PX4 Developer Summit 2019_ (Dr. Paul Riseborough) provides an overview of the estimator, and additionally describes both the major changes from 2018/2019, major changes and improvements were added since then.
:::
-## What is the ECL EKF?
+## Overview
-The Estimation and Control Library (ECL) uses an Extended Kalman Filter (EKF) algorithm to process sensor measurements and provide an estimate of the following states:
+PX4's Navigation filter uses an Extended Kalman Filter (EKF) algorithm to process sensor measurements and provide an estimate of the following states:
-- Quaternion defining the rotation from North, East, Down local earth frame to X, Y, Z body frame
+- Quaternion defining the rotation from North, East, Down local navigation frame to X, Y, Z body frame
- Velocity at the IMU - North, East, Down (m/s)
-- Position at the IMU - North, East, Down (m)
-- IMU delta angle bias estimates - X, Y, Z (rad)
-- IMU delta velocity bias estimates - X, Y, Z (m/s)
+- Position at the IMU - Latitude (rad), Longitude (rad), Altitude (m)
+- IMU gyro bias estimates - X, Y, Z (rad/s)
+- IMU accelerometer bias estimates - X, Y, Z (m/s2)
- Earth Magnetic field components - North, East, Down \(gauss\)
- Vehicle body frame magnetic field bias - X, Y, Z \(gauss\)
- Wind velocity - North, East \(m/s\)
+- Terrain altitude (m)
+
+To improve stability, an "error-state" formulation is implemented
+This is especially relevant when estimating the uncertainty of a rotation which is a 3D vector (tangent space of SO(3)).
The EKF runs on a delayed 'fusion time horizon' to allow for different time delays on each measurement relative to the IMU.
Data for each sensor is FIFO buffered and retrieved from the buffer by the EKF to be used at the correct time.
@@ -27,16 +31,28 @@ A complementary filter is used to propagate the states forward from the 'fusion
The time constant for this filter is controlled by the [EKF2_TAU_VEL](../advanced_config/parameter_reference.md#EKF2_TAU_VEL) and [EKF2_TAU_POS](../advanced_config/parameter_reference.md#EKF2_TAU_POS) parameters.
::: info
-The 'fusion time horizon' delay and length of the buffers is determined by the largest of the `EKF2_*_DELAY` parameters.
-If a sensor is not being used, it is recommended to set its time delay to zero.
+The 'fusion time horizon' delay and length of the buffers is determined by [EKF2_DELAY_MAX](../advanced_config/parameter_reference.md#EKF2_DELAY_MAX).
+This value should be at least as large as the longest delay `EKF2\_\*\_DELAY`.
Reducing the 'fusion time horizon' delay reduces errors in the complementary filter used to propagate states forward to current time.
:::
+The EKF uses the IMU data for state prediction only.
+IMU data is not used as an observation in the EKF derivation.
+The algebraic equations for the covariance prediction and measurement jacobians are derived using [SymForce](https://symforce.org/) and can be found here: [Symbolic Derivation](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/ekf2/EKF/python/ekf_derivation/derivation.py).
+Covariance update is done using the [Joseph Stabilized form](https://en.wikipedia.org/wiki/Kalman_filter#Deriving_the_posteriori_estimate_covariance_matrix) to improve numerical stability and allow conditional update of independent states.
+
+### Precisions about the position output
+
+The position is estimated as latitude, longitude and altitude and the INS integration is performed using the WGS84 ellipsoid mode.
+However, the position uncertainty is defined in the local navigation frame at the current position (i.e.: NED error in meters).
+
The position and velocity states are adjusted to account for the offset between the IMU and the body frame before they are output to the control loops.
+
The position of the IMU relative to the body frame is set by the `EKF2_IMU_POS_X,Y,Z` parameters.
-The EKF uses the IMU data for state prediction only. IMU data is not used as an observation in the EKF derivation.
-The algebraic equations for the covariance prediction, state update and covariance update were derived using the Matlab symbolic toolbox and can be found here: [Matlab Symbolic Derivation](https://github.com/PX4/PX4-ECL/blob/master/EKF/matlab/scripts/Terrain%20Estimator/GenerateEquationsTerrainEstimator.m).
+In addition to the global position estimate in latitude/longitude/altitude, the filter also provides a local position estimate (NED in meters) by projecting the global position estimate using an [azimuthal_equidistant_projection](https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection) centred on an arbitrary origin.
+This origin is automatically set when global position measurements are fused but can also be specified manually.
+If no global position information is provided, only the local position is available and the INS integration is performed on a spherical Earth.
## Running a Single EKF Instance
@@ -118,7 +134,8 @@ The EKF has different modes of operation that allow for different combinations o
On start-up the filter checks for a minimum viable combination of sensors and after initial tilt, yaw and height alignment is completed, enters a mode that provides rotation, vertical velocity, vertical position, IMU delta angle bias and IMU delta velocity bias estimates.
This mode requires IMU data, a source of yaw (magnetometer or external vision) and a source of height data.
-This minimum data set is required for all EKF modes of operation. Other sensor data can then be used to estimate additional states.
+This minimum data set is required for all EKF modes of operation.
+Other sensor data can then be used to estimate additional states.
### IMU
diff --git a/en/computer_vision/motion_capture.md b/en/computer_vision/motion_capture.md
index 76a40c66cf3b..938a97b5bb08 100644
--- a/en/computer_vision/motion_capture.md
+++ b/en/computer_vision/motion_capture.md
@@ -16,4 +16,4 @@ For information about MoCap see:
- [Using Vision or Motion Capture Systems for Position Estimation](../ros/external_position_estimation.md).
- [Flying with Motion Capture (VICON, NOKOV, Optitrack)](../tutorials/motion-capture.md).
-- [EKF > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
+- [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
diff --git a/en/computer_vision/visual_inertial_odometry.md b/en/computer_vision/visual_inertial_odometry.md
index 6871cde03f55..96f9a10c8a9f 100644
--- a/en/computer_vision/visual_inertial_odometry.md
+++ b/en/computer_vision/visual_inertial_odometry.md
@@ -77,7 +77,7 @@ The following parameters must be set to use external position information with E
These can be set in _QGroundControl_ > **Vehicle Setup > Parameters > EKF2** (remember to reboot the flight controller in order for parameter changes to take effect).
-For more detailed/additional information, see: [ECL/EKF Overview & Tuning > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system).
+For more detailed/additional information, see: [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system).
@@ -167,4 +167,4 @@ This topic also explains how to configure VIO for use with the LPE Estimator (de
## Further Information
-- [ECL/EKF Overview & Tuning > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
+- [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
diff --git a/en/debug/system_wide_replay.md b/en/debug/system_wide_replay.md
index 6a7d48b306a7..e808afd64c47 100644
--- a/en/debug/system_wide_replay.md
+++ b/en/debug/system_wide_replay.md
@@ -118,8 +118,8 @@ When parameters are overridden, corresponding parameter changes in the log are n
This is a specialization of the system-wide replay for fast EKF2 replay.
::: info
-The recording and replay of flight logs with [multiple EKF instances](../advanced_config/tuning_the_ecl_ekf.md#running-multiple-ekf-instances) is not supported.
-To enable recording for EKF replay you must set the parameters to enable a [single EKF instance](../advanced_config/tuning_the_ecl_ekf.md#running-a-single-ekf-instance).
+The recording and replay of flight logs with [multiple EKF2 instances](../advanced_config/tuning_the_ecl_ekf.md#running-multiple-ekf-instances) is not supported.
+To enable recording for EKF replay you must set the parameters to enable a [single EKF2 instance](../advanced_config/tuning_the_ecl_ekf.md#running-a-single-ekf-instance).
:::
In EKF2 mode, the replay will automatically create the ORB publisher rules described above.
diff --git a/en/flying/pre_flight_checks.md b/en/flying/pre_flight_checks.md
index d7f4f47b621b..a3166ed168f5 100644
--- a/en/flying/pre_flight_checks.md
+++ b/en/flying/pre_flight_checks.md
@@ -47,7 +47,7 @@ Note that the [Arming Check Report](#qgc-arming-check-report) is a much easier w
## EKF Preflight Checks/Errors
-This sections lists errors, with associated checks and parameters, that are reported by the [EKF](../advanced_config/tuning_the_ecl_ekf.md) (and propagate to _QGroundControl_).
+This sections lists errors, with associated checks and parameters, that are reported by [EKF2](../advanced_config/tuning_the_ecl_ekf.md) (and propagate to _QGroundControl_).
These are provided for information only (the QGC Arming Checks UI is the best way to get error and solution information).
#### PREFLIGHT FAIL: EKF HIGH IMU ACCEL BIAS
diff --git a/en/flying/terrain_following_holding.md b/en/flying/terrain_following_holding.md
index 927427e67bf9..fb4cc842f616 100644
--- a/en/flying/terrain_following_holding.md
+++ b/en/flying/terrain_following_holding.md
@@ -24,7 +24,7 @@ As the distance to ground changes, the altitude setpoint adjusts to keep the hei
At higher altitudes (when the estimator reports that the distance sensor data is invalid) the vehicle switches to *altitude following*, and will typically fly at a near-constant height above mean sea level (AMSL) using an absolute height sensor for altitude data.
::: info
-More precisely, the vehicle will use the available selected sources of altitude data as defined [here](../advanced_config/tuning_the_ecl_ekf.md#height).
+More precisely, the vehicle will use the available selected sources of altitude data as defined in [Using PX4's Navigation Filter (EKF2) > Height](../advanced_config/tuning_the_ecl_ekf.md#height).
:::
Terrain following is enabled by setting [MPC_ALT_MODE](../advanced_config/parameter_reference.md#MPC_ALT_MODE) to `1`.
diff --git a/en/gps_compass/rtk_gps.md b/en/gps_compass/rtk_gps.md
index b7a4e322e07d..a49acacf8e61 100644
--- a/en/gps_compass/rtk_gps.md
+++ b/en/gps_compass/rtk_gps.md
@@ -212,7 +212,7 @@ For example, you can decrease [EKF2_GPS_V_NOISE](../advanced_config/parameter_re
#### Dual Receivers
A second GPS receiver can be used as a backup (either RTK or non RTK).
-See the [EKF2 GPS Configuration](../advanced_config/tuning_the_ecl_ekf.md#gps) section.
+See the [Using PX4's Navigation Filter (EKF2) > GPS](../advanced_config/tuning_the_ecl_ekf.md#gps) section.