Skip to content

Clarify EKF3 Affinity #7499

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hunt0r wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Clarify EKF3 Affinity #7499

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c723b77
Split multi-sentence lines into one sentence per line.
hunt0r Mar 9, 2026
76abe47
Remove trailing whitespace
hunt0r Mar 9, 2026
14027c1
Clarify how EKF affinity works
hunt0r Mar 9, 2026
8c302bb
Clarity improvements from review feedback
hunt0r Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 40 additions & 11 deletions common/source/docs/common-ek3-affinity-lane-switching.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,49 @@
EKF3 Affinity and Lane Switching
================================

The :ref:`EKF <dev:extended-kalman-filter>` instantiates multiple instances of the filter called 'lanes'. The primary lane is the one that provides state estimates, rest are updated in the background and available for switching to. The number of possible lanes is exactly equal to the number of IMUs enabled for use. Conventionally, each lane uses the primary instance of the Airspeed, Barometer, GPS and Magnetometer sensors. The primary sensor can be set as a user-modifiable parameter, but can be later changed by the system, even in-flight, in case of a driver-level fault. However, modern-day vehicles are known to have multiple sensors installed of good quality. Affinity is a way for the EKF lanes to use non-primary sensors within any running lane. This provides a statistically consistent way to make use of multiple high quality sensors and use lane-switching to select the lane which has best performing combination of sensors. The lane error score takes into account innovations from all sensors used by a lane. This way, the vehicle can be saved from mishaps using noisy non-IMU sensors as well.
The :ref:`EKF <dev:extended-kalman-filter>` instantiates multiple instances of the filter called 'lanes'.
The "primary" lane is the one currently providing state estimates, other lanes are updated in the background and available for switching to.

.. note::

This page attempts to clarify an advanced configuration topic. The source code is the truth.

The number of possible lanes is the number of IMUs enabled for use (see :ref:`EK3_IMU_MASK <EK3_IMU_MASK>`).
Furthermore, the lanes are 1-1 bound to the (used) IMUs: lane 1 for IMU 1, lane 2 for IMU 2, etc.

**A simple example of an affinity configuration for a vehicle which has 2 Barometers, 2 GPS, 2 Airspeeds, 3 Magnetometers and 3 IMUs -**
Now, consider the other sensor types {Airspeed, Barometer, GPS, and Magnetometer (aka Compass)}.
First, it is important to define the system's notion of the "primary" sensor instance of each type.
The primary sensor instance is the instance being actively relied upon.
The initial primary sensor instance is selected by a user-modifiable parameter.
The system may change which sensor instance is its primary, even in-flight, for example in case of a sensor fault.
Copy link
Copy Markdown
Contributor

@rishabsingh3003 rishabsingh3003 Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line is a bit confusing in this context. Yes, the lane can possibly change its primary sensor for some sensors mid-flight, for example, a compass. But I don't think that's true for all sensors.. for example a barometer

Copy link
Copy Markdown
Contributor Author

@hunt0r hunt0r Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had details like this in mind with the note-box "This page [...] is not perfect on the details."

Do you think it's worth describing and then maintaining all the details on this page? If yes, additional commit(s) to fix them & remove the "this page is not perfect on the details" are welcome.

On the flip side: Do you think the page is better as it was before? That path forward also makes sense: Reject this PR and keep the content as it was.

Copy link
Copy Markdown
Contributor

@rishabsingh3003 rishabsingh3003 Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be better if you could say something along the lines of "There are some sensor types where the primary instance for the lane may change in flight, for example, the compass, which are not related to affinity but other health checks inside the EK3 code"

Copy link
Copy Markdown
Contributor Author

@hunt0r hunt0r Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying a reword, let's see if that addresses your concern.

Copy link
Copy Markdown
Contributor Author

@hunt0r hunt0r Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

8c302bb

Thus "changing the primary instance" is one mechanism the system can use to switch which sensor instance is being relied upon.

A second mechanism for selecting which sensor instance to rely on is provided by "affinity" & lane-switching.
Because modern-day vehicles may have redundant good quality sensors installed, affinity provides a way to force some EKF lanes to prefer sensor instances which are not the system-wide primary.
If affinity for a sensor-type is disabled, each lane uses the system's primary instance of the sensor.
(Affinity being disabled is the conventional/default choice.)
If affinity for a sensor-type is enabled, the sensor instances are distributed to lanes in a similar way as IMUs.
Now with affinity enabled, lane-switching becomes a mechanism for sensor-switching.
Each lane's error score---used by the system to make a switching decision---takes into account innovations from all sensors used by that lane.
Consider a noisy but not faulted sensor for which affinity is enabled: it makes the error-score for its lane bad.
The system responds to the bad error score by lane-switching away from relying on it.
Thus a mishap may be avoided by simply EKF lane-switching to a less-noisy IMU+sensor combination.

**Example: Vehicle uses 4 IMUs, 2 Airspeeds, 3 Barometers, 2 GPS, and 3 Magnetometers.
Affinity is disabled for airspeed & barometers, enabled for GPS & magnetometers.**

.. raw:: html

<table border="1" class="docutils">
<tr><th>LANE</th><th>1</th><th>2</th><th>3</th></tr>
<tr><td>AIRSPEED</td><td>1</td><td>2</td><td>1</td></tr>
<tr><td>BAROMETER</td><td>1</td><td>2</td><td>1</td></tr>
<tr><td>GPS</td><td>1</td><td>2</td><td>1</td></tr>
<tr><td>MAGNETOMETER</td><td>1</td><td>2</td><td>3</td></tr>
<tr><th>LANE</th><th>1</th><th>2</th><th>3</th><th>4</th></tr>
<tr><td>IMU</td><td>1</td><td>2</td><td>3</td><td>4</td></tr>
<tr><td>AIRSPEED</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
<tr><td>BAROMETER</td><td>1</td><td>1</td><td>1</td><td>1</td></tr>
<tr><td>GPS</td><td>1</td><td>2</td><td>1</td><td>1</td></tr>
<tr><td>MAGNETOMETER</td><td>1</td><td>2</td><td>3</td><td>1</td></tr>
</table>

*Numbers are the respective sensor instances*
*Numbers indicate the lane's initial primary sensor instance.*

Configuration Parameters
------------------------
Expand All @@ -29,12 +56,14 @@ Configuration Parameters

Affinity is only available with EKF3, so make sure you are using it by ensuring :ref:`EK3_ENABLE <EK3_ENABLE>` is set to "1" and :ref:`AHRS_EKF_TYPE <AHRS_EKF_TYPE>` is set to "3"

The :ref:`EK3_AFFINITY <EK3_AFFINITY>` parameter is a bitmask which gives you the option to choose the sensors you want to enable affinity for. Non-enabled will follow the default primary sensor allotment.
The :ref:`EK3_AFFINITY <EK3_AFFINITY>` parameter is a bitmask which gives you the option to choose the sensors you want to enable affinity for.
In every EKF lane, sensors for which affinity is not enabled will follow the system's "primary" selection logic.
For a sensor-type with affinity enabled, lane 1's primary sensor is 1, lane 2's primary sensor is 2, etc.

The :ref:`EK3_ERR_THRESH <EK3_ERR_THRESH>` parameter controls the sensitivity of lane switching. Lane errors are accumulated over time relative to the active primary lane. This threshold controls how much of an error difference between a non-primary and primary lane is required to consider the former performing better. Lowering this parameter makes lane switching more responsive to smaller 'relative' errors, and in practical you will see a more aggressive lane switching, and, vice-versa.
The :ref:`EK3_ERR_THRESH <EK3_ERR_THRESH>` parameter controls the sensitivity of lane switching. Lane errors are accumulated over time relative to the active primary lane. This threshold controls how much of an error difference between a non-primary and primary lane is required to consider the former performing better. Lowering this parameter makes lane switching more responsive to smaller 'relative' errors, and in practical you will see a more aggressive lane switching, and, vice-versa.

.. warning::

Misconfiguring the :ref:`EK3_ERR_THRESH <EK3_ERR_THRESH>` parameter could adversely affect the lane switching mechanism and have serious consequences which could lead to the loss of your vehicle. Please tune carefully.


Expand Down
Loading