diff --git a/.github/instructions/system.instructions.md b/.github/instructions/system.instructions.md index 626efd9f185..38e42378b9d 100644 --- a/.github/instructions/system.instructions.md +++ b/.github/instructions/system.instructions.md @@ -8,7 +8,7 @@ In addition to the core code review guidelines: - Race conditions and concurrency: no partial fixes, demand complete solutions - Semaphore/scheduling edge cases; understand RTOS guarantees -- State machine sequential-logic bugs (consecutive RTL, armed/disarmed alternation) +- State machine sequential-logic bugs (consecutive Return, armed/disarmed alternation) - Use uORB-driven scheduling (`SubscriptionCallback`), not extra threads - `param_set` triggers auto-save; no redundant `param_save_default` - Flash/memory efficiency: avoid `std::string` on embedded, minimize SubscriptionData usage diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43219e51930..8a385674a7c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,7 +66,7 @@ The scope identifies which part of PX4 is affected. Common scopes: | `ekf2` | Extended Kalman Filter (state estimation) | | `mavlink` | MAVLink messaging protocol | | `commander` | Commander and mode management | -| `navigator` | Mission, RTL, Land, and other navigation modes | +| `navigator` | Mission, Return, Land, and other navigation modes | | `sensors` | Sensor drivers and processing | | `drivers` | Hardware drivers | | `boards/px4_fmu-v6x` | Board-specific changes (use the board name) | @@ -99,7 +99,7 @@ feat(ekf2)!: remove deprecated height fusion API ``` feat(ekf2): add height fusion timeout fix(mavlink): correct BATTERY_STATUS_V2 parsing -refactor(navigator): simplify RTL altitude logic +refactor(navigator): simplify return altitude logic ci(workflows): migrate to reusable workflows docs(ekf2): update tuning guide feat(boards/px4_fmu-v6x)!: remove deprecated driver API diff --git a/ROMFS/px4fmu_common/init.d-posix/airframes/4006_gz_px4vision b/ROMFS/px4fmu_common/init.d-posix/airframes/4006_gz_px4vision index 135bb93152b..bbc2e791ed1 100644 --- a/ROMFS/px4fmu_common/init.d-posix/airframes/4006_gz_px4vision +++ b/ROMFS/px4fmu_common/init.d-posix/airframes/4006_gz_px4vision @@ -75,7 +75,7 @@ param set-default CP_GO_NO_DATA 1 # Navigator Parameters param set-default NAV_ACC_RAD 2 -# RTL Parameters +# Return Parameters param set-default RTL_DESCEND_ALT 5 param set-default RTL_RETURN_ALT 5 diff --git a/ROMFS/px4fmu_common/init.d/airframes/4016_holybro_px4vision b/ROMFS/px4fmu_common/init.d/airframes/4016_holybro_px4vision index 3934c446906..114ec59d649 100644 --- a/ROMFS/px4fmu_common/init.d/airframes/4016_holybro_px4vision +++ b/ROMFS/px4fmu_common/init.d/airframes/4016_holybro_px4vision @@ -73,7 +73,7 @@ param set-default CP_GO_NO_DATA 1 # Navigator Parameters param set-default NAV_ACC_RAD 2 -# RTL Parameters +# Return Parameters param set-default RTL_DESCEND_ALT 5 param set-default RTL_RETURN_ALT 5 diff --git a/ROMFS/px4fmu_common/init.d/airframes/4020_holybro_px4vision_v1_5 b/ROMFS/px4fmu_common/init.d/airframes/4020_holybro_px4vision_v1_5 index 173b21ed167..d3df25438f8 100644 --- a/ROMFS/px4fmu_common/init.d/airframes/4020_holybro_px4vision_v1_5 +++ b/ROMFS/px4fmu_common/init.d/airframes/4020_holybro_px4vision_v1_5 @@ -74,7 +74,7 @@ param set-default CP_GO_NO_DATA 1 # Navigator Parameters param set-default NAV_ACC_RAD 2 -# RTL Parameters +# Return Parameters param set-default RTL_DESCEND_ALT 5 param set-default RTL_RETURN_ALT 5 diff --git a/Tools/bench_test/README.md b/Tools/bench_test/README.md index fa56031bc99..96ca0a46f40 100644 --- a/Tools/bench_test/README.md +++ b/Tools/bench_test/README.md @@ -196,7 +196,7 @@ why the stress tests loop. | bench/storage_stress | SD card and FAT filesystem under the logger's feet | Sequential write/read below the floor, fsync latency spikes that cause log dropouts, or file churn failures | | bench/log_transfer | logger + MAVFTP (FILE_TRANSFER_PROTOCOL replies are nested sends) | A burst-read download that stops mid-file, or a ULog that fails integrity checks | | bench/serial_loopback | UART driver TX/RX path through a physical loopback jumper (fixture) | Lost or corrupted bytes through the jumper, or a port that cannot sustain the byte rate | -| sih/flight_mission | commander/navigator/land-detector flight logic on real NuttX scheduling | Arming, takeoff, waypoint progression, RTL, land detection or auto-disarm failing per-phase timeouts | +| sih/flight_mission | commander/navigator/land-detector flight logic on real NuttX scheduling | Arming, takeoff, waypoint progression, Return, land detection or auto-disarm failing per-phase timeouts | ## Bench tests (real firmware, no simulation) @@ -339,7 +339,7 @@ Skips with a warning when the firmware lacks `serial_test` Switches the board to a SIH airframe (`SYS_AUTOSTART=1100`, `SYS_HITL=2`, physics simulated on the FMU, `pwm_out_sim` in place of real outputs), flies -takeoff, a 3-waypoint square, and RTL as an auto mission with per-phase +takeoff, a 3-waypoint square, and Return as an auto mission with per-phase timeouts (arming, airborne, waypoint progression, touchdown, auto-disarm), downloads the flight ULog, and restores the original configuration even on failure. diff --git a/Tools/bench_test/sih/flight_mission.py b/Tools/bench_test/sih/flight_mission.py index 0b8861c5132..72e40a98e15 100755 --- a/Tools/bench_test/sih/flight_mission.py +++ b/Tools/bench_test/sih/flight_mission.py @@ -5,7 +5,7 @@ Scripted SIH flight on real hardware: switch the board to a SIH airframe restore the original configuration. Covers the flight-logic paths the rest of the bench suite cannot: commander -arming, navigator/mission progression, auto takeoff, RTL, land detection and +arming, navigator/mission progression, auto takeoff, Return, land detection and auto-disarm, all on real NuttX scheduling. The physics is simulated; real sensor drivers and real outputs are not exercised (pwm_out_sim replaces them, so nothing on the output rails is ever driven). @@ -48,7 +48,7 @@ WP_OFFSET_DEG = 0.0005 # ~55 m legs def build_flight_mission(alt): - """Takeoff, 3-waypoint square leg, RTL. Reuses px4bench.missions.Item.""" + """Takeoff, 3-waypoint square leg, Return. Reuses px4bench.missions.Item.""" home_lat = int(BASE_LAT * 1e7) home_lon = int(BASE_LON * 1e7) off = int(WP_OFFSET_DEG * 1e7) @@ -65,7 +65,7 @@ def build_flight_mission(alt): rtl = Item(len(items), 0, 0, 0, 0) rtl.command = MAV_CMD_NAV_RETURN_TO_LAUNCH - # RTL carries no coordinates; the position frame would (correctly) fail + # Return carries no coordinates; the position frame would (correctly) fail # the parameter validation added in #27541 with INVALID_PARAM5_X. rtl.frame = mavutil.mavlink.MAV_FRAME_MISSION rtl.param2 = 0.0 @@ -285,7 +285,7 @@ def fly(report, mav, shell, alt, report_dir): f.write(out) report.info('captured in-flight uorb top') report.check('waypoints', len(reached) >= n_wp - 2, - 'reached {} of {} pre-RTL items'.format(len(reached), n_wp - 2)) + 'reached {} of {} pre-Return items'.format(len(reached), n_wp - 2)) if len(reached) < n_wp - 2: return False diff --git a/docs/en/advanced_features/detect_and_avoid.md b/docs/en/advanced_features/detect_and_avoid.md index 1eab0794797..1406be78e5a 100644 --- a/docs/en/advanced_features/detect_and_avoid.md +++ b/docs/en/advanced_features/detect_and_avoid.md @@ -866,8 +866,8 @@ Under those assumptions, the expected operator-visible messages for each scenari - Hold triggered on augmented WC breach: `DAA 9F3FA3: Hold! lvl 1. 2366 m.` - `DAA Main: 9F3FA3 lvl UP 2. 1773 m.` - Return triggered on augmented NMAC breach: `DAA 9F3FA3: Return! lvl 2. 1773 m.` - - `[commander] Returning to launch` - - `[navigator] RTL: start return at 519 m (30 m above destination)` + - `[commander] Switching to Return` + - `[navigator] Return: start return at 519 m (30 m above destination)` - `DAA Main: 9F3FA3 lvl 2. 849 m.` (the periodic most-urgent status, emitted because the level held at 2 for [DAA_NOTIF_STATE](../advanced_config/parameter_reference.md#DAA_NOTIF_STATE) since the previous `9F3FA3` message) - `DAA Main: 9F3FA3 lvl UP 3. 527 m.` - Land triggered on WC breach: `DAA 9F3FA3: Land! lvl 3. 527 m.` diff --git a/docs/en/advanced_features/precland.md b/docs/en/advanced_features/precland.md index 9ae4660500b..2028817d2b2 100644 --- a/docs/en/advanced_features/precland.md +++ b/docs/en/advanced_features/precland.md @@ -196,7 +196,7 @@ Some of the most useful ones are listed below. | [PLD_FAPPR_ALT](../advanced_config/parameter_reference.md#PLD_FAPPR_ALT) | Final approach altitude. Default is 0.1 metres. | | [PLD_MAX_SRCH](../advanced_config/parameter_reference.md#PLD_MAX_SRCH) | Maximum number of search attempts in a required landing. | | [PLD_YAW_EN](../advanced_config/parameter_reference.md#PLD_YAW_EN) | Enable yaw alignment during precision landing when target orientation is available. | -| [RTL_PLD_MD](../advanced_config/parameter_reference.md#RTL_PLD_MD) | RTL precision land mode. `0`: disabled, `1`: [Opportunistic](#opportunistic-mode), `2`: [Required](#required-mode). | +| [RTL_PLD_MD](../advanced_config/parameter_reference.md#RTL_PLD_MD) | Return precision land mode. `0`: disabled, `1`: [Opportunistic](#opportunistic-mode), `2`: [Required](#required-mode). | ### IR Beacon Scaling diff --git a/docs/en/companion_computer/video_streaming_wfb_ng_wifi.md b/docs/en/companion_computer/video_streaming_wfb_ng_wifi.md index 1c8194297fb..34c09f1a661 100644 --- a/docs/en/companion_computer/video_streaming_wfb_ng_wifi.md +++ b/docs/en/companion_computer/video_streaming_wfb_ng_wifi.md @@ -144,7 +144,7 @@ With Alfa AWU036ACH and 20dBi patch antenna on the ground ~20km is possible. :::warning Don't use band that the RC TX operates on! -Or setup RTL properly to avoid model loss. +Or set up Return mode properly to avoid model loss. ::: **Q:** _Is only Raspberry PI supported?_ diff --git a/docs/en/concept/events_interface.md b/docs/en/concept/events_interface.md index 71e37f8f997..3d6b3c7af18 100644 --- a/docs/en/concept/events_interface.md +++ b/docs/en/concept/events_interface.md @@ -94,7 +94,7 @@ Explanations and requirements: - Above we specify a separate external and internal log level, which are the levels displayed to GCS users and in the log file, respectively: `{events::Log::Error, events::LogInternal::Info}`. For the majority of cases you can pass a single log level, and this will be used for both external and internal cases. There are cases it makes sense to have two different log levels. - For example an RTL failsafe action: the user should see it as Warning/Error, whereas in the log, it is an expected system response, so it can be set to `Info`. + For example a Return failsafe action: the user should see it as Warning/Error, whereas in the log, it is an expected system response, so it can be set to `Info`. - **Event Message**: - Single-line, short message of the event. diff --git a/docs/en/config/safety.md b/docs/en/config/safety.md index 6856e51b5e6..877ae4c82f7 100644 --- a/docs/en/config/safety.md +++ b/docs/en/config/safety.md @@ -141,7 +141,7 @@ Additional (and underlying) parameter settings are shown below. | Parameter | Setting | Description | | ----------------------------------------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [COM_RC_LOSS_T](../advanced_config/parameter_reference.md#COM_RC_LOSS_T) | Manual Control Loss Timeout | Time after last setpoint received from the selected manual control source after which manual control is considered lost. This must be kept short because the vehicle will continue to fly using the last known stick position until the timeout triggers. | -| [COM_FAIL_ACT_T](../advanced_config/parameter_reference.md#COM_FAIL_ACT_T) | Failsafe Reaction Delay | Delay in seconds between failsafe condition being triggered (`COM_RC_LOSS_T`) and failsafe action (RTL, Land, Hold). In this state the vehicle waits in hold mode for the manual control source to reconnect. This might be set longer for long-range flights so that intermittent connection loss doesn't immediately invoke the failsafe. It can be to zero so that the failsafe triggers immediately. | +| [COM_FAIL_ACT_T](../advanced_config/parameter_reference.md#COM_FAIL_ACT_T) | Failsafe Reaction Delay | Delay in seconds between failsafe condition being triggered (`COM_RC_LOSS_T`) and failsafe action (Return, Land, Hold). In this state the vehicle waits in hold mode for the manual control source to reconnect. This might be set longer for long-range flights so that intermittent connection loss doesn't immediately invoke the failsafe. It can be to zero so that the failsafe triggers immediately. | | [NAV_RCL_ACT](../advanced_config/parameter_reference.md#NAV_RCL_ACT) | Failsafe Action | Disabled, Loiter, Return, Land, Disarm, Terminate, Hold mode (no failsafe). | | [COM_RCL_EXCEPT](../advanced_config/parameter_reference.md#COM_RCL_EXCEPT) | RC Loss Exceptions | Set modes in which manual control loss is ignored. | diff --git a/docs/en/flight_modes/return.md b/docs/en/flight_modes/return.md index a471d569381..e8d7eda57a1 100644 --- a/docs/en/flight_modes/return.md +++ b/docs/en/flight_modes/return.md @@ -228,7 +228,7 @@ Things like path tracking error, wind and other disturbances may cause temporary It is therefore very important to consider this possibility and especially to review the geofence breach action (e.g. [GF_ACTION](../advanced_config/parameter_reference.md#GF_ACTION)). ::: -### RTL-types with Geofence-Awareness +### Return Types with Geofence Awareness The following table shows which return types currently support geofence awareness: @@ -321,7 +321,7 @@ For this reason fixed-wing vehicles are configured to use [Mission landing/reall ## Parameters -The RTL parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode) (and summarised below). +The Return parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode) (and summarised below). | Parameter | Description | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -330,10 +330,10 @@ The RTL parameters are listed in [Parameter Reference > Return Mode](../advanced | [RTL_DESCEND_ALT](../advanced_config/parameter_reference.md#RTL_DESCEND_ALT) | Altitude above the destination used for the final descent before landing or loitering (default: 30m). | | [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). | | [RTL_MIN_DIST](../advanced_config/parameter_reference.md#RTL_MIN_DIST) | Within this distance from the return destination, the return altitude is calculated from the "cone" rather than directly from `RTL_RETURN_ALT`. | -| [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) | Half-angle of the cone that defines the vehicle RTL return altitude. Values (in degrees): `0`, `25`, `45`, `65`, `80`, `90`. Note that `0` is "no cone" (always return at `RTL_RETURN_ALT` or higher), while `90` indicates an almost vertical cone, so the vehicle generally returns at its current altitude when close to the destination. The return altitude may still be constrained to avoid flying too low while approaching the destination. | -| [RTL_APPR_FORCE](../advanced_config/parameter_reference.md#RTL_APPR_FORCE) | [VTOL FW only] If set, home or rally-point RTL destinations are only considered when a valid VTOL approach loiter is defined for that landing location. Mission landing patterns are unaffected. | +| [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) | Half-angle of the cone that defines the vehicle return altitude. Values (in degrees): `0`, `25`, `45`, `65`, `80`, `90`. Note that `0` is "no cone" (always return at `RTL_RETURN_ALT` or higher), while `90` indicates an almost vertical cone, so the vehicle generally returns at its current altitude when close to the destination. The return altitude may still be constrained to avoid flying too low while approaching the destination. | +| [RTL_APPR_FORCE](../advanced_config/parameter_reference.md#RTL_APPR_FORCE) | [VTOL FW only] If set, home or rally-point return destinations are only considered when a valid VTOL approach loiter is defined for that landing location. Mission landing patterns are unaffected. | | [MAN_OVERRIDE_SPD](../advanced_config/parameter_reference.md#MAN_OVERRIDE_SPD) | Speed (normalized stick travel per second) above which moving the sticks controlling a multicopter (or VTOL in hover) gives control back to the pilot by switching to [Position mode](../flight_modes_mc/position.md) (or Altitude mode if position is unavailable). At the default 1 a half-stick movement in ~0.5 s triggers it; lower is more sensitive. A stick held statically has zero speed and will not trigger. Set to -1 to disable. | | [RTL_LOITER_RAD](../advanced_config/parameter_reference.md#RTL_LOITER_RAD) | [Fixed-wing Only] The radius of the loiter circle (at [RTL_LAND_DELAY](#RTL_LAND_DELAY)). | | [MIS_TKO_LAND_REQ](../advanced_config/parameter_reference.md#MIS_TKO_LAND_REQ) | Specify whether a mission landing or takeoff pattern is _required_. Generally fixed-wing vehicles set this to require a landing pattern but VTOL do not. | -| [RTL_TIME_FACTOR](../advanced_config/parameter_reference.md#RTL_TIME_FACTOR) | RTL time estimate safety factor. | -| [RTL_TIME_MARGIN](../advanced_config/parameter_reference.RTL_TIME_MARGIN) | RTL time estimate safety margin. | +| [RTL_TIME_FACTOR](../advanced_config/parameter_reference.md#RTL_TIME_FACTOR) | Return time estimate safety factor. | +| [RTL_TIME_MARGIN](../advanced_config/parameter_reference.md#RTL_TIME_MARGIN) | Return time estimate safety margin. | diff --git a/docs/en/flight_modes_fw/mission.md b/docs/en/flight_modes_fw/mission.md index 20135b5829a..8fec509e22a 100644 --- a/docs/en/flight_modes_fw/mission.md +++ b/docs/en/flight_modes_fw/mission.md @@ -99,7 +99,7 @@ A subset of the most important checks are listed below: - Any mission item conflicts with a plan or safety geofence - More than one land start mission item defined ([MAV_CMD_DO_LAND_START](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_LAND_START)) - A fixed-wing landing has an infeasible slope angle ([FW_LND_ANG](#FW_LND_ANG)) -- Land start item (`MAV_CMD_DO_LAND_START`) appears in mission before an RTL item ([MAV_CMD_NAV_RETURN_TO_LAUNCH](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_RETURN_TO_LAUNCH)) +- Land start item (`MAV_CMD_DO_LAND_START`) appears in mission before an RTL ("Return") item ([MAV_CMD_NAV_RETURN_TO_LAUNCH](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_RETURN_TO_LAUNCH)) - Missing takeoff and/or land item when these are configured as a requirement ([MIS_TKO_LAND_REQ](#MIS_TKO_LAND_REQ)) Additionally there is a check if the first waypoint is too far from the Home position ([MIS_DIST_1WP](#MIS_DIST_1WP)). diff --git a/docs/en/flight_modes_fw/return.md b/docs/en/flight_modes_fw/return.md index 6aac72b368b..b2d0dc181e8 100644 --- a/docs/en/flight_modes_fw/return.md +++ b/docs/en/flight_modes_fw/return.md @@ -65,7 +65,7 @@ The following requirements must be met to arm in this mode, or to switch to this ## Parameters -The RTL parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode). +The Return parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode). If using a mission landing, only the [RTL_RETURN_ALT](#RTL_RETURN_ALT) and [RTL_DESCEND_ALT](#RTL_DESCEND_ALT) are relevant. The others are relevant if the destination is a rally point or the home location. diff --git a/docs/en/flight_modes_mc/return.md b/docs/en/flight_modes_mc/return.md index 5ce1793cd03..ccb370c289e 100644 --- a/docs/en/flight_modes_mc/return.md +++ b/docs/en/flight_modes_mc/return.md @@ -73,7 +73,7 @@ For more information on this return type see [Home/Rally Point Return Type (RTL_ ## Parameters -The RTL parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode). +The Return parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode). The parameters that are relevant to multicopter (assuming the [RTL_TYPE](../advanced_config/parameter_reference.md#RTL_TYPE) is set to 0) are listed below. @@ -83,7 +83,7 @@ The parameters that are relevant to multicopter (assuming the [RTL_TYPE](../adva | [RTL_DESCEND_ALT](../advanced_config/parameter_reference.md#RTL_DESCEND_ALT) | Altitude above the destination used for the final descent before landing or loitering (default: 30m). | | [RTL_LAND_DELAY](../advanced_config/parameter_reference.md#RTL_LAND_DELAY) | Time to hover 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). | | [RTL_MIN_DIST](../advanced_config/parameter_reference.md#RTL_MIN_DIST) | Within this distance from the home position, the return altitude is calculated from the "cone" rather than directly from `RTL_RETURN_ALT`. | -| [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) | Half-angle of the cone that defines the vehicle RTL return altitude. Values (in degrees): `0`, `25`, `45`, `65`, `80`, `90`. Note that `0` is "no cone" (always return at `RTL_RETURN_ALT` or higher), while `90` indicates an almost vertical cone, so the vehicle generally returns at its current altitude when close to the destination. The return altitude may still be constrained to avoid flying too low while approaching the destination. | +| [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) | Half-angle of the cone that defines the vehicle return altitude. Values (in degrees): `0`, `25`, `45`, `65`, `80`, `90`. Note that `0` is "no cone" (always return at `RTL_RETURN_ALT` or higher), while `90` indicates an almost vertical cone, so the vehicle generally returns at its current altitude when close to the destination. The return altitude may still be constrained to avoid flying too low while approaching the destination. | | [MAN_OVERRIDE_SPD](../advanced_config/parameter_reference.md#MAN_OVERRIDE_SPD) | Speed (normalized stick travel per second) above which moving the sticks controlling a multicopter (or VTOL in hover) gives control back to the pilot by switching to [Position mode](../flight_modes_mc/position.md) (or Altitude mode if position is unavailable). At the default value of 1 a half-stick movement in ~0.5 s triggers it; lower is more sensitive. A stick held statically has zero speed and will not trigger. Set to -1 to disable. | ## See Also diff --git a/docs/en/flight_modes_vtol/return.md b/docs/en/flight_modes_vtol/return.md index de101bd85fb..0ee79d6705e 100644 --- a/docs/en/flight_modes_vtol/return.md +++ b/docs/en/flight_modes_vtol/return.md @@ -75,7 +75,7 @@ When uploading VTOL approach loiters through MAVLink, [upload them as rally/safe The `MAV_CMD_NAV_RALLY_POINT` item must come first, followed by one or more `MAV_CMD_NAV_LOITER_TO_ALT` items that define the approach loiters for that rally point. The next `MAV_CMD_NAV_RALLY_POINT` starts a new landing-location block. -For each `MAV_CMD_NAV_LOITER_TO_ALT` item, `x/y/z` define the loiter center and approach altitude, and `param2` defines the loiter radius used by RTL. +For each `MAV_CMD_NAV_LOITER_TO_ALT` item, `x/y/z` define the loiter center and approach altitude, and `param2` defines the loiter radius used by Return mode. If `param2` is unset or zero, PX4 falls back to [RTL_LOITER_RAD](#RTL_LOITER_RAD). For example, a rally upload with one rally point and two possible approach loiters would use: @@ -99,16 +99,16 @@ If returning as a multicopter: ## Parameters -The RTL parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode). +The Return parameters are listed in [Parameter Reference > Return Mode](../advanced_config/parameter_reference.md#return-mode). If using a mission landing, only the [RTL_RETURN_ALT](#RTL_RETURN_ALT) and [RTL_DESCEND_ALT](#RTL_DESCEND_ALT) are relevant. The others are relevant if the destination is a rally point or the home location. | Parameter | Description | | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [RTL_TYPE](../advanced_config/parameter_reference.md#RTL_TYPE) | Return type. | -| [RTL_APPR_FORCE](../advanced_config/parameter_reference.md#RTL_APPR_FORCE) | [VTOL FW only] If set, PX4 only considers home or rally-point RTL destinations when a valid VTOL approach loiter is defined for that landing location. Mission landing patterns are unaffected. | +| [RTL_APPR_FORCE](../advanced_config/parameter_reference.md#RTL_APPR_FORCE) | [VTOL FW only] If set, PX4 only considers home or rally-point return destinations when a valid VTOL approach loiter is defined for that landing location. Mission landing patterns are unaffected. | | [RTL_RETURN_ALT](../advanced_config/parameter_reference.md#RTL_RETURN_ALT) | Return altitude in meters (default: 60m)If already above this value the vehicle will return at its current altitude. | -| [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) | Half-angle of the cone that defines the vehicle RTL return altitude. Values (in degrees): 0, 25, 45, 65, 80, 90. Note that 0 is "no cone" (always return at `RTL_RETURN_ALT` or higher), while 90 indicates that the vehicle must return at the current altitude or `RTL_DESCEND_ALT` (whichever is higher). | +| [RTL_CONE_ANG](../advanced_config/parameter_reference.md#RTL_CONE_ANG) | Half-angle of the cone that defines the vehicle return altitude. Values (in degrees): 0, 25, 45, 65, 80, 90. Note that 0 is "no cone" (always return at `RTL_RETURN_ALT` or higher), while 90 indicates that the vehicle must return at the current altitude or `RTL_DESCEND_ALT` (whichever is higher). | | [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) | | [RTL_LAND_DELAY](../advanced_config/parameter_reference.md#RTL_LAND_DELAY) | Time to hover 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). | | [RTL_LOITER_RAD](../advanced_config/parameter_reference.md#RTL_LOITER_RAD) | [Fixed-wing Only] The radius of the loiter circle (at [RTL_LAND_DELAY](#RTL_LAND_DELAY). | diff --git a/docs/en/flying/package_delivery_mission.md b/docs/en/flying/package_delivery_mission.md index 9ad16c403cc..27c3a8cfd2a 100644 --- a/docs/en/flying/package_delivery_mission.md +++ b/docs/en/flying/package_delivery_mission.md @@ -24,7 +24,7 @@ Whether or not you `Land` depends on whether the package can safely be deployed Since a gripper cannot lower packages safely, multicopter and VTOL vehicles will often land to deploy packages when using a gripper. After the deployment device [indicates completion](#package-release-feedback), the vehicle will proceed to the next waypoint. -Note that if landed, the next mission item after deployment should be another `Waypoint` or a `Takeoff` mission item ([it must not be a `RETURN`](#rtl-waypoint-for-package-delivery-with-landing).) +Note that if landed, the next mission item after deployment should be another `Waypoint` or a `Takeoff` mission item ([it must not be a `RETURN`](#return-waypoint-for-package-delivery-with-landing).) ## Creating a Package Delivery Mission @@ -74,12 +74,12 @@ Note how the altitude graph shows the `Land` item. ### Notes -#### RTL Waypoint for Package Delivery with Landing +#### Return Waypoint for Package Delivery with Landing Do not plan a mission with a delivery like this: `LAND` > `GRIPPER` > `RETURN TO LAUNCH`. -For safety reasons "Return To Launch" is disabled when vehicle is landed ([related issue](https://github.com/PX4/PX4-Autopilot/pull/20044)). -So if you land, release the cargo, then have an RTL waypoint, the vehicle will idle at the landing coordinate. +For safety reasons Return mode is disabled when the vehicle is landed ([related issue](https://github.com/PX4/PX4-Autopilot/pull/20044)). +So if you land, release the cargo, then have a `Return` (`MAV_CMD_NAV_RETURN_TO_LAUNCH`) mission item, the vehicle will idle at the landing coordinate. #### Manual Control of Gripper in Missions diff --git a/docs/en/ros2/px4_ros2_control_interface.md b/docs/en/ros2/px4_ros2_control_interface.md index a0a474fc41e..9636df86160 100644 --- a/docs/en/ros2/px4_ros2_control_interface.md +++ b/docs/en/ros2/px4_ros2_control_interface.md @@ -59,7 +59,7 @@ A mode defined using the interface library has the following properties: #### Mode Executor A mode executor is an optional component for scheduling modes. -For example, the mode executor for a custom payload delivery or survey mode might first trigger a take-off, then switch to the custom mode, and when that completes trigger an RTL. +For example, the mode executor for a custom payload delivery or survey mode might first trigger a take-off, then switch to the custom mode, and when that completes trigger a Return. Specifically, it has the following properties: @@ -733,8 +733,8 @@ This makes it independent of startup ordering in case of multiple external modes ### Replacing an Internal Mode -An external mode can replace an existing internal mode, such as [Return](../flight_modes/return.md) mode (RTL). -By doing so, whenever RTL gets selected (through the user or a failsafe situation), the external mode is used instead of the internal one. +An external mode can replace an existing internal mode, such as [Return](../flight_modes/return.md) mode. +By doing so, whenever it gets selected (through the user or a failsafe situation), the external mode is used instead of the internal one. The internal one is only used as a fallback when the external one becomes unresponsive or crashes. The replacement mode can be set in the settings of the `ModeBase` constructor: diff --git a/docs/en/ros2/px4_ros2_waypoint_missions.md b/docs/en/ros2/px4_ros2_waypoint_missions.md index 4484e1c136a..3abbbf9c915 100644 --- a/docs/en/ros2/px4_ros2_waypoint_missions.md +++ b/docs/en/ros2/px4_ros2_waypoint_missions.md @@ -11,7 +11,7 @@ They completely bypass the existing PX4 mission mode and waypoint logic, and can ::: ROS 2 waypoint missions are effectively special PX4 ROS 2 custom modes that are run based on the content of a [JSON mission definition](#mission-definition). -Mission definitions can contain actions that reference existing PX4 modes, such as Takeoff mode or RTL, and can also be extended with arbitrary custom actions written in ROS. +Mission definitions can contain actions that reference existing PX4 modes, such as Takeoff or Return mode, and can also be extended with arbitrary custom actions written in ROS. A [mode executor](px4_ros2_control_interface.md#mode-executor) is used to schedule the modes. Mission definitions can be hard coded in the custom mission mode (either in code or statically loaded from a JSON string), or directly generated within the application. @@ -69,13 +69,13 @@ They are identified by a name, and any number of these can be registered with th A custom action is then run whenever a mission item with matching name is executed, and any extra arguments from the JSON definition are passed as arguments (for example an altitude for a takeoff action). Actions can call other actions, run any mode (PX4 or external by its ID), run a trajectory, or run any other external action before deciding when to continue the mission. -There is a set of default actions, for example for RTL, Land, etc. +There is a set of default actions, for example for Return, Land, etc. These simply trigger the corresponding PX4 mode. They can be disabled or replaced with custom implementations. There are also some special actions (which can be replaced as well): - `OnFailure`: this is called in case of a failure, e.g. a mode switch failed, a non-existing action is called (by another action) or by an explicit call to `MissionExecutor::abort()`. - The default is to run RTL, with fallback to Land. + The default is to run Return, with fallback to Land. - `OnResume`: this is called when resuming a mission (either from the ground or in-air). It handles a number of cases: - when called with an argument `action="storeState"`: this can be used to store the current position when the mission is deactivated, so it can be resumed from the same position. diff --git a/docs/en/test_and_ci/bench_testing.md b/docs/en/test_and_ci/bench_testing.md index 2bda724d1d5..bee8c9ca812 100644 --- a/docs/en/test_and_ci/bench_testing.md +++ b/docs/en/test_and_ci/bench_testing.md @@ -79,7 +79,7 @@ A per-test watchdog turns a hung board into a named failure instead of a stuck t ## Simulated Flight on the FMU (SIH) -`sih/flight_mission.py` performs a complete hardware-in-the-loop flight without any host-side simulator: it switches the board to a [SIH airframe](../sim_sih/index.md) (`SYS_HITL=2`, physics computed on the autopilot), uploads a mission, arms through the NuttX shell, and asserts takeoff, waypoint progression, RTL, landing, and auto-disarm against per-phase timeouts. +`sih/flight_mission.py` performs a complete hardware-in-the-loop flight without any host-side simulator: it switches the board to a [SIH airframe](../sim_sih/index.md) (`SYS_HITL=2`, physics computed on the autopilot), uploads a mission, arms through the NuttX shell, and asserts takeoff, waypoint progression, Return, landing, and auto-disarm against per-phase timeouts. It runs as the last test of the default bench suite and also works standalone. Because it arms the flight controller, the suite asks for explicit confirmation on a terminal (type `arm`), and non-interactive runs skip it unless `--allow-arming` is passed. It first probes the running firmware for the SIH module and records a skip, not a failure, when the build does not include it. diff --git a/docs/en/test_and_ci/integration_testing_mavsdk.md b/docs/en/test_and_ci/integration_testing_mavsdk.md index 74b2d78f1b6..9e82f3d2626 100644 --- a/docs/en/test_and_ci/integration_testing_mavsdk.md +++ b/docs/en/test_and_ci/integration_testing_mavsdk.md @@ -90,7 +90,7 @@ Run a single test by specifying the `model` and test `case` as command line opti For example, to test a multicopter mission using the SIH simulator: ```sh -test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sih-sitl.json --speed-factor 10 --model quadx --case 'Fly square Multicopter Missions including RTL' +test/mavsdk_tests/mavsdk_test_runner.py test/mavsdk_tests/configs/sih-sitl.json --speed-factor 10 --model quadx --case 'Fly square Multicopter Missions including Return' ``` The easiest way to find out the current set of models and their associated test cases is to run all PX4 tests [as shown above](#run-all-px4-tests) (note, you can then cancel the build if you wish to test just one). @@ -108,8 +108,8 @@ About to run 39 test cases for 3 selected models (1 iteration): - 'Continue on baro stuck during mission (baro height mode)' - 'Continue on baro stuck during mission (GPS height mode)' - 'Takeoff and Land' - - 'Fly square Multicopter Missions including RTL' - - 'Fly square Multicopter Missions with manual RTL' + - 'Fly square Multicopter Missions including Return' + - 'Fly square Multicopter Missions with manual Return' - 'Fly straight Multicopter Mission' - 'Offboard takeoff and land' - 'Offboard position control' @@ -124,8 +124,8 @@ About to run 39 test cases for 3 selected models (1 iteration): - 'Continue on baro stuck during mission (baro height mode)' - 'Continue on baro stuck during mission (GPS height mode)' - 'Takeoff and Land' - - 'Fly square Multicopter Missions including RTL' - - 'Fly square Multicopter Missions with manual RTL' + - 'Fly square Multicopter Missions including Return' + - 'Fly square Multicopter Missions with manual Return' - 'Fly forward in position control' - 'Fly forward in altitude control' - tailsitter: @@ -137,8 +137,8 @@ About to run 39 test cases for 3 selected models (1 iteration): - 'Continue on baro stuck during mission (baro height mode)' - 'Continue on baro stuck during mission (GPS height mode)' - 'Takeoff and Land' - - 'Fly square Multicopter Missions including RTL' - - 'Fly square Multicopter Missions with manual RTL' + - 'Fly square Multicopter Missions including Return' + - 'Fly square Multicopter Missions with manual Return' - 'Fly forward in position control' - 'Fly forward in altitude control' ``` diff --git a/docs/en/test_cards/fw_02_full_autonomous.md b/docs/en/test_cards/fw_02_full_autonomous.md index c8405bd03d4..0226e830684 100644 --- a/docs/en/test_cards/fw_02_full_autonomous.md +++ b/docs/en/test_cards/fw_02_full_autonomous.md @@ -2,7 +2,7 @@ ## Objective -To test the auto modes such as Mission, Takeoff, Hold, and RTL for fixed wing vehicles. +To test the auto modes such as Mission, Takeoff, Hold, and Return for fixed wing vehicles. ## Preflight @@ -10,7 +10,7 @@ Plan a mission on the ground. Ensure the mission has: - Takeoff as first waypoint - Changes in altitude throughout the mission -- Last waypoint is an RTL +- Last waypoint is a Return item - Duration of 1 to 2 minutes ## Flight Tests @@ -29,7 +29,7 @@ Plan a mission on the ground. Ensure the mission has:     ❏ Verify changes in altitude throughout the mission -    ❏ Verify Mission Ends in RTL +    ❏ Verify Mission Ends in Return     ❏ Duration of 1 to 2 minutes @@ -43,7 +43,7 @@ Plan a mission on the ground. Ensure the mission has:     ❏ Orbit radius and direction should match parameters -❏ RTL +❏ Return     ❏ Arm and takeoff in any manual mode @@ -51,7 +51,7 @@ Plan a mission on the ground. Ensure the mission has:     ❏ Engage Return mode -    ❏ Vehicle should climb to RTL altitude if below it +    ❏ Vehicle should climb to return altitude if below it     ❏ Vehicle should return to home and hold or land @@ -60,5 +60,5 @@ Plan a mission on the ground. Ensure the mission has: - Mission should upload on first attempt - Vehicle should automatically takeoff upon engaging Auto - Waypoint tracking should be smooth with appropriate turn radius -- Vehicle should adjust height to RTL altitude before returning home +- Vehicle should adjust height to return altitude before returning home - Landing approach should be stable (if auto-land is configured) diff --git a/docs/en/test_cards/mc_02_full_autonomous.md b/docs/en/test_cards/mc_02_full_autonomous.md index e040ed0b7a4..5e324112962 100644 --- a/docs/en/test_cards/mc_02_full_autonomous.md +++ b/docs/en/test_cards/mc_02_full_autonomous.md @@ -2,7 +2,7 @@ ## Objective -To test the auto modes such as Mission, RTL, etc... +To test the auto modes such as Mission, Return, etc... ## Preflight @@ -10,7 +10,7 @@ Plan a mission on the ground. Ensure the mission has - Takeoff as first waypoint - Changes in Altitude throughout the mission -- Last waypoint is an RTL +- Last waypoint is a Return item - Duration of 5 to 6 minutes ## Flight Tests @@ -23,7 +23,7 @@ Plan a mission on the ground. Ensure the mission has     ❏ First waypoint set to Takeoff -    ❏ Enable Mission End RTL +    ❏ Enable Mission End Return     ❏ Duration of 5 to 6 minutes @@ -35,26 +35,26 @@ Plan a mission on the ground. Ensure the mission has     ❏ Engage Auto (Mission Mode) to trigger take-off -    ❏ Observe tracking, cornering and proper RTL performance +    ❏ Observe tracking, cornering and proper Return performance     ❏ Upon touching ground, copter should disarm automatically within 2 seconds (disarm time set by parameter: [COM_DISARM_LAND](../advanced_config/parameter_reference.md#COM_DISARM_LAND)) -❏ RTL +❏ Return     ❏ Arm and takeoff in position mode     ❏ Fly out ~10m from start point -    ❏ Engage RTL Mode +    ❏ Engage Return mode -    ❏ Observe tracking, cornering and proper RTL performance +    ❏ Observe tracking, cornering and proper Return performance ## Expected Results - Take-off should be smooth as throttle is raised - Mission should upload on first attempt - Vehicle should automatically take-off upon engaging Auto -- Vehicle should adjust height to RTL altitude before returning home +- Vehicle should adjust height to return altitude before returning home - Upon landing, copter should not bounce on the ground