[Bug] EKF2_DECL_TYPE description doesn't match the code: EKF2_MAG_DECL is ignored unless bit 1 is set #29196

Describe the bug

Describe the bug

The description of EKF2_DECL_TYPE (params_magnetometer.yaml) says:

0 : Set to true to use the declination from the geo_lookup library when the GPS position becomes available, set to false to always use the EKF2_MAG_DECL value.
1 : Set to true to save the EKF2_MAG_DECL parameter to the value returned by the EKF when the vehicle disarms.

The behaviour is different:

1. With EKF2_DECL_TYPE = 0, EKF2_MAG_DECL is ignored and a declination of 0° is used, although the description says bit 0 cleared means "always use the EKF2_MAG_DECL value".
2. EKF2_MAG_DECL is only used when bit 1 is set (EKF2_DECL_TYPE = 2 or 3).
3. EKF2_MAG_DECL is saved without any disarm. The description says the value is saved "when the vehicle disarms", but in the test the board was never armed, so a disarm never happened. As soon as a WMM declination was available (here after setting an origin), it was written to EKF2_MAG_DECL in the same boot (confirmed with a debug print in EKF2). The new value was only visible after a reboot.

To reproduce

Test without GPS, board static in the same orientation for all runs, never armed. EKF2_MAG_DECL set to 30 before each run. After each reboot: waited for cs_yaw_align and cs_mag_hdg, then read the yaw from ATTITUDE. In runs 5–8, an origin was set to trigger the WMM lookup:

commander set_ekf_origin <lat> <lon> <alt>

Declination applied = yaw − yaw of run 1 (the 0° baseline). The values in the declination applied column are rounded.

• Runs 1 and 5: with EKF2_DECL_TYPE = 0, EKF2_MAG_DECL (30) is not used. This contradicts "set to false to always use the EKF2_MAG_DECL value".
• Runs 3 and 4: EKF2_MAG_DECL is used only when bit 1 is set.
• Runs 7 and 8: with bit 1 and a WMM value, EKF2_MAG_DECL is overwritten in the same boot, without arming. A debug print in the save block confirmed the write in both runs (wmm -3.95, param 30.00). In QGC the new value only appeared after a reboot.

Aditional information

• Runs 3/4 and 7/8: EKF2_DECL_TYPE = 2 and 3 behaved the same in all cases, so I'm not sure if the parameter itself should be revised as well.
• The WMM value in runs 6–8 (−3.95°) is not the value at the set origin but the value at 0°N 0°E. That's a separate bug, reported in [Bug] EKF2: WMM declination is looked up at 0°N 0°E when the origin is set without a valid position #29195. It doesn't affect the behaviour shown here.

Expected behaviour

The description should match the actual behaviour:

EKF2 uses the first of these that applies:

1. Bit 0 set and a global position is available: the declination from the World Magnetic Model (WMM) at that position.
2. Bit 1 set: EKF2_MAG_DECL. As soon as a global position is available, EKF2 overwrites EKF2_MAG_DECL with the WMM declination for that position (whether bit 0 is set or not, and independent of arming or disarming). A manually configured value is therefore only used until a position is available.
3. Otherwise: 0.

To use a manual declination on a vehicle without a position source, set bit 1 and enter the value in EKF2_MAG_DECL.

Bit labels:

• 0: Use WMM declination when a position is available
• 1: Use EKF2_MAG_DECL, and store the WMM declination in it when a position is available

Flight Log / Additional Information

Version

PX4 v1.17.0. The code is unchanged on main.

Hardware

Pixhawk 6X, external DroneCAN magnetometer, no GNSS