Needs testing: Issue #10830 Surface Mode Fixes

[breadoven]

Should close #10830.

Inhibits landing detection when Surface mode active unless AGL altitude Trusted and below 50cm.

Changes behaviour in Surface mode without Trusted AGL altitude. Previously the craft would descend at 0.5m/s regardless of throttle stick position. PR changes this so the throttle stick provides some adjustment of the descent rate, 0.5 m/s from high to mid stick then linear increase up to 2 m/s at low stick position. Should be less confusing for the pilot to have some response from throttle control.

Provides OSD system message indicating Surface mode status.

Also updates OSD system message array size to take account of additional Geozone messages.

Needs testing.

[Jetrell]

There was a guy on Discord today who also experienced a similar issue to this.

This was the transcript.

iNav Crash: LANDING_DETECTED mid-air at 15m due to Rangefinder out-of-range value (-1)
FC: Matek H743
GPS/Mag: Mateksys M10Q-5883
Rangefinder/OF: MicroAir MTF-02
Frame: 13" Quad | INAV 9.0.1
No GPS Fix entire flight

Incident:Quad flew above rangefinder max altitude when PosHold activated. It became stuck at 15m and refused to descend.
To force it down into rangefinder range, throttle was held at bottom (rcData=995).
Instead of descending, the quad remained frozen. 1.87s later, motors cut due to LANDING_DETECTED.
Timeline:
431605628 us: Throttle to bottom (rcData=995).
433478853 us: iNav registers LANDING_DETECTED (1.87s later).

High altitude caused MTF-02 to go out of bounds (>571cm), making surfaceRaw output -1.

Root Cause:
With PosHold enabled above limits, the sensor froze on -1, triggering a fatal landing detection loop: Frozen Altitude: Constant -1 made the estimator register 0 vertical speed, ignoring throttle input and keeping the quad stuck.
Math Trap: Since -1 is less than the landing threshold, iNav assumed the quad was on the ground.
False Landing: Zero vertical velocity combined with low throttle met all landing criteria, causing a mid-air disarm.

Quad have to be totally rebuilt, again.
This is fourth time it falls out of the air, but first time with a valid log to find the fault.

Temporarly Fix applied:
set nav_disarm_on_landing = OFF
Prevents mid-air disarm and allows barometer fallback when above rangefinder limits.

The quad also fell out of the air during RTH and PosHold earlier.
There seems to be a logical flaw in the sensor fusion (Baro/Sonar/GPS/ACC/Throttle) that allows this to happen.
A multirotor should never be able to trigger an automatic landing disarm mid-air, regardless of the throttle position.
I have two suggestions for the developers to prevent this bug:
1: Validation Check: Prevent the sonar/rangefinder from being used by the navigation system until it reads a valid, verified value within its operational bounds (not -1).
2: Descent Verification: Require the rangefinder value to actively decrease and confirm an actual descent before the landing detection algorithm can be released/triggered.

Note that he said he turned off the landing detector in this Diff, after the crash. Thinking it might be related.

There is also a slight issue with having altitude trusted below 10cm. And not just what defines TRUSTED ?
But in the case of this specific copter and many larger ones like it, that have legs/landing gear. Which positions the copters lidar sensor farther off the ground than 10cm. He said his is around 20cm above the surface while still on the ground.

DIFF - INAV_9.0.1_cli_20260516_015624 (nav_disarm_on_landing = OFF after crash).txt

LOG00042 (dropped out of air).TXT

https://www.youtube.com/watch?v=JQwIIH9OyG8&t=5s

[breadoven]

@Jetrell Yes it's the same issue as #10830. The surface logic isn't very sophisticated when the AGL altitude isn't trusted. If you switch on Althold above the range finders useable range, so it isn't trusted, it simply descends at 0.5m/s until it gets back in range and becomes trusted. When this happens the throttle stick becomes useless, high or low ... it does nothing which is pretty confusing for the pilot. Maybe the throttle stick should control the descent speed in these circumstances when AGL isn't trusted, e.g. 0.5 m/s above mid throttle with a linear increase up to say 2 m/s from throttle mid to throttle low. Would make more sense to the pilot.

Also the 0.5m/s is less than the landing detector minimum speed of 1 m/s which can cause it to trigger if the throttle is held low. Not sure why I chose 10cm as the detection cut off for this PR but it could be increased to maybe 50cm because detection is also only allowed in the PR if AGL altitude is trusted (that in itself would have prevented these crashes).

Do you not have a rangefinder equipped quad @Jetrell to test this ?

[Jetrell]

Also the 0.5m/s is less than the landing detector minimum speed of 1 m/s which can cause it to trigger if the throttle is held low. Not sure why I chose 10cm as the detection cut off for this PR but it could be increased to maybe 50cm because detection is also only allowed in the PR if AGL altitude is trusted (that in itself would have prevented these crashes).

It is interesting about the 0.5m/s.. Emergency Landing descent speed is also 0.5m/s. Which I guess could also lead to a landing detector disarm if the throttle was lowered, if still in radio range.

Increasing it to 50cm shouldn't be a problem from any lidar that works well enough to be worth using..
I only have a Matek VL53L0X sensor. And they're useless in sun light. Otherwise I would have tested it by this. So no.
For the type of flying I do, I don't used them. And I can't really justify buying something like an NRA15 just for testing.

[github-actions]

Test firmware build ready — commit 0f061d3

Download firmware for PR #11425

234 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.

[Copilot]

Pull request overview

Addresses issue #10830 by adjusting SURFACE (terrain-follow) behavior on multicopters to avoid premature landing detection and to make descent behavior more controllable when AGL is not trusted, and adds OSD feedback about SURFACE mode status.

Changes:

• Adjusts SURFACE altitude/throttle handling when AGL is untrusted to make throttle influence descent rate rather than forcing a constant descent.
• Restricts manual-mode “throttle low” landing-detection start condition during SURFACE to cases where AGL is trusted and very low altitude.
• Adds new OSD system messages for SURFACE OK / SURFACE inoperative status and increases system-message array capacity.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/main/navigation/navigation_multicopter.c	Tweaks SURFACE RC-to-altitude / descent behavior and gates manual landing detection when SURFACE is active.
src/main/io/osd.h	Adds SURFACE-related OSD system message strings.
src/main/io/osd.c	Displays SURFACE system messages and increases system-message array size for additional messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sensei-hacker]

@copilot apply changes based on this feedback

[kasatka60]

And I can't really justify buying something like an NRA15 just for testing.

Maybe you should try the mtp-02p? It has a range of 6 meters.
https://ali.click/vi2ec1z

[Jetrell]

Maybe you should try the mtp-02p? It has a range of 6 meters. https://ali.click/vi2ec1z

I'm not fan of Lidar rangefinders. Because they're highly susceptible to sun light causing intermittent or incorrect readings.
While the NRA15 uses K band radar. Making a radar based rangefinder generally more reliable.

[breadoven]

I've "bench" tested this using the Fake rangefinder and it works as expected as far as bench testing allows, i.e. the logic works as expected. AGL altitude was varied using the transmitter scroll wheel. The descent rate ramp up works correctly on the throttle stick and the OSD system messages work as expected.

False landing detection appears to work as intended which is the main point of this PR. It won't trigger a landing with throttle low, quad static and AGL not trusted. When AGL is trusted landing detection becomes more difficult if anything because of the long existing code that looks at the AGL altitude relative to Arming AGL altitude so the main issue here is not detecting a landing more than anything else.

[breadoven]

I'll merge this based on the fake rangefinder testing. It's good enough to confirm the logic works as expected.