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 3 commits into
base: master
Choose a base branch
from
Open

Clarify EKF3 Affinity #7499

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c8cdd63
Split multi-sentence lines into one sentence per line.
hunt0r Mar 9, 2026
fa0369a
Remove trailing whitespace
hunt0r Mar 9, 2026
61a4457
Clarify how EKF affinity works
hunt0r Mar 9, 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
44 changes: 33 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,42 @@
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 describes an advanced configuration topic. The source code is the truth. This page hopefully provides conceptual clarity, but it *is not perfect* on the details.

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 -**
For each of the other sensor-types {Airspeed, Barometer, GPS, and Magnetometer (aka Compass)}:
If affinity for that sensor-type is disabled, each lane uses the system's "primary" instance of the sensor.
(Affinity being disabled for every sensor-type is the conventional/default choice.)
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
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
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.


Because modern-day vehicles may have redundant good quality sensors installed, "affinity" provides a way to have some EKF lanes prefer sensor instances which are not the system-wide primary.
For sensors with affinity enabled, lane-switching should be thought of as sensor-switching.
Copy link
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.

I think this is over-simplification. It's possible that not all IMUs present in a flight controller perform equally well. Which means lane-switching with affinity enabled isn't just "sensor-switching". If a user hasn't tested all lanes (or at least checked logs for all lanes), they might switch to a worse lane.

Copy link
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 agree it is a simplification. (I hoped "should be thought of" would communicate that... maybe it did?)

Over-simplification suggests it might be worse than some alternative... help me understand what you have in mind?

Also, I think there's no gap in my understanding of the topic, it's merely a discussion about what wording is appropriate. This PR is my attempt to find the right balance, but I'm glad to take it in the direction(s) you'd like!

Do you know github's "Suggest Changes" feature? That would be a great way to specifically communicate what differences you'd like to see, and my "Accept Suggestion" would confirm my agreement/understanding.

The lane error score (used to make a switching decision) takes into account innovations from all sensors used by a lane.
Thus in the case of noisy-but-not-broken non-IMU sensors, affinity might avoid a mishap by simply EKF lane-switching to a less-noisy IMU+sensor combination.
Copy link
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.

The language here is a bit confusing.

Copy link
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'm guessing you're flagging the over-hypenation 😄. Yeah, I didn't have good user-facing language for "misbehaving but not faulted". Suggestions?

I also tried to stay close to the original sentence (language like "avoid a mishap by lane-switching") which might contribute to the confusion. That was primarily motivated by a desire to make a minimum-necessary change, I'm happy with broader rewording if you are.


**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 +49,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