From 2829c928c413313b2de97e761ea58b4ff9ad7d53 Mon Sep 17 00:00:00 2001 From: Roman Bapst Date: Wed, 22 Jul 2026 08:29:02 +0300 Subject: [PATCH] docs(navigator): [geofence] added some more warnings about limitations (#28001) * [docs][geofence] added some more warnings about limitations Signed-off-by: RomanBapst * docs(update): Minor restructure --------- Signed-off-by: RomanBapst Co-authored-by: Hamish Willee --- docs/en/flight_modes/return.md | 23 +++++++++++++++++------ docs/en/releases/main.md | 2 +- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/en/flight_modes/return.md b/docs/en/flight_modes/return.md index 57b01a1d3d1..ff99dae4183 100644 --- a/docs/en/flight_modes/return.md +++ b/docs/en/flight_modes/return.md @@ -160,6 +160,8 @@ In this return type the vehicle: ## Geofence Awareness {#geofence_awareness} + + For most of the return types (including the default home/rally point return type) the return path is chosen to avoid breaching any geofence. Planning is purely horizontal: the altitude profile is unaffected, and only the lateral path is adjusted to avoid the fence. If no geofence is set, the vehicle flies a direct path to the destination. @@ -173,14 +175,9 @@ If no such point exists, or if the autopilot fails to plan a feasible path (e.g. The estimated time for return is based on the current shortest horizontal path to the destination and may change if the geofence is updated. ::: -::: warning -Geofence awareness currently supports a maximum of 99 polygon vertices in total (circles count as 8 vertices each). -If this limit is exceeded, the autopilot falls back to a direct path as described above. -::: - ::: warning There is no absolute guarantee that the vehicle will not breach a geofence on the return path. -Things like path tracking error, wind and other disturbances may cause temporary violation of the geofence. +Things like path tracking error, wind and other disturbances may cause temporary violation of the geofence, while some of the [geofence limitations](#geofence-limitations) below may disable geofence-aware return altogether. 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)). ::: @@ -208,6 +205,20 @@ The figures below show an exclusion zone and an inclusion zone. ![Inclusion Zone](../../assets/flight_modes/rtl_geofence_inclusion.jpg) +### Geofence Limitations + +- Geofence awareness currently supports a maximum of 99 polygon vertices in total (circles count as 8 vertices each). + If this limit is exceeded, the autopilot falls back to a direct path as described above. +- The autopilot does not check at upload time whether every part of the allowed area is still reachable once the [safety margin](#shortest-path-calculation) has been applied. + A region can be "cut off" by the margin — for example where several exclusion zones overlap — without any error being reported when the geofence is uploaded. + The error is only reported when a return is triggered and no feasible path can be found, at which point the vehicle falls back to flying directly to the destination. + As a result you may believe that every region is reachable when in fact some are not. +- If the autopilot falls back to a direct path (for any of the reasons described above), a configured geofence breach action ([GF_ACTION](../advanced_config/parameter_reference.md#GF_ACTION)) still applies. + For example, if the direct path breaches a geofence, the configured action (such as flight termination) will be carried out. +- The safety margin in the [Shortest-path Calculation](#shortest-path-calculation) above may not be appropriate for all vehicles. + It is derived from [NAV_LOITER_RAD](../advanced_config/parameter_reference.md#NAV_LOITER_RAD) for fixed-wing and VTOL vehicles, and from twice [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) for multicopters. + It is not directly configurable. + ## Minimum Return Altitude For most [return types](#return_types) a vehicle will ascend to a _minimum safe altitude_ before returning (unless already above that altitude), in order to avoid any obstacles between it and the destination. diff --git a/docs/en/releases/main.md b/docs/en/releases/main.md index 18534f42c02..ab87957b3a4 100644 --- a/docs/en/releases/main.md +++ b/docs/en/releases/main.md @@ -48,7 +48,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide). ### Safety -- TBD +- [Geofence Aware Return mode](../flight_modes/return.md#geofence_awareness). ([PX4-Autopilot#27145: feat(navigator): Geofence Aware RTL](https://github.com/PX4/PX4-Autopilot/pull/27145), [PX4-Autopilot#28001: docs(navigator): [geofence] added some more warnings about limitations](https://github.com/PX4/PX4-Autopilot/pull/28001)). ### Estimation