fix(commander): report Descend as a distinct flight mode (#27918)

Give NAVIGATION_STATE_DESCEND its own MAVLink custom_mode and advertise it so ground stations stop displaying it as Land. --------- Signed-off-by: Elisa Ferrara <elisa.ferrara@auterion.com>
2026-07-25 13:57:42 +08:00 · 2026-07-21 14:30:07 +02:00
parent e7b1d486e5
commit 841bb40365
11 changed files with 93 additions and 2 deletions
--- a/docs/en/SUMMARY.md
+++ b/docs/en/SUMMARY.md
@@ -17,6 +17,7 @@
      - [Orbit Mode (MC)](flight_modes_mc/orbit.md)
      - [Takeoff Mode (MC)](flight_modes_mc/takeoff.md)
      - [Land Mode (MC)](flight_modes_mc/land.md)
+      - [Descend Mode (MC)](flight_modes_mc/descend.md)
      - [Hold Mode (MC)](flight_modes_mc/hold.md)
      - [Follow Me Mode (MC)](flight_modes_mc/follow_me.md)
      - [Mission Mode (MC)](flight_modes_mc/mission.md)
@@ -74,6 +75,7 @@
    - [Manual Mode (FW)](flight_modes_fw/manual.md)
    - [Takeoff Mode (FW)](flight_modes_fw/takeoff.md)
    - [Land Mode (FW)](flight_modes_fw/land.md)
+    - [Descend Mode (FW)](flight_modes_fw/descend.md)
    - [Hold Mode (FW)](flight_modes_fw/hold.md)
    - [Guided Course Mode (FW)](flight_modes_fw/guided_course.md)
    - [Mission Mode (FW)](flight_modes_fw/mission.md)
--- a/docs/en/_sidebar.md
+++ b/docs/en/_sidebar.md
@@ -15,6 +15,7 @@
      - [Orbit Mode (MC)](/flight_modes_mc/orbit.md)
      - [Takeoff Mode (MC)](/flight_modes_mc/takeoff.md)
      - [Land Mode (MC)](/flight_modes_mc/land.md)
+      - [Descend Mode (MC)](/flight_modes_mc/descend.md)
      - [Hold Mode (MC)](/flight_modes_mc/hold.md)
      - [Follow Me Mode (MC)](/flight_modes_mc/follow_me.md)
      - [Mission Mode (MC)](/flight_modes_mc/mission.md)
@@ -79,6 +80,7 @@
    - [Manual Mode (FW)](/flight_modes_fw/manual.md)
    - [Takeoff Mode (FW)](/flight_modes_fw/takeoff.md)
    - [Land Mode (FW)](/flight_modes_fw/land.md)
+    - [Descend Mode (FW)](/flight_modes_fw/descend.md)
    - [Hold Mode (FW)](/flight_modes_fw/hold.md)
    - [Guided Course Mode (FW)](/flight_modes_fw/guided_course.md)
    - [Mission Mode (FW)](/flight_modes_fw/mission.md)
--- a/docs/en/flight_modes_fw/descend.md
+++ b/docs/en/flight_modes_fw/descend.md
@@ -0,0 +1,37 @@
+# Descend Mode (Fixed-Wing)
+
+_Descend_ is a [failsafe](../config/safety.md) fallback mode.
+It is activated automatically by PX4 and cannot be selected by the pilot. It only appears as a status label.
+
+The vehicle descends open-loop: it circles at a fixed bank angle ([FW_GPSF_R](../advanced_config/parameter_reference.md#FW_GPSF_R)) and descends at a fixed 0.5 m/s, but does not control its ground position, so the circle drifts with the wind.
+It is the last resort used when the vehicle must come down but has no valid position estimate for a controlled descent.
+
+::: info
+
+- Mode is automatic and cannot be selected by the user.
+- Requires only attitude, so it works without a position estimate.
+- The vehicle first loiters at the current altitude for [FW_GPSF_LT](../advanced_config/parameter_reference.md#FW_GPSF_LT) seconds (waiting for the estimate to recover) before starting to descend.
+
+:::
+
+## When It Occurs
+
+Descend is the bottom of the failsafe chain (`Hold → Return → Land → Descend`).
+PX4 falls through to it whenever a failsafe needs to bring the vehicle down or hold position but the position estimate is missing, so none of the higher options can run. For example:
+
+- Losing the position estimate while landing, e.g. GNSS and airspeed sensors fail during [Land](../flight_modes_fw/land.md): the vehicle keeps descending, but now open-loop as _Descend_.
+- Losing the position estimate in [Hold](../flight_modes_fw/hold.md), [Mission](../flight_modes_fw/mission.md) or [Return](../flight_modes_fw/return.md): with no position to hold, fly to, or return with, the failsafe escalates down to _Descend_.
+- A Return or Land failsafe (from manual control loss, GCS/data link loss, low battery, geofence breach, …) triggered while no valid position estimate is available: Return and Land can't run, so it degrades to _Descend_.
+
+## Exiting Descend
+
+Descend ends when either:
+
+- the failsafe condition is resolved (e.g. the position estimate recovers), and the vehicle returns to its previous mode; or
+- the pilot takes over by switching to a manual mode ([Position](../flight_modes_fw/position.md), [Altitude](../flight_modes_fw/altitude.md) or [Stabilized](../flight_modes_fw/stabilized.md)).
+
+## See Also
+
+- [Descend Mode (MC)](../flight_modes_mc/descend.md)
+- [Land Mode (FW)](../flight_modes_fw/land.md)
+- [Safety (Failsafes)](../config/safety.md)
--- a/docs/en/flight_modes_fw/index.md
+++ b/docs/en/flight_modes_fw/index.md
@@ -47,6 +47,7 @@ Airspeed is actively controlled if an airspeed sensor is installed in any autono
 - [Mission](../flight_modes_fw/mission.md) — Vehicle executes a [predefined mission/flight plan](../flying/missions.md) that has been uploaded to the flight controller.
 - [Takeoff](../flight_modes_fw/takeoff.md) — Vehicle initiates the takeoff sequence using either _catapult/hand-launch mode_ or _runway takeoff mode_ (in the current direction).
 - [Land](../flight_modes_fw/land.md) — Vehicle initiates the [fixed-wing landing sequence](../flight_modes_fw/mission.md#mission-landing).
+- [Descend](../flight_modes_fw/descend.md) — Failsafe fallback: the vehicle circles down at a fixed bank angle without position control (used when the position estimate is lost). Not pilot-selectable.
 - [Offboard](../flight_modes_fw/offboard.md) — Vehicle obeys attitude setpoints provided via MAVLink or ROS 2.

 Pilots transition between flight modes using switches on the remote control or with a ground control station (see [Flight Mode Configuration](../config/flight_mode.md)).
--- a/docs/en/flight_modes_mc/descend.md
+++ b/docs/en/flight_modes_mc/descend.md
@@ -0,0 +1,37 @@
+# Descend Mode (Multicopter)
+
+_Descend_ is a [failsafe](../config/safety.md) fallback mode.
+It is activated automatically by PX4 and cannot be selected by the pilot. It only appears as a status label.
+
+The vehicle descends open-loop: it keeps its attitude and reduces altitude, but does not control its horizontal position, so it drifts with the wind.
+It is the last resort used when the vehicle must come down but has no valid position estimate for a controlled descent.
+
+::: info
+
+- Mode is automatic and cannot be selected by the user.
+- Requires only attitude, so it works without a position (or even altitude) estimate.
+- The descent rate is set by [MPC_LAND_SPEED](../advanced_config/parameter_reference.md#MPC_LAND_SPEED).
+
+:::
+
+## When It Occurs
+
+Descend is the bottom of the failsafe chain (`Hold → Return → Land → Descend`).
+PX4 falls through to it whenever a failsafe needs to bring the vehicle down or hold position but the position estimate is missing, so none of the higher options can run. For example:
+
+- Losing the position estimate while landing, e.g. GNSS fails during [Land](../flight_modes_mc/land.md): the vehicle keeps descending, but now open-loop as _Descend_.
+- Losing the position estimate in [Hold](../flight_modes_mc/hold.md), [Mission](../flight_modes_mc/mission.md) or [Return](../flight_modes_mc/return.md): with no position to hold, fly to, or return with, the failsafe escalates down to _Descend_.
+- A Return or Land failsafe (from manual control loss, GCS/data link loss, low battery, geofence breach, …) triggered while no valid position estimate is available: Return and Land can't run, so it degrades to _Descend_.
+
+## Exiting Descend
+
+Descend ends when either:
+
+- the failsafe condition is resolved (e.g. the position estimate recovers), and the vehicle returns to its previous mode; or
+- the pilot takes over by switching to a manual mode ([Position](../flight_modes_mc/position.md), [Altitude](../flight_modes_mc/altitude.md) or [Stabilized](../flight_modes_mc/manual_stabilized.md)). On a multicopter, moving the sticks does this [by default](../flight_modes_mc/land.md#MAN_OVERRIDE_SPD).
+
+## See Also
+
+- [Descend Mode (FW)](../flight_modes_fw/descend.md)
+- [Land Mode (MC)](../flight_modes_mc/land.md)
+- [Safety (Failsafes)](../config/safety.md)
--- a/docs/en/flight_modes_mc/index.md
+++ b/docs/en/flight_modes_mc/index.md
@@ -38,6 +38,7 @@ Autonomous:
  This requires a global position estimate (GPS).
 - [Takeoff](../flight_modes_mc/takeoff.md) — Vehicle takes off vertically and then switches to _Hold mode_.
 - [Land](../flight_modes_mc/land.md) — Vehicle lands immediately.
+- [Descend](../flight_modes_mc/descend.md) — Failsafe fallback: the vehicle descends without horizontal position control (used when the position estimate is lost). Not pilot-selectable.
 - [Orbit](../flight_modes_mc/orbit.md) - Vehicle flys in a circle, yawing so that it always faces towards the center.
  RC control can optionally be used to change the orbit radius, direction, speed and so on.
 - [Follow Me](../flight_modes_mc/follow_me.md) — Vehicle follows a beacon that is providing position setpoints.
--- a/src/lib/events/enums.json
+++ b/src/lib/events/enums.json
@@ -608,6 +608,10 @@
                            "name": "auto_course",
                            "description": "Course"
                        },
+                        "26": {
+                            "name": "descend",
+                            "description": "Descend"
+                        },
                        "255": {
                            "name": "unknown",
                            "description": "[Unknown]"
@@ -741,6 +745,7 @@
                    "7": [319029248],
                    "8": [720896],
                    "10": [327680],
+                    "12": [335806464],
                    "14": [393216],
                    "15": [458752],
                    "17": [33816576],
--- a/src/lib/modes/ui.hpp
+++ b/src/lib/modes/ui.hpp
@@ -60,6 +60,7 @@ static inline uint32_t getValidNavStates()
 	       (1u << vehicle_status_s::NAVIGATION_STATE_STAB) |
 	       (1u << vehicle_status_s::NAVIGATION_STATE_AUTO_TAKEOFF) |
 	       (1u << vehicle_status_s::NAVIGATION_STATE_AUTO_LAND) |
+	       (1u << vehicle_status_s::NAVIGATION_STATE_DESCEND) |
 	       (1u << vehicle_status_s::NAVIGATION_STATE_AUTO_FOLLOW_TARGET) |
 	       (1u << vehicle_status_s::NAVIGATION_STATE_AUTO_PRECLAND) |
 	       (1u << vehicle_status_s::NAVIGATION_STATE_ORBIT) |
--- a/src/modules/commander/ModeManagement.cpp
+++ b/src/modules/commander/ModeManagement.cpp
@@ -693,7 +693,9 @@ void ModeManagement::checkConfigOverrides()
 void ModeManagement::getModeStatus(uint32_t &valid_nav_state_mask, uint32_t &can_set_nav_state_mask) const
 {
 	valid_nav_state_mask = mode_util::getValidNavStates();
-	can_set_nav_state_mask = valid_nav_state_mask & ~(1u << vehicle_status_s::NAVIGATION_STATE_TERMINATION);
+	can_set_nav_state_mask = valid_nav_state_mask
+				 & ~((1u << vehicle_status_s::NAVIGATION_STATE_TERMINATION)
+				     | (1u << vehicle_status_s::NAVIGATION_STATE_DESCEND));

 	// Add external modes
 	for (int i = Modes::FIRST_EXTERNAL_NAV_STATE; i <= Modes::LAST_EXTERNAL_NAV_STATE; ++i) {
--- a/src/modules/commander/ModeUtil/conversions.hpp
+++ b/src/modules/commander/ModeUtil/conversions.hpp
@@ -74,6 +74,8 @@ static inline navigation_mode_t navigation_mode(uint8_t nav_state)

 	case vehicle_status_s::NAVIGATION_STATE_AUTO_LAND: return navigation_mode_t::auto_land;

+	case vehicle_status_s::NAVIGATION_STATE_DESCEND: return navigation_mode_t::descend;
+
 	case vehicle_status_s::NAVIGATION_STATE_AUTO_FOLLOW_TARGET: return navigation_mode_t::auto_follow_target;

 	case vehicle_status_s::NAVIGATION_STATE_AUTO_PRECLAND: return navigation_mode_t::auto_precland;
--- a/src/modules/commander/px4_custom_mode.h
+++ b/src/modules/commander/px4_custom_mode.h
@@ -77,6 +77,7 @@ enum PX4_CUSTOM_SUB_MODE_AUTO {
 	PX4_CUSTOM_SUB_MODE_EXTERNAL7,
 	PX4_CUSTOM_SUB_MODE_EXTERNAL8,
 	PX4_CUSTOM_SUB_MODE_GUIDED_COURSE,
+	PX4_CUSTOM_SUB_MODE_AUTO_DESCEND,
 };

 enum PX4_CUSTOM_SUB_MODE_POSCTL {
@@ -150,7 +151,7 @@ static inline union px4_custom_mode get_px4_custom_mode(uint8_t nav_state)

 	case vehicle_status_s::NAVIGATION_STATE_DESCEND:
 		custom_mode.main_mode = PX4_CUSTOM_MAIN_MODE_AUTO;
-		custom_mode.sub_mode = PX4_CUSTOM_SUB_MODE_AUTO_LAND;
+		custom_mode.sub_mode = PX4_CUSTOM_SUB_MODE_AUTO_DESCEND;
 		break;

 	case vehicle_status_s::NAVIGATION_STATE_TERMINATION: