Skip to content

AP_NavEKF3: LearnedMagField manages learned compass offsets - #35128

Merged
tridge merged 3 commits into
ArduPilot:masterfrom
rmackay9:ekf3-hold-learned-mag-field
Nov 17, 2026
Merged

tridge merged 3 commits into
ArduPilot:masterfrom
rmackay9:ekf3-hold-learned-mag-field

Conversation

@rmackay9

Copy link
Copy Markdown
Contributor

Summary

With this change, each EKF3 core keeps a copy of the learned body magnetic field in a new nested class called LearnedMagField, instead of relying on the live body_magfield of the EKF state. This separation reduces dependencies on the order in which the live mag field may be cleared and when the last valid learned offsets can be saved to the COMPASSn_OFS_X/Y/Z parameters. This difference has almost no functional impact in master but becomes important for a follow-up PR #35105 which affects when the EKF3's onGround is set/cleared.

How the class is used

  1. During each EKF update, the latest learned body magnetic field is copied into the LearnedMagField class and the validity flag is set, but only if all of these are true:

    a. the final in-flight mag field initialisation after takeoff has finished (see finalInflightMagInit)
    b. the mag field states are being learned (see !inhibitMagStates)
    c. the compass is in use (use_compass()) and healthy (compass.healthy(magSelectIndex))
    d. the field estimate has converged (its variances are small, P[19][19] to P[21][21] are below 5e-6)

If any of them is false the previous copy is left as it is, so the last good value survives a landing.

These are the same conditions master checks when it saves the offsets at disarm, except that use_compass() is also checked here (on master the compass library checks it at save time). The copy also records which compass it is for (magSelectIndex), and is only returned for that compass, which replaces the check mag_idx == magSelectIndex that master makes at save time.

  1. The copy is cleared (validity flag false) at takeoff, when the compass offset parameters change, when the EKF switches to another compass, at EKF initialisation and when the compass stops being used.
  2. At disarm, with COMPASS_LEARN = 2 (EKF-Learning), the compass library asks the EKF for the offsets of each compass. If the copy is valid, is for that compass and the compass is healthy, the EKF returns the current COMPASSn_OFS_X/Y/Z values minus the learned field (scaled to milliGauss), and these are saved to the parameters.
  3. Because the parameters have changed, the EKF zeroes its live body_magfield and clears the copy, so the correction is not applied twice.

Testing

These existing autotests exercise the code change and pass on both this PR and master:

  • CompassLearnCopyFromEKF: learns offsets in flight, lands and disarms, and checks the offsets are saved. Passes.
  • CompassLearnCopyFromEKFAffinity: the same with two EKF cores, each pinned to its own compass, checking each core's copy is saved for the right compass.
  • test.Copter.Replay shows no replay changes before/after this change

An new autotest has been added:

  • CompassLearnDisabledDoesNotSave (new): learns offsets in flight, sets COMPASS_LEARN to 0, lands and disarms, and checks nothing is saved. It guards against the held copy being saved when learning is turned off. It passes both on this branch and master and has been added because it protects behaviour this PR could break rather than showing new behaviour.

CompassLearnCopyFromEKF and CompassLearnCopyFromEKFAffinity pass.

More human testing will be performed before we merge

Classification & Testing (check all that apply and add your own)

  • Checked by a human programmer
  • Non-functional change
  • No-binary change
  • Infrastructure change (e.g. unit tests, helper scripts)
  • Automated test(s) verify changes (e.g. unit test, autotest)
  • Tested manually, description below (e.g. SITL)
  • Tested on hardware
  • Logs attached
  • Logs available on request

Claude greatly helped me creating and testing this PR

@AP-Review

AP-Review commented Nov 12, 2026 •

Copy link
Copy Markdown

Deprecated — see below for the updated review.

Previous review (2026-11-12)

Automated review note — AI-generated (Claude+Codex), validated against the live diff. Please sanity-check before acting.
Verdict: COMMENT

Reviewed at head 4131df33f3.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35128/1.html#pr35128

This is a clean refactor: the three existing and new compass-learn autotests pass at this head, and a mutation check shows the existing CompassLearnCopyFromEKF test does exercise the new copy. Two small points remain.

Should fix

  • libraries/AP_Arming/AP_Arming.cpp:2027: the comment says the EKF holds the field until the next takeoff. EKF3 sets onGround = !armed, so the new clear runs at the next arm. EKF2's getMagOffsets() still needs finalInflightMagInit, so EKF2 builds still need this save to run before set_soft_armed(false). Suggest "until the next arm" and keeping the EKF2 caveat.
  • Tools/autotest/arducopter.py:23226: with COMPASS_LEARN=0, save_ekf_learned_offsets() returns before it ever asks the EKF, so this test checks the existing Compass guard, not the held copy. The test is fine to keep. A test that fails when one of the clear() sites (arm, compass switch, offset change) is removed would cover the new state, which matters before PR 35105 changes onGround.

A note that the description did not mention saves now using the last converged copy was withdrawn: the PR text and commit message both describe it.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Global Size Summary (Total Flash delta in bytes)

Built from 7ce5815 rebased onto a995235

Board Periph tracker blimp bootloader copter heli iofw plane rover sub
DrotekP3Pro _ _ _ * _ _ _ _ _ _
Durandal _ +56 +56 _ +56 +56 _ +56 +56 +64
Hitec-Airspeed * _ _ _ _ _ _ _ _ _
KakuteF7 _ +220 +220 _ +220 +220 _ +220 +176 +220
MambaH743v4 _ -16 -16 _ -16 -16 _ -16 -16 -16
MatekF405-CAN _ _ _ * _ _ _ _ _ _
MatekF405 _ +220 +220 _ +220 +220 _ +220 +176 +220
MatekH743-bdshot _ +56 +56 _ +56 +56 _ +56 +56 +64
Pixhawk1-1M _ +220 +220 _ +224 +224 _ +224 +228 +224
disco _ +470 +456 _ +434 +448 _ +450 +436 +440
f103-GPS * _ _ _ _ _ _ _ _ _

rmackay9 and others added 3 commits November 16, 2026 09:47
…landing

The EKF only handed out learned compass offsets while the learning
conditions held (in-flight mag initialisation complete, mag states not
inhibited), so offsets could be lost if either changed before the
disarm that saves them.
Keep a copy of the learned body field while it is valid and use it for
getMagOffsets(). It is cleared when the compass offsets change, the
compass is switched, a flight starts, or the compass is no longer used.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The EKF now holds the learned field after landing, so the offsets
no longer have to be saved before the vehicle is on the ground.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…turned off

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@rmackay9
rmackay9 force-pushed the ekf3-hold-learned-mag-field branch from 4131df3 to 7ce5815 Compare November 16, 2026 00:47
@rmackay9

Copy link
Copy Markdown
Contributor Author

@AP-Review, thanks for the review.

My AI and I have rebased this on master and updated the comment re EKF3 and EKF2 behaviour.

Re your 2nd suggestion to add another autotest, I don't think we should add an autotest. I think the existing CompassLearnCopyFromEKF already fails if the copy is lost at landing which is the code path that matters.

@AP-Review

Copy link
Copy Markdown

Automated review note — AI-generated (Claude+Codex), validated against the live diff. Please sanity-check before acting.
Verdict: COMMENT

Reviewed at head 7ce5815837.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35128/2.html#pr35128

No blocking issues at this head: the rebase leaves the EKF3 and autotest commits unchanged.
Since the last review, the disarm comment has been fixed to say EKF3 holds the field until the next arm, with the EKF2 caveat kept.

Minor (2)
  • libraries/AP_NavEKF3/AP_NavEKF3_VehicleStatus.cpp:449: the comment says "on takeoff", but EKF3's onGround is !armed, so this clear runs on arm. Suggest "clear learned mag field on arm" to match the corrected AP_Arming comment. The PR text says "at takeoff" too.
  • Tools/autotest/arducopter.py:23653: invalidation test (still open, optional). Your call not to add it here is fine. For the record, CompassLearnCopyFromEKF fails if no copy is made, but it still passes (181.44 saved) with a mutation that clears the copy when EKF3 sees onGround, because the save runs before soft-disarm. So retention past onGround is untested until PR 35105 needs it.

@rmackay9

Copy link
Copy Markdown
Contributor Author

@AP-Review,

Thanks again for the review.

Re the two Minor points:

  1. I'm not going to change the comment at libraries/AP_NavEKF3/AP_NavEKF3_VehicleStatus.cpp:449 because the follow-up PR Copter/AP_NavEKF3: use vehicle land complete flag to set onGround and inFlight flags #35105 is going to make the comment true again.
  2. I'm glad your happy that it's fine not to add the test

@tridge
tridge merged commit ff602fb into ArduPilot:master Nov 17, 2026
118 of 119 checks passed
@rmackay9
rmackay9 deleted the ekf3-hold-learned-mag-field branch November 17, 2026 03:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants