feat(sensors/gps): move GPS antenna offsets to per-receiver parameters (#26634)

* sensors: move GPS antenna offsets to per-receiver parameters Move antenna position configuration from the single EKF2_GPS_POS_X/Y/Z parameter set into per-receiver SENS_GPS{0,1}_OFF{X,Y,Z} parameters in the sensors module. Each offset slot is matched to a physical receiver by device ID (SENS_GPS{0,1}_ID), falling back to uORB instance index when no IDs are configured. The antenna offset is now carried through the SensorGps uORB message and blended alongside other GPS states when multi-receiver blending is active, so EKF2 receives the correct lever arm for whichever receiver (or weighted combination) is selected. - Add antenna_offset_{x,y,z} fields to SensorGps.msg - Remove EKF2_GPS_POS_X/Y/Z params; EKF2 reads offset from gnssSample - Add SENS_GPS{0,1}_ID and SENS_GPS{0,1}_OFF{X,Y,Z} params (module.yaml) - Blend antenna offsets in GpsBlending (weighted average) - Add unit tests for single, blended, and failover antenna offset cases - Migrate params.c to module.yaml for the vehicle_gps_position module * sensors: gps_blending: add asymmetric weight and fallthrough offset tests Add two additional antenna offset test cases: - dualReceiverAsymmetricWeightAntennaOffset: verify that unequal eph values produce correctly skewed blend weights (0.8/0.2) and that the output antenna offset reflects the weighted average - blendingFallthroughAntennaOffset: verify that when blending is enabled but can_do_blending evaluates false (eph=0), the non-blending path correctly assigns the selected receiver's antenna offset * feat(param_translation): translate EKF2_GPS_POS_ to SENS_GPS0_OFF_ * fix(msgs): proper formatting * chore(msg): 0 if invalid/unknown * fix(ROMFS): migrate EKF2_GPS_POS_ params * fix(docs): migrate EKF2_GPS_POS_ params * fix(blending): unsigned param * Update msg/SensorGps.msg Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(sensors/gps): remove 'values:' tag in module.yaml * fix(sensors/gps): unsigned instance index * fix(blending): restore const on gps_blend_states() Move antenna offset blending into blend_gps_data() where the weights are computed, keeping gps_blend_states() const. * fix(sensors/gps): fix msg annotation and restore SENS_GPS_PRIME values Remove incorrect @invalid NaN annotation from antenna offset fields (0.0 default is correct, not a sentinel). Restore values tag for SENS_GPS_PRIME so QGC shows a dropdown. * fix(gps_blending): fix pre-existing bug to clear _gps_updated flags The loop iterates over i but always clears gps_select_index. The intent is to clear all updated flags, but only the selected one gets cleared (N times) * test(gps_blending): add stale update flag regression test
2026-03-23 10:03:41 +08:00 · 2026-03-17 17:33:41 -08:00
parent b597227da6
commit 89855926ef
29 changed files with 424 additions and 144 deletions
--- a/docs/en/assembly/mount_gps_compass.md
+++ b/docs/en/assembly/mount_gps_compass.md
@@ -20,7 +20,7 @@ For more information see [Setting the Compass Orientation](../config/flight_cont

 ## Position

-In order to compensate for the relative motion between the receiver and the CoG, you should [configure](../advanced_config/parameters.md) the following parameters to set the offsets: [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z).
+In order to compensate for the relative motion between the receiver and the CoG, you should [configure](../advanced_config/parameters.md) the following parameters to set the offsets: [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ).

 This is important because the body frame estimated by the EKF will converge on the location of the GNSS module and assume it to be at the CoG. If the GNSS module is significantly offset from the CoG, then rotation around the COG will be interpreted as an altitude change, which in some flight modes (such as position mode) will result in unnecessary corrections.

--- a/docs/en/dronecan/ark_g5_rtk_gps.md
+++ b/docs/en/dronecan/ark_g5_rtk_gps.md
@@ -97,7 +97,7 @@ There is also CAN built-in bus termination via [CANNODE_TERM](../advanced_config
 You need to set necessary [DroneCAN](index.md) parameters and define offsets if the sensor is not centred within the vehicle:

 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK G5 RTK GPS from the vehicle's centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK G5 RTK GPS from the vehicle's centre of gravity.

 ## LED Meanings

--- a/docs/en/dronecan/ark_g5_rtk_heading_gps.md
+++ b/docs/en/dronecan/ark_g5_rtk_heading_gps.md
@@ -99,7 +99,7 @@ You need to set necessary [DroneCAN](index.md) parameters and define offsets if
 - Enable GPS yaw fusion by setting bit 3 of [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to true.
 - Enable GPS blending to ensure the heading is always published by setting [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) to 7 (all three bits checked).
 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK G5 RTK HEADING GPS from the vehicle's centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK G5 RTK HEADING GPS from the vehicle's centre of gravity.

 ### Parameter references

--- a/docs/en/dronecan/ark_gps.md
+++ b/docs/en/dronecan/ark_gps.md
@@ -91,7 +91,7 @@ If the sensor is not centred within the vehicle you will also need to define sen

 - Enable GPS yaw fusion by setting bit 3 of [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to true.
 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK GPS from the vehicles centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK GPS from the vehicles centre of gravity.

 ### ARK GPS Configuration

--- a/docs/en/dronecan/ark_rtk_gps.md
+++ b/docs/en/dronecan/ark_rtk_gps.md
@@ -86,7 +86,7 @@ You need to set necessary [DroneCAN](index.md) parameters and define offsets if
 - Enable GPS blending to ensure the heading is always published by setting [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) to 7 (all three bits checked).
 - If using [Moving Baseline & GPS Heading](#setting-up-moving-baseline--gps-heading), set [SENS_GPS_PRIME](../advanced_config/parameter_reference.md#SENS_GPS_PRIME) to the CAN node ID of the _Moving Base_ module. The moving base is preferred because the rover receiver in a moving baseline configuration can experience degraded navigation rate and increased data latency when corrections are intermittent.
 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK RTK GPS from the vehicles centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK RTK GPS from the vehicles centre of gravity.

 ### ARK RTK GPS Configuration

--- a/docs/en/dronecan/ark_rtk_gps_l1_l2.md
+++ b/docs/en/dronecan/ark_rtk_gps_l1_l2.md
@@ -85,7 +85,7 @@ You need to set necessary [DroneCAN](index.md) parameters and define offsets if
 - Enable GPS yaw fusion by setting bit 3 of [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to true.
 - Enable GPS blending to ensure the heading is always published by setting [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) to 7 (all three bits checked).
 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK RTK GPS L1 L5 from the vehicles centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK RTK GPS L1 L5 from the vehicles centre of gravity.

 ### ARK RTK GPS L1 L5 Configuration

--- a/docs/en/dronecan/ark_x20_rtk_gps.md
+++ b/docs/en/dronecan/ark_x20_rtk_gps.md
@@ -88,7 +88,7 @@ You need to set necessary [DroneCAN](index.md) parameters and define offsets if
 - Enable GPS yaw fusion by setting bit 3 of [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to true.
 - Enable GPS blending to ensure the heading is always published by setting [SENS_GPS_MASK](../advanced_config/parameter_reference.md#SENS_GPS_MASK) to 7 (all three bits checked).
 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK X20 RTK GPS from the vehicles centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK X20 RTK GPS from the vehicles centre of gravity.

 ### ARK X20 RTK GPS Configuration

--- a/docs/en/dronecan/holybro_m8n_gps.md
+++ b/docs/en/dronecan/holybro_m8n_gps.md
@@ -94,4 +94,4 @@ If the sensor is not centred within the vehicle you will also need to define sen
 - Enable GPS yaw fusion by setting bit 3 of [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to true.
 - Enable [UAVCAN_SUB_GPS](../advanced_config/parameter_reference.md#UAVCAN_SUB_GPS), [UAVCAN_SUB_MAG](../advanced_config/parameter_reference.md#UAVCAN_SUB_MAG), and [UAVCAN_SUB_BARO](../advanced_config/parameter_reference.md#UAVCAN_SUB_BARO).
 - Set [CANNODE_TERM](../advanced_config/parameter_reference.md#CANNODE_TERM) to `1` if this is that last node on the CAN bus.
- The parameters [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z) can be set to account for the offset of the ARK GPS from the vehicles centre of gravity.
+- The parameters [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ) can be set to account for the offset of the ARK GPS from the vehicles centre of gravity.
--- a/docs/en/dronecan/index.md
+++ b/docs/en/dronecan/index.md
@@ -188,7 +188,7 @@ GPS CANNODE parameter ([set using QGC](#qgc-cannode-parameter-configuration)):

 Other PX4 Parameters:

- If the GPS is not positioned at the vehicle centre of gravity you can account for the offset using [EKF2_GPS_POS_X](../advanced_config/parameter_reference.md#EKF2_GPS_POS_X), [EKF2_GPS_POS_Y](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Y) and [EKF2_GPS_POS_Z](../advanced_config/parameter_reference.md#EKF2_GPS_POS_Z).
+- If the GPS is not positioned at the vehicle centre of gravity you can account for the offset using [SENS_GPS0_OFFX](../advanced_config/parameter_reference.md#SENS_GPS0_OFFX), [SENS_GPS0_OFFY](../advanced_config/parameter_reference.md#SENS_GPS0_OFFY) and [SENS_GPS0_OFFZ](../advanced_config/parameter_reference.md#SENS_GPS0_OFFZ).
 - If the GPS module provides yaw information, you can enable GPS yaw fusion by setting bit 3 of [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to true.

 #### RTK GPS