skip do_jumps in rtl fast and rtl fast reverse

Author: jonas

docs/en/flight_modes/return.md

@@ -110,11 +110,13 @@ The behaviour is fairly complex because it depends on the flight mode, and wheth
 
 Mission _with_ landing pattern:
 
-- **Mission mode:** Mission is continued in "fast-forward mode" (jumps, delay and any other non-position commands ignored, loiter and other position waypoints converted to simple waypoints) and then lands.
+- **Mission mode:**
+  - Mission is continued in "fast-forward mode" and then lands.
+    - DO_JUMP commands, delays and other non-position mission items are ignored, and loiter and other position waypoints are converted to simple waypoints.
 - **Auto mode other than mission mode:**
   - Ascend to a safe [minimum return altitude](#minimum-return-altitude) above any expected obstacles.
   - Fly directly to closest waypoint (for FW not a landing WP) and descend to waypoint altitude.
-  - Continue mission in fast forward mode from that waypoint.
+  - Continue mission in fast forward mode from that waypoint, using the same traversal rules as above.
 - **Manual modes:**
   - Ascend to a safe [minimum return altitude](#minimum-return-altitude) above any expected obstacles.
   - Fly directly to landing sequence position and descend to waypoint altitude
@@ -137,6 +139,11 @@ If no mission is defined PX4 will fly directly to home location and land (rally
 
 If the mission changes during return mode, then the behaviour is re-evaluated based on the new mission following the same rules as above (e.g. if the new mission has no landing sequence and you're in a mission, the mission is reversed).
 
+::: info
+For `RTL_TYPE=4`, PX4 currently chooses between continuing to a mission landing and reversing toward home by comparing raw mission item indices.
+This is only an approximation of the flown path length, because the number if mission items is not indicative of the distance remaining and non-position items are also counted.
+:::
+
 ### Closest Safe Destination Return Type (RTL_TYPE=3)
 
 In this return type the vehicle:
@@ -208,7 +215,7 @@ The RTL parameters are listed in [Parameter Reference > Return Mode](../advanced
 
 | Parameter                                                                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="RTL_TYPE"></a>[RTL_TYPE](../advanced_config/parameter_reference.md#RTL_TYPE)                         | Return mechanism (path and destination).<br>`0`: Return to a rally point or home (whichever is closest) via direct path.<br>`1`: Return to a rally point or the mission landing pattern start point (whichever is closest), via direct path. If neither mission landing or rally points are defined return home via a direct path. If the destination is a mission landing pattern, follow the pattern to land.<br>`2`: Use mission path fast-forward to landing if a landing pattern is defined, otherwise fast-reverse to home while skipping DO_JUMP and other non-position mission items. Ignore rally points. Fly direct to home if no mission plan is defined.<br>`3`: Return via direct path to closest destination: home, start of mission landing pattern or safe point. If the destination is a mission landing pattern, follow the pattern to land. |
+| <a id="RTL_TYPE"></a>[RTL_TYPE](../advanced_config/parameter_reference.md#RTL_TYPE)                         | Return mechanism (path and destination).<br>`0`: Return to a rally point or home (whichever is closest) via direct path.<br>`1`: Return to a rally point or the mission landing pattern start point (whichever is closest), via direct path. If neither mission landing or rally points are defined return home via a direct path. If the destination is a mission landing pattern, follow the pattern to land.<br>`2`: Use the mission path to landing while skipping DO_JUMP and other non-position mission items if a landing pattern is defined, otherwise fast-reverse to home with the same traversal rules. Ignore rally points. Fly direct to home if no mission plan is defined.<br>`3`: Return via direct path to closest destination: home, start of mission landing pattern or safe point. If the destination is a mission landing pattern, follow the pattern to land. |
 | <a id="RTL_RETURN_ALT"></a>[RTL_RETURN_ALT](../advanced_config/parameter_reference.md#RTL_RETURN_ALT)       | Return altitude in meters (default: 60m) when [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) is 0. If already above this value the vehicle will return at its current altitude.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | <a id="RTL_DESCEND_ALT"></a>[RTL_DESCEND_ALT](../advanced_config/parameter_reference.md#RTL_DESCEND_ALT)    | Minimum return altitude and altitude at which the vehicle will slow or stop its initial descent from a higher return altitude (default: 30m)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | <a id="RTL_LAND_DELAY"></a>[RTL_LAND_DELAY](../advanced_config/parameter_reference.md#RTL_LAND_DELAY)       | Time to wait at `RTL_DESCEND_ALT` before landing (default: 0.5s) -by default this period is short so that the vehicle will simply slow and then land immediately. If set to -1 the system will loiter at `RTL_DESCEND_ALT` rather than landing. The delay is provided to allow you to configure time for landing gear to be deployed (triggered automatically).                                                                                                                                                                                                                                                                                                                                                                                                                                    |

src/modules/navigator/mission.cpp

@@ -130,7 +130,7 @@ Mission::set_current_mission_index(uint16_t index)
 
 bool Mission::setNextMissionItem()
 {
-	return (goToNextItem(MissionTraversalType::FollowMissionControlFlow) == PX4_OK);
+	return (goToNextItem() == PX4_OK);
 }
 
 bool

src/modules/navigator/mission_base.cpp

@@ -1122,6 +1122,12 @@ bool MissionBase::loadTraversalItem(int32_t &mission_index, mission_item_s &miss
 	return loadMissionItemFromCache(mission_index, mission_item);
 }
 
+void MissionBase::getPreviousPositionItems(int32_t start_index, int32_t items_index[],
+		size_t &num_found_items, uint8_t max_num_items)
+{
+	getPreviousPositionItems(start_index, items_index, num_found_items, max_num_items, traversalType());
+}
+
 void MissionBase::getPreviousPositionItems(int32_t start_index, int32_t items_index[],
 		size_t &num_found_items, uint8_t max_num_items, MissionTraversalType traversal_type)
 {
@@ -1147,6 +1153,12 @@ void MissionBase::getPreviousPositionItems(int32_t start_index, int32_t items_in
 	}
 }
 
+void MissionBase::getNextPositionItems(int32_t start_index, int32_t items_index[],
+				       size_t &num_found_items, uint8_t max_num_items)
+{
+	getNextPositionItems(start_index, items_index, num_found_items, max_num_items, traversalType());
+}
+
 void MissionBase::getNextPositionItems(int32_t start_index, int32_t items_index[],
 				       size_t &num_found_items, uint8_t max_num_items,
 				       MissionTraversalType traversal_type)
@@ -1174,6 +1186,11 @@ void MissionBase::getNextPositionItems(int32_t start_index, int32_t items_index[
 	}
 }
 
+int MissionBase::goToNextItem()
+{
+	return goToNextItem(traversalType());
+}
+
 int MissionBase::goToNextItem(MissionTraversalType traversal_type)
 {
 	if (_mission.current_seq + 1 >= (_mission.count)) {
@@ -1183,6 +1200,11 @@ int MissionBase::goToNextItem(MissionTraversalType traversal_type)
 	return goToItem(_mission.current_seq + 1, traversal_type);
 }
 
+int MissionBase::goToPreviousItem()
+{
+	return goToPreviousItem(traversalType());
+}
+
 int MissionBase::goToPreviousItem(MissionTraversalType traversal_type)
 {
 	if (_mission.current_seq <= 0) {
@@ -1192,6 +1214,11 @@ int MissionBase::goToPreviousItem(MissionTraversalType traversal_type)
 	return goToItem(_mission.current_seq - 1, traversal_type, true);
 }
 
+int MissionBase::goToPreviousPositionItem()
+{
+	return goToPreviousPositionItem(traversalType());
+}
+
 int MissionBase::goToPreviousPositionItem(MissionTraversalType traversal_type)
 {
 	int32_t previous_position_item_index{-1};
@@ -1205,6 +1232,11 @@ int MissionBase::goToPreviousPositionItem(MissionTraversalType traversal_type)
 	}
 }
 
+int MissionBase::goToNextPositionItem()
+{
+	return goToNextPositionItem(traversalType());
+}
+
 int MissionBase::goToNextPositionItem(MissionTraversalType traversal_type)
 {
 	int32_t next_position_item_index{-1};

src/modules/navigator/mission_base.h

@@ -105,7 +105,20 @@ class MissionBase : public MissionBlock, public ModuleParams
 	};
 
 	/**
-	 * @brief Get the previous mission position items.
+	 * @brief Get the previous mission position items using this mode's traversal policy.
+	 *
+	 * Convenience overload for callers that want the navigation mode default. Keep the
+	 * explicit traversal overload below for cases that intentionally need different semantics.
+	 *
+	 * @param[in] start_index Index from which to start searching backward
+	 * @param[out] items_index Array of the previous position item indices
+	 * @param[out] num_found_items Number of position items found
+	 * @param[in] max_num_items Maximum number of position items to collect
+	 */
+	void getPreviousPositionItems(int32_t start_index, int32_t items_index[], size_t &num_found_items,
+				      uint8_t max_num_items);
+	/**
+	 * @brief Get the previous mission position items using an explicit traversal policy.
 	 *
 	 * @param[in] start_index Index from which to start searching backward
 	 * @param[out] items_index Array of the previous position item indices
@@ -115,9 +128,19 @@ class MissionBase : public MissionBlock, public ModuleParams
 	 */
 	void getPreviousPositionItems(int32_t start_index, int32_t items_index[], size_t &num_found_items,
 				      uint8_t max_num_items,
-				      MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+				      MissionTraversalType traversal_type);
+	/**
+	 * @brief Get the next mission item containing a position setpoint using this mode's traversal policy.
+	 *
+	 * @param[in] start_index Index from which to start searching forward
+	 * @param[out] items_index Array of the next position item indices
+	 * @param[out] num_found_items Number of position items found
+	 * @param[in] max_num_items Maximum number of position items to collect
+	 */
+	void getNextPositionItems(int32_t start_index, int32_t items_index[], size_t &num_found_items,
+				  uint8_t max_num_items);
 	/**
-	 * @brief Get the next mission item containing a position setpoint.
+	 * @brief Get the next mission item containing a position setpoint using an explicit traversal policy.
 	 *
 	 * @param[in] start_index Index from which to start searching forward
 	 * @param[out] items_index Array of the next position item indices
@@ -127,7 +150,7 @@ class MissionBase : public MissionBlock, public ModuleParams
 	 */
 	void getNextPositionItems(int32_t start_index, int32_t items_index[], size_t &num_found_items,
 				  uint8_t max_num_items,
-				  MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+				  MissionTraversalType traversal_type);
 	/**
 	 * @brief Mission has a land start, a land, and is valid
 	 *
@@ -136,20 +159,35 @@ class MissionBase : public MissionBlock, public ModuleParams
 	 */
 	bool hasMissionLandStart() const { return _mission.land_start_index >= 0 && _mission.land_index >= 0 && isMissionValid();};
 	/**
-	 * @brief Go to next Mission Item
+	 * @brief Go to next Mission Item using this mode's traversal policy.
+	 * Go to next non jump mission item
+	 *
+	 * @return PX4_OK if next mission item exists, PX4_ERR otherwise
+	 */
+	int goToNextItem();
+	/**
+	 * @brief Go to next Mission Item using an explicit traversal policy.
 	 * Go to next non jump mission item
 	 *
 	 * @param[in] traversal_type Whether to follow DO_JUMP mission control flow or ignore DO_JUMP items
 	 * @return PX4_OK if next mission item exists, PX4_ERR otherwise
 	 */
-	int goToNextItem(MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+	int goToNextItem(MissionTraversalType traversal_type);
+	/**
+	 * @brief Go to previous Mission Item using this mode's traversal policy.
+	 * Go to previous non jump mission item
+	 *
+	 * @return PX4_OK if previous mission item exists, PX4_ERR otherwise
+	 */
+	int goToPreviousItem();
 	/**
-	 * @brief Go to previous Mission Item
+	 * @brief Go to previous Mission Item using an explicit traversal policy.
 	 * Go to previous non jump mission item
+	 *
 	 * @param[in] traversal_type Whether to follow DO_JUMP mission control flow or ignore DO_JUMP items
 	 * @return PX4_OK if previous mission item exists, PX4_ERR otherwise
 	 */
-	int goToPreviousItem(MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+	int goToPreviousItem(MissionTraversalType traversal_type);
 	/**
 	 * @brief Go to Mission Item
 	 *
@@ -161,19 +199,31 @@ class MissionBase : public MissionBlock, public ModuleParams
 	int goToItem(int32_t index, MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow,
 		     bool mission_direction_backward = false);
 	/**
-	 * @brief Go To Previous Mission Position Item
+	 * @brief Go To Previous Mission Position Item using this mode's traversal policy.
+	 *
+	 * @return PX4_OK if previous mission item exists, PX4_ERR otherwise
+	 */
+	int goToPreviousPositionItem();
+	/**
+	 * @brief Go To Previous Mission Position Item using an explicit traversal policy.
 	 *
 	 * @param[in] traversal_type Whether to follow DO_JUMP mission control flow or ignore DO_JUMP items
 	 * @return PX4_OK if previous mission item exists, PX4_ERR otherwise
 	 */
-	int goToPreviousPositionItem(MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+	int goToPreviousPositionItem(MissionTraversalType traversal_type);
+	/**
+	 * @brief Go To Next Mission Position Item using this mode's traversal policy.
+	 *
+	 * @return PX4_OK if next mission item exists, PX4_ERR otherwise
+	 */
+	int goToNextPositionItem();
 	/**
-	 * @brief Go To Next Mission Position Item
+	 * @brief Go To Next Mission Position Item using an explicit traversal policy.
 	 *
 	 * @param[in] traversal_type Whether to follow DO_JUMP mission control flow or ignore DO_JUMP items
 	 * @return PX4_OK if next mission item exists, PX4_ERR otherwise
 	 */
-	int goToNextPositionItem(MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+	int goToNextPositionItem(MissionTraversalType traversal_type);
 	/**
 	 * @brief Go to Mission Land Start Item
 	 *
@@ -326,6 +376,18 @@ class MissionBase : public MissionBlock, public ModuleParams
 	 */
 	bool position_setpoint_equal(const position_setpoint_s *p1, const position_setpoint_s *p2) const;
 
+	/**
+	 * @brief Traversal mode used by this navigation mode when walking position items.
+	 *
+	 * Mission mode follows active DO_JUMP control flow by default. Derived modes such as
+	 * mission-based RTL can override this to walk the geometric mission path instead.
+	 * Traversal helpers use this policy unless the caller explicitly overrides it.
+	 */
+	virtual MissionTraversalType traversalType() const
+	{
+		return MissionTraversalType::FollowMissionControlFlow;
+	}
+
 	/**
 	 * @brief Set the Mission Index
 	 *
@@ -353,7 +415,7 @@ class MissionBase : public MissionBlock, public ModuleParams
 	 * @return true if a position item was found
 	 */
 	bool findNextPositionIndex(int32_t start_index, int32_t &next_index,
-				   MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+				   MissionTraversalType traversal_type);
 
 	/**
 	 * @brief Find the previous position mission item.
@@ -366,7 +428,7 @@ class MissionBase : public MissionBlock, public ModuleParams
 	 * @return true if a position item was found
 	 */
 	bool findPreviousPositionIndex(int32_t start_index, int32_t &previous_index,
-				       MissionTraversalType traversal_type = MissionTraversalType::FollowMissionControlFlow);
+				       MissionTraversalType traversal_type);
 
 	bool _is_current_planned_mission_item_valid{false};	/**< Flag indicating if the currently loaded mission item is valid*/
 	bool _mission_has_been_activated{false};		/**< Flag indicating if the mission has been activated*/

src/modules/navigator/rtl_direct_mission_land.cpp

@@ -115,7 +115,7 @@ void RtlDirectMissionLand::on_activation()
 
 bool RtlDirectMissionLand::setNextMissionItem()
 {
-	return (goToNextPositionItem(MissionTraversalType::FollowMissionControlFlow) == PX4_OK);
+	return (goToNextPositionItem() == PX4_OK);
 }
 
 void RtlDirectMissionLand::setActiveMissionItems()

src/modules/navigator/rtl_mission_fast.cpp

@@ -101,7 +101,7 @@ void RtlMissionFast::on_activation()
 
 bool RtlMissionFast::setNextMissionItem()
 {
-	return (goToNextPositionItem(MissionTraversalType::FollowMissionControlFlow) == PX4_OK);
+	return (goToNextPositionItem() == PX4_OK);
 }
 
 void RtlMissionFast::setActiveMissionItems()

src/modules/navigator/rtl_mission_fast.h

@@ -63,6 +63,7 @@ class RtlMissionFast : public RtlBase
 private:
 	bool setNextMissionItem() override;
 	void setActiveMissionItems() override;
+	MissionTraversalType traversalType() const override { return MissionTraversalType::IgnoreDoJump; }
 
 	int32_t _mission_index_prior_rtl{INT32_C(-1)};