From c723b773d9bf319566d05644d63b8397bbb0b472 Mon Sep 17 00:00:00 2001 From: Hunter McClelland Date: Mon, 9 Mar 2026 10:57:51 -0400 Subject: [PATCH 1/4] Split multi-sentence lines into one sentence per line. --- .../docs/common-ek3-affinity-lane-switching.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/common/source/docs/common-ek3-affinity-lane-switching.rst b/common/source/docs/common-ek3-affinity-lane-switching.rst index bf3617f4c5e..a8ad33e25a1 100644 --- a/common/source/docs/common-ek3-affinity-lane-switching.rst +++ b/common/source/docs/common-ek3-affinity-lane-switching.rst @@ -5,7 +5,16 @@ EKF3 Affinity and Lane Switching ================================ -The :ref:`EKF ` 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 ` 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. **A simple example of an affinity configuration for a vehicle which has 2 Barometers, 2 GPS, 2 Airspeeds, 3 Magnetometers and 3 IMUs -** @@ -29,7 +38,8 @@ Configuration Parameters Affinity is only available with EKF3, so make sure you are using it by ensuring :ref:`EK3_ENABLE ` is set to "1" and :ref:`AHRS_EKF_TYPE ` is set to "3" -The :ref:`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 ` 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_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. From 76abe47419ffdffd8dcbd3c77581cd7434d3a42d Mon Sep 17 00:00:00 2001 From: Hunter McClelland Date: Mon, 9 Mar 2026 10:58:25 -0400 Subject: [PATCH 2/4] Remove trailing whitespace --- common/source/docs/common-ek3-affinity-lane-switching.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/common/source/docs/common-ek3-affinity-lane-switching.rst b/common/source/docs/common-ek3-affinity-lane-switching.rst index a8ad33e25a1..cb30332530e 100644 --- a/common/source/docs/common-ek3-affinity-lane-switching.rst +++ b/common/source/docs/common-ek3-affinity-lane-switching.rst @@ -41,10 +41,10 @@ Configuration Parameters The :ref:`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_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 ` 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 ` parameter could adversely affect the lane switching mechanism and have serious consequences which could lead to the loss of your vehicle. Please tune carefully. From 14027c19c0c6d95571ef4fe1ffe7d38395d36f6a Mon Sep 17 00:00:00 2001 From: Hunter McClelland Date: Mon, 9 Mar 2026 11:49:45 -0400 Subject: [PATCH 3/4] Clarify how EKF affinity works --- .../common-ek3-affinity-lane-switching.rst | 46 ++++++++++++------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/common/source/docs/common-ek3-affinity-lane-switching.rst b/common/source/docs/common-ek3-affinity-lane-switching.rst index cb30332530e..971f14a9145 100644 --- a/common/source/docs/common-ek3-affinity-lane-switching.rst +++ b/common/source/docs/common-ek3-affinity-lane-switching.rst @@ -6,30 +6,41 @@ EKF3 Affinity and Lane Switching ================================ The :ref:`EKF ` 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 "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 `). +Furthermore, the lanes are 1-1 bound to the (used) IMUs: lane 1 for IMU 1, lane 2 for IMU 2, etc. + +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. + +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. +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. -**A simple example of an affinity configuration for a vehicle which has 2 Barometers, 2 GPS, 2 Airspeeds, 3 Magnetometers and 3 IMUs -** +**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 - - - - - + + + + + +
LANE123
AIRSPEED121
BAROMETER121
GPS121
MAGNETOMETER123
LANE1234
IMU1234
AIRSPEED1111
BAROMETER1111
GPS1211
MAGNETOMETER1231
-*Numbers are the respective sensor instances* +*Numbers indicate the lane's initial primary sensor instance.* Configuration Parameters ------------------------ @@ -39,7 +50,8 @@ Configuration Parameters Affinity is only available with EKF3, so make sure you are using it by ensuring :ref:`EK3_ENABLE ` is set to "1" and :ref:`AHRS_EKF_TYPE ` is set to "3" The :ref:`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. +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 ` 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. From 8c302bb6dc047557da2befe453c40aa00d5a059c Mon Sep 17 00:00:00 2001 From: Hunter McClelland Date: Tue, 14 Apr 2026 09:02:29 -0400 Subject: [PATCH 4/4] Clarity improvements from review feedback --- .../common-ek3-affinity-lane-switching.rst | 25 ++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/common/source/docs/common-ek3-affinity-lane-switching.rst b/common/source/docs/common-ek3-affinity-lane-switching.rst index 971f14a9145..698901f1c2d 100644 --- a/common/source/docs/common-ek3-affinity-lane-switching.rst +++ b/common/source/docs/common-ek3-affinity-lane-switching.rst @@ -10,21 +10,28 @@ The "primary" lane is the one currently providing state estimates, other lanes a .. 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. + 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 `). Furthermore, the lanes are 1-1 bound to the (used) IMUs: lane 1 for IMU 1, lane 2 for IMU 2, etc. -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.) +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. - -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. -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. +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.**