Skip to content

Copter/AP_NavEKF3: use vehicle land complete flag to set onGround and inFlight flags - #35105

Open
rmackay9 wants to merge 5 commits into
ArduPilot:masterfrom
rmackay9:ekf3-use-vehicle-land-complete-flag
Open

rmackay9 wants to merge 5 commits into
ArduPilot:masterfrom
rmackay9:ekf3-use-vehicle-land-complete-flag

Conversation

@rmackay9

@rmackay9 rmackay9 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This EKF3 change causes a Copter that has just landed to get the same on-ground behaviour as when disarmed. This includes the GPS checks, zero velocity fusion when not moving, compass heading fused regardless of innovations and fusing of all-zero optical flow values.

While a separate change, this will have the side effect of resolving the "landing in loiter" issue from PR #35077. This issue involves the EKF failsafe triggering during a land.

How it works

  • Current, in master, Copter and Heli tell the AHRS/EKF if it is landed (aka "land_complete") using the AP_Vehicle::set_likely_flying method which sets dal.get_time_flying_ms = 0. Rover, Sub, Tracker (and soon Blimp) simply pass the armed state. Plane passes its is_flying() state.
  • This PR adds a separate vehicle_landed flag. Copter's set_land_complete() sets it with AP_AHRS::set_vehicle_landed(), AP_DAL copies it into a new Flags2 byte of the RFRN log message and EKF3 reads it with dal.get_vehicle_landed(). Only Copter and Heli set it, so the EKF sets onGround and clears inFlight for them only.
  • Because the flag is logged, Replay of a Copter log gives the same result as the flight and EKF3 needs no Replay-specific code. Logs from before this change read the flag as 0.

Behaviour Changes

Before this change, an armed Copter that landed stayed onGround=false and inFlight=true until disarmed, since inFlight is only cleared on disarm. Before takeoff it was onGround=false, inFlight=false. Here's a table showing the change:

Situation master this PR
Armed, before takeoff onGround=false, inFlight=false onGround=true, inFlight=false
Flying onGround=false, inFlight=true onGround=false, inFlight=true
Armed, after landing onGround=false, inFlight=true onGround=true, inFlight=false

In master, inFlight is only cleared on disarm. With this PR a landed Copter gets the same on-ground behaviour as when disarmed, which means:

With this PR after the Copter has landed both states are onGround=true, inFlight=false which means:

  • Compass fusion: a compass that fails its innovation test is now fused, not rejected, after landing. Before this change it was rejected after any flight, because inFlight stayed true
  • Yaw and mag resets: In-flight yaw/mag resets are not allowed while landed. The in-flight init flags and learned field are cleared at each landing, so they're redone at the next takeoff.
  • Mag field learning: disabled on the ground except when EK3_MAG_CAL = 4 (Always) or 7 (On ground and after first climb yaw reset). With the default 3, learning that was left on after a flight now switches off at landing.
  • Static yaw fusion: When not moving, yaw is held to the last good heading, which lets yaw bias learn on the ground.
  • GPS checks: The drift and speed checks now run while armed on the ground.
  • Zero-velocity fusion: Applied when not moving, which constrains gyro and Z accel bias. Accel bias learning is inhibited while landed and moving.
  • Height: Height datum resets are allowed. The terrain state resets to the ground. The baro innovation limit is looser when not aiding.
  • Rangefinder: With a Good range finder and no range data for 200ms the EKF assumes the on-ground range.
  • Wind estimation: Off while landed
  • EKF-GSF yaw estimator: Restarted at landing, which clears its yaw reset counters.
  • Optical flow: The flow takeoff flag clears, and zeroed flow rates are fused if the EKF's height above ground estimate (HAGL) is below 0.5m.
  • Copter in Throw mode: the EKF's in-flight yaw alignment will not happen until after the throw is detected. In master the yaw alignment can happen during the carry phase if the vehicle is raised more than 2.5m above its arming height. This is a consequence of aligning the vehicle and EKF landed state. With this PR a copter carried armed is treated as landed (by both Copter and EKF3) until the throw is detected while in master the Vehicle and EKF are in an inconsistent state with the Copter's land_complete = true but the EKF's onGround = false.
  • If a Copter is disarmed an then re-armed in the air, the vehicle is treated as landed (onGround=true, inFlight=false) until the throttle is raised. This is a moot point however because Copter has never guaranteed that in-air arming is possible.

Plane/QuadPlane is not affected by this change. Rover, Sub, Tracker and Blimp never set the flag so they are not affected either, including in Replay.

EKF3 now depends on Copter's land detector being correct. If it reports "landed" while flying, the EKF would use its on-ground behaviour in the air (for example zero velocity fusion and wind estimation off). Heli uses the same flag and has not been tested.

This existing issue was discovered: #35197 but it is beyond the scope of this PR to resolve.

Testing

An auto test, EK3YawAlignEachTakeoff, has been added that checks that the yaw reset happens twice (in total) if a vehicle takes off, then lands and takes off again.

I've also tested this manually and attached screen shots below. The test in SITL was:

  1. start SITL copter
  2. loiter
  3. arm throttle
  4. rc 3 1800 <-- raise throttle to takeoff the 1st time, wait until vehicle climbs to 10m. Look for 1st yaw reset.
  5. rc 3 1200 <-- lower throttle to 20% in order to land but vehicle will not disarm (because throttle is slightly raise)
  6. rc 3 1800 <-- raise throttle to takeoff again. look for 2nd yaw reset

Before we see only a single yaw reset
before

After we see a second yaw reset when the vehicle takes off again
after

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 helped me greatly in the creation and testing of this PR

@AP-Review

AP-Review commented Nov 11, 2026 •

Copy link
Copy Markdown

Deprecated — see below for the updated review.

Previous review (2026-11-11)

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

Reviewed at head 285e3a8063.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35105/1.html#pr35105

The EKF3 change does what it says for Copter, but the new autotest fails at this head, and Replay of non-Copter logs now diverges from the flight.

Blocking

  1. Tools/autotest/arducopter.py:16522: EK3YawAlignEachTakeoff force-disarms while still climbing. The copter drops to the ground and ends about 3.9 m from its start, which fails Copter's 2 m end-of-test location check (6 of 6 runs failed). Ending the test with self.do_RTL() passes, and the test still fails on master.

Should fix

  • libraries/AP_NavEKF3/AP_NavEKF3_VehicleStatus.cpp:380: APM_BUILD_TYPE(APM_BUILD_Replay) applies the Copter landed check to every vehicle's logs. Rover, Sub, Tracker, Plane and Blimp set time_flying_ms differently, so Replay now diverges from the flight (Rover log: 139417 errors, QuadPlane log: 38469; both 0 on master). One fix is to log a flag that only Copter/Heli set and test that, since VehicleClass alone can't tell Blimp apart.

@rmackay9
rmackay9 force-pushed the ekf3-use-vehicle-land-complete-flag branch from 285e3a8 to 06f1cf3 Compare November 11, 2026 07:00
@AP-Review

AP-Review commented Nov 11, 2026 •

Copy link
Copy Markdown

Deprecated — see below for the updated review.

Previous review (2026-11-11)

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

Reviewed at head 06f1cf36d2.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35105/2.html#pr35105

The EKF3 change still works for Copter, and the new autotest now passes; one non-blocking Replay issue remains.
Since the review at 285e3a8, the test ends with do_RTL() instead of a forced disarm. It now passes and lands at home, and it still fails on master.

Should fix

  • libraries/AP_NavEKF3/AP_NavEKF3_VehicleStatus.cpp:380: Replay applies the Copter landed check to non-Copter logs (still open). This includes QuadPlane: its Replay log goes from 0 errors to 38469, so the PR text's "Plane/QuadPlane is not affected" is only true for firmware. One fix is to log a flag that only Copter/Heli set and test that in Replay.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Global Size Summary (Total Flash delta in bytes)

Built from d094779 rebased onto 97a060c

Board Periph tracker blimp bootloader copter heli iofw plane rover sub
DrotekP3Pro _ _ _ * _ _ _ _ _ _
Durandal _ +40 +44 _ +52 +52 _ +44 +44 +40
Hitec-Airspeed * _ _ _ _ _ _ _ _ _
KakuteF7 _ +44 +44 _ +52 +52 _ +48 +48 +44
MambaH743v4 _ +44 +44 _ +60 +60 _ +48 +44 +44
MatekF405-CAN _ _ _ * _ _ _ _ _ _
MatekF405 _ +44 +44 _ +52 +52 _ +48 +48 +44
MatekH743-bdshot _ +40 +44 _ +52 +52 _ +44 +44 +40
Pixhawk1-1M _ +44 +44 _ +56 +56 _ +52 +48 +44
disco _ +40 +22 _ +54 +62 _ +48 +40 +48
f103-GPS * _ _ _ _ _ _ _ _ _

@andyp1per

Copy link
Copy Markdown
Contributor

Tested in SITL on the landing test from the #35077 thread, renamed for FLOW_ALT_MIN: 3 runs on #35077 plus this PR against 2 on #35077 alone. The LOITER failsafe at +4.4 s after LAND_COMPLETE is gone, aiding holds until DISARM_DELAY in all four legs, and the ALT_HOLD legs with bad flow on the ground walk 0.05 m. EK3YawAlignEachTakeoff passes. One case it does not cover, and three points for the description:

  1. A range finder that reads out of range low on the ground still loses position after landing. LOITER landing with an origin, RNGFND1_MIN raised to 0.2 after takeoff: "EKF variance: position lost" and LAND at +4.4 s, with and without this PR, and with FLOW_ALT_MIN 0 (one run each). gndOffsetValid times out 5 s after the last range sample and horiz_pos_rel drops. The description's "with no range data for 200ms the EKF assumes the on-ground range" does not happen on master for that sensor: readRangeFinder() takes the continue for any sensor not reading Good before it reaches that branch, so the branch only runs for a Good sensor with fewer than three fresh samples. AP_NavEKF3: ground clearance fusion fix #32232 makes it reachable. This is the usual case for flow copters with RNGFNDx_MIN 0.05 and no ground clearance, which read 0.00 m, out of range low, on the ground in flight logs.

  2. The paths gated on onGroundNotMoving do not run on a real copter while its props spin: zero-velocity fusion, the static yaw hold and yaw bias learning on the ground. In flight logs armed after landing, the stillness test's gyro_diff reads 15-22x its threshold and accel_diff 2-3x (a steady hover 3.6-3.8x, disarmed 0.2-0.7x). SITL has no motor vibration by default, which is why it shows them working. On hardware the changes that do take effect after landing are the flow zeroing and accel bias learning inhibited on all axes.

  3. Replay, adding to the bot's point: Blimp registers as VehicleClass::COPTER and never calls set_likely_flying, so its time_flying_ms is always 0 and a logged class test alone still diverges on Blimp logs. Once Blimp passes the armed state, as the description plans, dal.get_vehicle_class() == COPTER under APM_BUILD_TYPE(APM_BUILD_Replay) covers every vehicle, as AP_OpticalFlow: add FLOW_HGT_MIN, the sensor's minimum focus height #34292 does for its Rover exclusion. A new logged flag would need a new byte or message, since RFRN's flag byte is full.

  4. onGround now also holds from arming to NOT_LANDED (median 2.3 s, up to 24 s in flight logs; none left the ground before NOT_LANDED). hgtInnovFiltState is only cleared while !onGround, so it now filters the baro through spool-up, where flight tests show prop wash taking the baro 4.4-5.7 m low at liftoff. In AID_NONE healthy() fails once it passes 1 m, which reports AHRS unhealthy and allows a lane switch as the copter takes off. Not tested.

@rmackay9
rmackay9 force-pushed the ekf3-use-vehicle-land-complete-flag branch from 06f1cf3 to 3993abc Compare November 12, 2026 07:02
@rmackay9 rmackay9 removed the AIReview label Nov 12, 2026
@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 3993abc2e6.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35105/3.html#pr35105

The landed-flag change works for Copter and the new test passes at this head; one non-blocking THROW-mode regression remains.
Since the review at 06f1cf3, Replay uses a new logged vehicle_landed flag that only Copter sets, and the Rover and QuadPlane logs that diverged now replay with 0 errors.

Should fix

  • ArduCopter/land_detector.cpp:233: in THROW drop mode, land_complete stays true while the armed copter is carried, so EKF3 now treats the carry as on the ground and resets its takeoff height to the release point. The copter only descends after the drop, so the in-flight yaw/field alignment never runs (none in ThrowDoubleDrop at this PR, two per flight on master). One option is to call ahrs.set_vehicle_landed(false) when THROW enters Throw_Detecting; in SITL that restored the alignments, and ThrowDoubleDrop, ThrowMode and EK3YawAlignEachTakeoff still passed.
Minor (2)

Withdrawn: CompassLearnDisabledDoesNotSave does not need to reach the held copy, because it tests the COMPASS_LEARN guard by design.

@andyp1per

Copy link
Copy Markdown
Contributor

One more case beside THROW: a mid-air disarm followed by a re-arm. Disarm forces land_complete, and once re-armed only throttle above the non-takeoff level clears it, so vehicle_landed stays set while the copter falls. On master onGround goes false on the first EKF cycle after arming. In SITL on #32972, re-arms in Stabilize at zero throttle and in ALT_HOLD with the stick at 1450, 1500 and 1550 all stayed landed and fell at 15-17 m/s, one of them for about 9 s. From the source, through that window the compass is fused without its innovation check, and the in-flight yaw and field reset is held off with its flags cleared each cycle.

#32768 handles the same case for its arm-time height datum reset, which zeroes the vertical velocity. There ap.disarmed_in_air is set by a disarm with land_complete clear, or by a watchdog reset while armed, and only the disarmed land detector clears it, once the airframe has stopped accelerating and descending. The reset is skipped while it is set. If #32768 goes in, reporting landed only while disarmed_in_air is clear would cover this. set_land_complete() returns early when nothing changes, so the flag would also need setting where the land detector clears disarmed_in_air.

@peterbarker

peterbarker commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

See this comment in the method you're modifying:

        TODO - this logic should be moved out of the EKF and into the flight vehicle code.

... and discussion on #28389 (comment)

... and #2074 (comment)

@rmackay9

Copy link
Copy Markdown
Contributor Author

@AP-Review, thanks for the review.

RE the "Should fix" item for THROW mode - I disagree with the suggestion to add ahrs.set_vehicle_landed(false) to Throw mode because it bypasses Copter's land_complete flag and thus means the vehicle code land_complete and EKF state could become inconsistent. The behaviour change is that the EKF's in-flight yaw alignment cannot happen until after the throw is detected but I think this could actually be preferable because the pilot might have a metal watch on (or similar). I've added a comment about this behaviour change to the PR description

I've also updated the rangefinder bullet point

@AP-Review

AP-Review commented Nov 16, 2026 •

Copy link
Copy Markdown

Deprecated — see below for the updated review.

Previous review (2026-11-16)

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

Reviewed at head ebdff68dcf.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35105/5.html#pr35105

The landed-flag change still works for Copter, and both new tests pass at this head. Two non-blocking points remain, one of them an unanswered reviewer case.
Since the review at 3993abc, the head moved (a rebase plus a rewritten comment). The AP_Arming comment and the rangefinder description bullet are fixed, and the THROW behaviour is now documented as deliberate, so the request to clear the flag in THROW is dropped.

Should fix

  • ArduCopter/land_detector.cpp:233: a disarm in the air forces land_complete, and after a re-arm vehicle_landed stays set while the copter falls, so EKF3 takes its on-ground branch in the air. This is andyp1per's 2026-11-12 case, which has no reply yet. In SITL the effect was small, but XY accel bias learning is inhibited and the takeoff height reference is overwritten during the fall. Reporting landed only while disarmed_in_air is clear (once AP_NavEKF3: clear baro temperature drift on arming #32768 lands), or naming this case in the description's land-detector caveat, would cover it.

Note

  • PR description, Throw bullet (still open): after a drop that only descends, the in-flight alignment may not happen at all in that flight, because it needs a 2.5 m climb above the release point. With the default EK3_MAG_CAL 3, field learning then also stays off. Saying so would match the code; the behaviour itself is your call.

Withdrawn: the new AP_Arming "until the next arm" wording is accurate as a lower bound (Copter keeps the field until takeoff).

@rmackay9

rmackay9 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor Author

Thanks @AP-Review for the review.

Re the "Should fix" item, I've slightly updated the PR description to specify the change in behaviour after an in-air re-arm. This whole line of thinking is a bit ridiculous though, Copter has never guaranteed that in-air re-arms are possible and beyond that, worry about the minor impacts on XY accel biases is the least of the worries in that situation.

}

bool get_vehicle_landed(void) const {
return vehicle_landed;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could the AHRS call through to vehicle and get the likely flying flag?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @IamPete1,

Txs for the review and comments. I think that's technically possible but I think that's the wrong direction for data/state to flow. I think the AHRS is lower on the stack than the vehicle code.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That works too it just seems odd to see copter setting the same information into both vehicle and ahrs.

Vehicles can use it to tell the estimators they have landed even
though they are still armed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
rmackay9 and others added 4 commits November 17, 2026 12:16
It is the first bit of a new Flags2 byte, appended to RFRN so that
logs without it replay as not landed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
An armed Copter that has landed now gets the same on-ground behaviour
as when disarmed.  This includes the GPS checks, zero velocity
fusion when not moving, compass heading fused regardless of innovations

This leads to the EKF3 fusing all-zero optical flow values on a Copter
flying with optical flow that has just landed but has not yet disarmed.

Copter/Heli tells the AHRS when it has landed using
AP_AHRS::set_vehicle_landed which reaches the EKF through the DAL.

With this change, EKF3 uses this to set onGround and clear inFlight
flags.  Other vehicles do not set it so they are unaffected, and Replay
of their logs is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
EKF3 clears its in-flight yaw and magnetic field initialisation when the
vehicle is on the ground so that it is redone on each takeoff. Take off,
land without disarming and take off again, and check the in-flight yaw
alignment is reported after both takeoffs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@tridge
tridge force-pushed the ekf3-use-vehicle-land-complete-flag branch from ebdff68 to d094779 Compare November 17, 2026 01:16
@AP-Review

Copy link
Copy Markdown

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

Reviewed at head d09477970a.
Full report: https://firmware.ardupilot.org/Tools/APReview/DevCallReviews/PRReviews/ardupilot/ardupilot/35105/6.html#pr35105

The landed-flag change still works at this head, which is a clean rebase of the code reviewed before. The new test passes and still fails with the EKF3 change reverted.
Since the last review the author has documented the in-air re-arm case in the description, which matches the code, so that item is closed.

Minor (2)

CI was still running at review time, with no failures so far.

@rmackay9

Copy link
Copy Markdown
Contributor Author

Thanks @AP-Review for the ACCEPT. I've fixed up the PR description typos.

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.

6 participants