From 574032be41c7b3420ac61b6370d2cdc753c9ce73 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Wed, 13 Nov 2024 11:39:20 +0100 Subject: [PATCH 01/16] Create Geozones.md Round 1 --- docs/Geozones.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/Geozones.md diff --git a/docs/Geozones.md b/docs/Geozones.md new file mode 100644 index 00000000000..33197fd258e --- /dev/null +++ b/docs/Geozones.md @@ -0,0 +1,35 @@ +# Geozones + +## Introduction +The Geozone feature allows pilots to define one or multiple areas on the map in Mission Control, to prevent accidental flying outside of allowed zones (Flight-Zones, FZ) or to avoid certain areas they are not allowed or not willing to fly in (No-Flight-Zone, NFZ). +This type of feature might be known to many pilots as a "Geofence" and despite providing the same core functionality, INAV Geozones are significantly more versatile and provide more safety and features. + +Geozones can not only inform the Pilot on the OSD, if the aircraft is approaching a geozone border, it also gives the distance and direction to the closest border and the remaining flight distance to the breach point. Additionally it provides autonomous avoidance features, if the Aircraft is in any kind of self-leveling flight mode. +The most important feature for safety, is the automatic path planning for RTH (Return To Home), that automatically avoids NFZ areas if possible. + +![image](https://github.com/user-attachments/assets/48e3e5cc-8517-4096-8497-399cf00ee541) + + +## Compatibility +- INAV Version: 8.0 or later +- INAV Configurator: 8.0 or Later +- [MWPTools:](https://github.com/stronnag/mwptools) Snapshot 2024-11-xx or later +- Only flight controller with more than 512k of Flash (STM32F405, STM32F765, STM32H743, etc.) +- Plane, Multirotor (Rover and Boat are untested at time of writing) + +## Setup Procedure +- In the INAV Configurator, switch to the Configuration Panel and enable "Geozone" in the features. +- Switch to the Mission Control Panel and you will see a new Icon to call up the Geozone Editor. If Zones are already set up, they will be loaded automatically, as soon as the you enter Mission Control. +- Click on the "+" Symbol to add a new zone and define its parameters to your desire. +- The following Options are available: + - Shape: Configures a Zone as a Circle or a Polygon + - Type: Inclusive (FZ, green) or Exclusive (NFZ, red) + - Min. Alt (cm): lower ceiling of the Zone + - Max. Alt (cm): upper ceiling of the Zone + - Action: Ection to execute if an aircraft approaches the border of that Zone + - Radius: Circular Zone only, Radius of the Circle +- Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) +- Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details + +## Functions and Behaviors +- From 5d91e4ed7dd646e00e8574179e82b3ee50def1bf Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Wed, 13 Nov 2024 12:03:27 +0100 Subject: [PATCH 02/16] Update Geozones.md round 2 --- docs/Geozones.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/Geozones.md b/docs/Geozones.md index 33197fd258e..6f316f4adf4 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -32,4 +32,14 @@ The most important feature for safety, is the automatic path planning for RTH (R - Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details ## Functions and Behaviors +- Zone Type: Inclusive + - If craft is armed inside the Inclusive FZ, everything outside that zone is considered a NFZ. + - Inclusive FZ can be combined if they overlap and will be handled as one zone. + - Overlapping multiple FZ allows different upper and lower altitude limits for each zone, as long as they still overlap in 3D Space (Both overlapping zones have to have a overlapping altitude range as well). + - Arming the aircraft outside of an Inclusive Zone is prohibited within a 2km distance to the next vertex (Distance to a border between two vertex is not checked). Arming override can be used. Arming at a distance bigger than 2km is possible. + - Arming a craft outside of an Inclusive FZ will disable all Inclusive zones. +- Zone Type: Exclusive + - Arming inside an Exclusive NFZ is prohibited. Arming override can be used but not recommended. If armed inside a NFZ the Pilot keeps control until the NFZ is left, then any configured Action will be executed on re-enter. + - Exclusive Zones can be combined and overlapped as needed + - Exclusive NFZ with an upper or lower limit other than 0 can be overflown and underflown. The Automatic avoidance will only fly above NFZ if possible and never below. - From 88c193c2690b3eb718d8f96c2d50e32818cc4f50 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Wed, 13 Nov 2024 12:29:53 +0100 Subject: [PATCH 03/16] Update Geozones.md update 3 --- docs/Geozones.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/Geozones.md b/docs/Geozones.md index 6f316f4adf4..6225a444874 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -29,8 +29,12 @@ The most important feature for safety, is the automatic path planning for RTH (R - Action: Ection to execute if an aircraft approaches the border of that Zone - Radius: Circular Zone only, Radius of the Circle - Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) +- To add additional vertices, click on the border-line of the zone you are editing. This will add a new vertex on that line to move around. - Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details +## Additional Settings +- + ## Functions and Behaviors - Zone Type: Inclusive - If craft is armed inside the Inclusive FZ, everything outside that zone is considered a NFZ. @@ -42,4 +46,17 @@ The most important feature for safety, is the automatic path planning for RTH (R - Arming inside an Exclusive NFZ is prohibited. Arming override can be used but not recommended. If armed inside a NFZ the Pilot keeps control until the NFZ is left, then any configured Action will be executed on re-enter. - Exclusive Zones can be combined and overlapped as needed - Exclusive NFZ with an upper or lower limit other than 0 can be overflown and underflown. The Automatic avoidance will only fly above NFZ if possible and never below. +- Actions: + - Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary “billiard ball effect” + - Hold: Position in front of the boundary is held. Airplances will adjust their loiter center according to the loider radius, to stay away from the border while circling. + - RTH: Triggers return to home. The Failsafe RTH Procedure is executed, so RTH Trackback is also used if enabled for Failsafe situations. + - None: No action (only info in OSD) +- RTH: + - If RTH is enabled by Failsafe, User Command or Zone Action, INAV will calculate a path to the Home Location that automatically avoids NFZ and tries to stay inside the current FZ. + - If no Path can be calculated (Not able to climb over a blocking NFZ, No Intersection between FZ, too tight gaps between blocking NFZ) a configurable alternative action will be executed + - Direct RTH: Ignores Flight zones and comes back in a direct path + - Emergency Land: Executes a GPS enabled Emergency Landing (Circle down with horizontal position hold active on Planes) + - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed + +## Limitations - From 058eb1cd9a926afb3222e8347ac91b19d5aaa934 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Wed, 13 Nov 2024 12:43:55 +0100 Subject: [PATCH 04/16] Update Geozones.md update 4 --- docs/Geozones.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index 6225a444874..356f6525971 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -30,7 +30,7 @@ The most important feature for safety, is the automatic path planning for RTH (R - Radius: Circular Zone only, Radius of the Circle - Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) - To add additional vertices, click on the border-line of the zone you are editing. This will add a new vertex on that line to move around. -- Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details +- Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details) ## Additional Settings - @@ -59,4 +59,11 @@ The most important feature for safety, is the automatic path planning for RTH (R - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed ## Limitations -- +- The maximum amount of dedicated zones of any type is 63. +- The maximum amount of vertices of all zones combined is 127. Every circular zone uses 2 vertices while every polygon has to consist of at least 3 vertices. +- INAV can only execute one border-breach action at a time. This is especially important to consider for Airplanes that can not hover. + - Complicated Zone setups with overlaps and tight areas can cause a Loiter or "bounce" into another NFZ that was not considered before. + - This can lead to a "Return to FZ" action that tries to find the shortest path into a legal area. +- All Geozone Actions are disabled when in Waypoint Mode. The Pilot is responsible to plan his mission accordingly, to not create a path that crosses NFZ areas. If a mission leads to such area and the pilot disables WP mode, a "Return to FZ" action will be executed. +- All Geozone Actions are disabled in ACRO and MANUAL Mode. INAV will not take over control in these modes and only OSD Warnings are shown. +- Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clock wise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before upload. From 9b02a29f85be87738a7001c4dd14d2c35c5cad0b Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 19:32:29 +0100 Subject: [PATCH 05/16] Update Geozones.md --- docs/Geozones.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index 356f6525971..b2cf1eef150 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -19,7 +19,8 @@ The most important feature for safety, is the automatic path planning for RTH (R ## Setup Procedure - In the INAV Configurator, switch to the Configuration Panel and enable "Geozone" in the features. -- Switch to the Mission Control Panel and you will see a new Icon to call up the Geozone Editor. If Zones are already set up, they will be loaded automatically, as soon as the you enter Mission Control. +- Switch to the Mission Control Panel and you will see a new Icon to call up the Geozone Editor. If Zones are already set up, they will be loaded automatically, as soon as the you enter Mission Control. + ![image](https://github.com/user-attachments/assets/23cd2149-b6a2-4945-b349-ee99863e74f0) - Click on the "+" Symbol to add a new zone and define its parameters to your desire. - The following Options are available: - Shape: Configures a Zone as a Circle or a Polygon @@ -30,10 +31,21 @@ The most important feature for safety, is the automatic path planning for RTH (R - Radius: Circular Zone only, Radius of the Circle - Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) - To add additional vertices, click on the border-line of the zone you are editing. This will add a new vertex on that line to move around. + ![image](https://github.com/user-attachments/assets/eacb6d3c-62d3-4bab-8874-1543c0a6b06d) - Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details) +- After finishing the zone setup, click the "Store in EEPROM" Button to save the zones on the Flight Controller. It is important that the FC reboots after storing, as the Zones can only be used after a fresh boot process. + ![image](https://github.com/user-attachments/assets/4b278dd0-aa65-45f6-b914-22bdd753feaf) ## Additional Settings -- +- In the Advanced Tuning Panel you will find additional global settings for Geozones + ![image](https://github.com/user-attachments/assets/db567521-e256-4fb6-8ca6-6e6b8b57d7a9) + - Detection Distance: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent + - Avoid Altitude Range: When the Aircraft approaches a NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is. + - Safe Altitude Distance: Vertical safety margin to avoid a ceiling or floor altitude breach at high vertical speed. If your FZ Ceiling is at 100m and this value set to 10m, the aircraft will not allow you to fly above 90m and descents if the Aircraft overshoots. + - Safehome as Inclusive: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude + - Safehome Zone Action: Defines the action on zone breach if Safehome is enabled as inclusive. This is helpful for flying fields with distance or altitude restrictions for LOS Pilots. + - Multirotor Stop Distance: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane) + - No Way Home Action: If RTH can not find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ. ## Functions and Behaviors - Zone Type: Inclusive @@ -62,8 +74,15 @@ The most important feature for safety, is the automatic path planning for RTH (R - The maximum amount of dedicated zones of any type is 63. - The maximum amount of vertices of all zones combined is 127. Every circular zone uses 2 vertices while every polygon has to consist of at least 3 vertices. - INAV can only execute one border-breach action at a time. This is especially important to consider for Airplanes that can not hover. - - Complicated Zone setups with overlaps and tight areas can cause a Loiter or "bounce" into another NFZ that was not considered before. - - This can lead to a "Return to FZ" action that tries to find the shortest path into a legal area. + - Complicated Zone setups with overlaps and tight areas can cause a loiter or "bounce" into another NFZ that was not considered before. + - This can lead to a "Return to FZ" action that tries to find the shortest path into an allowed area. - All Geozone Actions are disabled when in Waypoint Mode. The Pilot is responsible to plan his mission accordingly, to not create a path that crosses NFZ areas. If a mission leads to such area and the pilot disables WP mode, a "Return to FZ" action will be executed. - All Geozone Actions are disabled in ACRO and MANUAL Mode. INAV will not take over control in these modes and only OSD Warnings are shown. -- Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clock wise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before upload. +- Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clock wise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before upload. + - Examples of Zones that are not allowed: + ![image](https://github.com/user-attachments/assets/63d287fe-e2eb-44d4-a8ba-2b862d69eb71) +- To properly combine multiple Inclusion FZ into one area, the Zones need to overlap at 2 borders and the points where the borders touch, have to be at least 2.5x Loiter-Radius apart for Airplanes at at least 2.5x Multirotor Stop Distance apart for Multirotors. + - Example: + ![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63) +- If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 3x Avoid Altitude Range +- It is not recommended, to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can leat to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. From 57e3f1c1601ea68dbf1566791c04b35a670f05d9 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 19:49:18 +0100 Subject: [PATCH 06/16] Update Geozones.md --- docs/Geozones.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index b2cf1eef150..e95d97b9bbc 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -25,8 +25,8 @@ The most important feature for safety, is the automatic path planning for RTH (R - The following Options are available: - Shape: Configures a Zone as a Circle or a Polygon - Type: Inclusive (FZ, green) or Exclusive (NFZ, red) - - Min. Alt (cm): lower ceiling of the Zone - - Max. Alt (cm): upper ceiling of the Zone + - Min. Alt (cm): lower ceiling of the Zone (0 represents the ground relative from the launch location or AMSL. No action will be taken for a minimum altitude of 0, so the aircraft can "dive out" of an Inclusive FZ on a hill. To have a Minimum Altitude action, set a negative altitude of -1 or lower) + - Max. Alt (cm): upper ceiling of the Zone (A value if 0 means no upper altitude limit) - Action: Ection to execute if an aircraft approaches the border of that Zone - Radius: Circular Zone only, Radius of the Circle - Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) @@ -59,7 +59,7 @@ The most important feature for safety, is the automatic path planning for RTH (R - Exclusive Zones can be combined and overlapped as needed - Exclusive NFZ with an upper or lower limit other than 0 can be overflown and underflown. The Automatic avoidance will only fly above NFZ if possible and never below. - Actions: - - Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary “billiard ball effect” + - Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary at the same angle it approached it, similar to a pool ball bouncing off the table border. Multirotor will switch into "Position Hold". - Hold: Position in front of the boundary is held. Airplances will adjust their loiter center according to the loider radius, to stay away from the border while circling. - RTH: Triggers return to home. The Failsafe RTH Procedure is executed, so RTH Trackback is also used if enabled for Failsafe situations. - None: No action (only info in OSD) @@ -69,6 +69,11 @@ The most important feature for safety, is the automatic path planning for RTH (R - Direct RTH: Ignores Flight zones and comes back in a direct path - Emergency Land: Executes a GPS enabled Emergency Landing (Circle down with horizontal position hold active on Planes) - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed +- Return to Zone: + - If the Aircraft breaches into a NFZ or out of a FZ (by avoiding in tight angled Zones or flown in Acro mode and then the mode switches to any Self-Level mode), RTZ is initiated and the aircraft flies back into the last permitted zone on the shortest possible course. + +## OSD Elements +- ## Limitations - The maximum amount of dedicated zones of any type is 63. From 8820a3ffea35f9ace1c56467cebd66d7e02ce6e3 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 19:52:21 +0100 Subject: [PATCH 07/16] Update Geozones.md --- docs/Geozones.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index e95d97b9bbc..aaab3786bae 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -69,6 +69,7 @@ The most important feature for safety, is the automatic path planning for RTH (R - Direct RTH: Ignores Flight zones and comes back in a direct path - Emergency Land: Executes a GPS enabled Emergency Landing (Circle down with horizontal position hold active on Planes) - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed + - To abort the Smart-RTH feature and come back on a direct way, disable and Re-Enable RTH within 1 Second. This temporarily ignores all FZ and NFZ borders. - Return to Zone: - If the Aircraft breaches into a NFZ or out of a FZ (by avoiding in tight angled Zones or flown in Acro mode and then the mode switches to any Self-Level mode), RTZ is initiated and the aircraft flies back into the last permitted zone on the shortest possible course. @@ -89,5 +90,5 @@ The most important feature for safety, is the automatic path planning for RTH (R - To properly combine multiple Inclusion FZ into one area, the Zones need to overlap at 2 borders and the points where the borders touch, have to be at least 2.5x Loiter-Radius apart for Airplanes at at least 2.5x Multirotor Stop Distance apart for Multirotors. - Example: ![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63) -- If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 3x Avoid Altitude Range +- If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 50m. - It is not recommended, to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can leat to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. From 10502a486ed38f0b3998d6e715e29ccb539d6455 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 20:09:54 +0100 Subject: [PATCH 08/16] Update Geozones.md --- docs/Geozones.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index aaab3786bae..703bf3175fa 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -39,12 +39,12 @@ The most important feature for safety, is the automatic path planning for RTH (R ## Additional Settings - In the Advanced Tuning Panel you will find additional global settings for Geozones ![image](https://github.com/user-attachments/assets/db567521-e256-4fb6-8ca6-6e6b8b57d7a9) - - Detection Distance: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent + - Detection Distance: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent. - Avoid Altitude Range: When the Aircraft approaches a NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is. - Safe Altitude Distance: Vertical safety margin to avoid a ceiling or floor altitude breach at high vertical speed. If your FZ Ceiling is at 100m and this value set to 10m, the aircraft will not allow you to fly above 90m and descents if the Aircraft overshoots. - - Safehome as Inclusive: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude + - Safehome as Inclusive: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude. - Safehome Zone Action: Defines the action on zone breach if Safehome is enabled as inclusive. This is helpful for flying fields with distance or altitude restrictions for LOS Pilots. - - Multirotor Stop Distance: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane) + - Multirotor Stop Distance: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane). - No Way Home Action: If RTH can not find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ. ## Functions and Behaviors @@ -56,26 +56,34 @@ The most important feature for safety, is the automatic path planning for RTH (R - Arming a craft outside of an Inclusive FZ will disable all Inclusive zones. - Zone Type: Exclusive - Arming inside an Exclusive NFZ is prohibited. Arming override can be used but not recommended. If armed inside a NFZ the Pilot keeps control until the NFZ is left, then any configured Action will be executed on re-enter. - - Exclusive Zones can be combined and overlapped as needed + - Exclusive Zones can be combined and overlapped as needed. - Exclusive NFZ with an upper or lower limit other than 0 can be overflown and underflown. The Automatic avoidance will only fly above NFZ if possible and never below. - Actions: - Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary at the same angle it approached it, similar to a pool ball bouncing off the table border. Multirotor will switch into "Position Hold". - Hold: Position in front of the boundary is held. Airplances will adjust their loiter center according to the loider radius, to stay away from the border while circling. - RTH: Triggers return to home. The Failsafe RTH Procedure is executed, so RTH Trackback is also used if enabled for Failsafe situations. - - None: No action (only info in OSD) + - None: No action (only info in OSD). - RTH: - If RTH is enabled by Failsafe, User Command or Zone Action, INAV will calculate a path to the Home Location that automatically avoids NFZ and tries to stay inside the current FZ. - - If no Path can be calculated (Not able to climb over a blocking NFZ, No Intersection between FZ, too tight gaps between blocking NFZ) a configurable alternative action will be executed - - Direct RTH: Ignores Flight zones and comes back in a direct path - - Emergency Land: Executes a GPS enabled Emergency Landing (Circle down with horizontal position hold active on Planes) - - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed + - If no Path can be calculated (Not able to climb over a blocking NFZ, No Intersection between FZ, too tight gaps between blocking NFZ) a configurable alternative action will be executed. + - Direct RTH: Ignores Flight zones and comes back in a direct path. + - Emergency Land: Executes a GPS enabled Emergency Landing (Circle down with horizontal position hold active on Planes). + - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed. - To abort the Smart-RTH feature and come back on a direct way, disable and Re-Enable RTH within 1 Second. This temporarily ignores all FZ and NFZ borders. - Return to Zone: - If the Aircraft breaches into a NFZ or out of a FZ (by avoiding in tight angled Zones or flown in Acro mode and then the mode switches to any Self-Level mode), RTZ is initiated and the aircraft flies back into the last permitted zone on the shortest possible course. ## OSD Elements -- +- Three dedicated OSD Elements have been added: + - Fence-Distance Horizontal shows the distance to the nearest Fence Border and the heading to that border. + - Fence-Distance Vertical shows the distance to the nearest ceiling or floor of a zone. + - Fence-Direction Vertical is an optional element to show if the nearest vertical border is above or below the aircraft. + ![image](https://github.com/user-attachments/assets/87dd3c5a-1046-4bd4-93af-5f8c9078b868) +- The Flight-Mode will show AUTO if the Aircraft executes any kind of Fence-Action. +- The System-Message shows the distance to a potential fence breach point, based on the current aircraft Attitude and Heading. +- Additionally the System Message shows the current Fence Action that is Executed. + ## Limitations - The maximum amount of dedicated zones of any type is 63. - The maximum amount of vertices of all zones combined is 127. Every circular zone uses 2 vertices while every polygon has to consist of at least 3 vertices. From 2e587aa33bf23e892ff5e2d89cfee76c803e5a63 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 20:27:33 +0100 Subject: [PATCH 09/16] Update Geozones.md --- docs/Geozones.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index 703bf3175fa..efca30580da 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -27,7 +27,7 @@ The most important feature for safety, is the automatic path planning for RTH (R - Type: Inclusive (FZ, green) or Exclusive (NFZ, red) - Min. Alt (cm): lower ceiling of the Zone (0 represents the ground relative from the launch location or AMSL. No action will be taken for a minimum altitude of 0, so the aircraft can "dive out" of an Inclusive FZ on a hill. To have a Minimum Altitude action, set a negative altitude of -1 or lower) - Max. Alt (cm): upper ceiling of the Zone (A value if 0 means no upper altitude limit) - - Action: Ection to execute if an aircraft approaches the border of that Zone + - Action: Action to execute if an aircraft approaches the border of that Zone - Radius: Circular Zone only, Radius of the Circle - Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) - To add additional vertices, click on the border-line of the zone you are editing. This will add a new vertex on that line to move around. @@ -94,7 +94,7 @@ The most important feature for safety, is the automatic path planning for RTH (R - All Geozone Actions are disabled in ACRO and MANUAL Mode. INAV will not take over control in these modes and only OSD Warnings are shown. - Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clock wise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before upload. - Examples of Zones that are not allowed: - ![image](https://github.com/user-attachments/assets/63d287fe-e2eb-44d4-a8ba-2b862d69eb71) + ![image](https://github.com/user-attachments/assets/50f1a441-39da-4f1c-9128-7375bc593fa5) - To properly combine multiple Inclusion FZ into one area, the Zones need to overlap at 2 borders and the points where the borders touch, have to be at least 2.5x Loiter-Radius apart for Airplanes at at least 2.5x Multirotor Stop Distance apart for Multirotors. - Example: ![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63) From 5891a39064ccee40bf24b2833e1cba94eab0e8cd Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 21:47:14 +0100 Subject: [PATCH 10/16] Update Geozones.md Added CLI stuff --- docs/Geozones.md | 53 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 12 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index efca30580da..f95fa31b788 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -36,16 +36,16 @@ The most important feature for safety, is the automatic path planning for RTH (R - After finishing the zone setup, click the "Store in EEPROM" Button to save the zones on the Flight Controller. It is important that the FC reboots after storing, as the Zones can only be used after a fresh boot process. ![image](https://github.com/user-attachments/assets/4b278dd0-aa65-45f6-b914-22bdd753feaf) -## Additional Settings +## Global Settings - In the Advanced Tuning Panel you will find additional global settings for Geozones ![image](https://github.com/user-attachments/assets/db567521-e256-4fb6-8ca6-6e6b8b57d7a9) - - Detection Distance: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent. - - Avoid Altitude Range: When the Aircraft approaches a NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is. - - Safe Altitude Distance: Vertical safety margin to avoid a ceiling or floor altitude breach at high vertical speed. If your FZ Ceiling is at 100m and this value set to 10m, the aircraft will not allow you to fly above 90m and descents if the Aircraft overshoots. - - Safehome as Inclusive: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude. - - Safehome Zone Action: Defines the action on zone breach if Safehome is enabled as inclusive. This is helpful for flying fields with distance or altitude restrictions for LOS Pilots. - - Multirotor Stop Distance: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane). - - No Way Home Action: If RTH can not find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ. + - Detection Distance `geozone_detection_distance`: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent. + - Avoid Altitude Range `geozone_avoid_altitude_range`: When the Aircraft approaches a NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is. + - Safe Altitude Distance `geozone_safe_altitude_distance`: Vertical safety margin to avoid a ceiling or floor altitude breach at high vertical speed. If your FZ Ceiling is at 100m and this value set to 10m, the aircraft will not allow you to fly above 90m and descents if the Aircraft overshoots. + - Safehome as Inclusive `geozone_safehome_as_inclusive`: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude. + - Safehome Zone Action `geozone_safehome_zone_action`: Defines the action on zone breach if Safehome is enabled as inclusive. This is helpful for flying fields with distance or altitude restrictions for LOS Pilots. + - Multirotor Stop Distance `geozone_mr_stop_distance:`: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane). + - No Way Home Action `geozone_no_way_home_action`: If RTH can not find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ. ## Functions and Behaviors - Zone Type: Inclusive @@ -75,9 +75,9 @@ The most important feature for safety, is the automatic path planning for RTH (R ## OSD Elements - Three dedicated OSD Elements have been added: - - Fence-Distance Horizontal shows the distance to the nearest Fence Border and the heading to that border. - - Fence-Distance Vertical shows the distance to the nearest ceiling or floor of a zone. - - Fence-Direction Vertical is an optional element to show if the nearest vertical border is above or below the aircraft. + - Fence-Distance Horizontal shows the distance to the nearest Fence Border and the heading to that border. (ID 145) + - Fence-Distance Vertical shows the distance to the nearest ceiling or floor of a zone. (ID 146) + - Fence-Direction Vertical is an optional element to show if the nearest vertical border is above or below the aircraft. (ID 144) ![image](https://github.com/user-attachments/assets/87dd3c5a-1046-4bd4-93af-5f8c9078b868) - The Flight-Mode will show AUTO if the Aircraft executes any kind of Fence-Action. - The System-Message shows the distance to a potential fence breach point, based on the current aircraft Attitude and Heading. @@ -99,4 +99,33 @@ The most important feature for safety, is the automatic path planning for RTH (R - Example: ![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63) - If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 50m. -- It is not recommended, to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can leat to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. +- It is not recommended, to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can leat to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. + +## CLI +The Geozone Information are stored in two separate data arrays. The first array holds the main Geozone Information and settings. The second array holds the Geozone vertices. +The following commands are available for users: + +- `geozone` without argument lists the current settings +- `geozone vertex` - lists all vertices. +- `geozone vertex reset` - deletes all vertices. +- `geozone` vertex reset ` - Deletes all vertices of the zone. +- `geozone` vertex reset ` - Deletes the vertex with the corresponding id from a zone. + +The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY CLI_! + +`geozone ` + +- id: 0 - 63 +- shape: 0 = Circular, 1 = Polygonal +- type: 0 = Exclusive, 1 = Inclusive +- minimum altitude: In centimetres, 0 = ground +- maximum altitude: In centimetres, 0 = infinity +- fence action: 0 = None, 1 = Avoid, 2 = Position hold, 3 = Return to home + +`geozone vertex ` + +- zone id: (0-63) The zone id to which this vertex belongs +- vertex idx: Index of the vertex (0-126) +- latitude/ logitude: Longitude and latitude of the vertex. Values in decimal degrees * 1e7. Example:the value 47.562004o becomes 475620040 + + From 07842239578787f6da5d2cbb3ed6b518ea52f8cc Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 21:58:27 +0100 Subject: [PATCH 11/16] hopefully Final Grammar touches --- docs/Geozones.md | 50 ++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index f95fa31b788..b6648182790 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -4,8 +4,8 @@ The Geozone feature allows pilots to define one or multiple areas on the map in Mission Control, to prevent accidental flying outside of allowed zones (Flight-Zones, FZ) or to avoid certain areas they are not allowed or not willing to fly in (No-Flight-Zone, NFZ). This type of feature might be known to many pilots as a "Geofence" and despite providing the same core functionality, INAV Geozones are significantly more versatile and provide more safety and features. -Geozones can not only inform the Pilot on the OSD, if the aircraft is approaching a geozone border, it also gives the distance and direction to the closest border and the remaining flight distance to the breach point. Additionally it provides autonomous avoidance features, if the Aircraft is in any kind of self-leveling flight mode. -The most important feature for safety, is the automatic path planning for RTH (Return To Home), that automatically avoids NFZ areas if possible. +Geozones can not only inform the Pilot on the OSD, if the aircraft is approaching a geozone border, it also gives the distance and direction to the closest border and the remaining flight distance to the breach point. Additionally, it provides autonomous avoidance features, if the Aircraft is in any kind of self-leveling flight mode. +The most important feature for safety is the automatic path planning for RTH (Start Return To Home), that automatically avoids NFZ areas if possible. ![image](https://github.com/user-attachments/assets/48e3e5cc-8517-4096-8497-399cf00ee541) @@ -19,49 +19,49 @@ The most important feature for safety, is the automatic path planning for RTH (R ## Setup Procedure - In the INAV Configurator, switch to the Configuration Panel and enable "Geozone" in the features. -- Switch to the Mission Control Panel and you will see a new Icon to call up the Geozone Editor. If Zones are already set up, they will be loaded automatically, as soon as the you enter Mission Control. +- Switch to the Mission Control Panel and you will see a new Icon to call up the Geozone Editor. If Zones are already set up, they will be loaded automatically, as soon as you enter Mission Control. ![image](https://github.com/user-attachments/assets/23cd2149-b6a2-4945-b349-ee99863e74f0) - Click on the "+" Symbol to add a new zone and define its parameters to your desire. - The following Options are available: - Shape: Configures a Zone as a Circle or a Polygon - Type: Inclusive (FZ, green) or Exclusive (NFZ, red) - - Min. Alt (cm): lower ceiling of the Zone (0 represents the ground relative from the launch location or AMSL. No action will be taken for a minimum altitude of 0, so the aircraft can "dive out" of an Inclusive FZ on a hill. To have a Minimum Altitude action, set a negative altitude of -1 or lower) + - Min. Alt (cm): lower ceiling of the Zone (0 represents the ground relative from the launch location or AMSL. No action will be taken at a minimum altitude of 0, so the aircraft can "dive out" of an Inclusive FZ on a hill. To have a Minimum Altitude action, set a negative altitude of -1 or lower) - Max. Alt (cm): upper ceiling of the Zone (A value if 0 means no upper altitude limit) - Action: Action to execute if an aircraft approaches the border of that Zone - Radius: Circular Zone only, Radius of the Circle -- Move the Zone-Markers to the desired locations, to create a bordered area with the needed shape and size (Or change the radius in case of a Circular Zone) -- To add additional vertices, click on the border-line of the zone you are editing. This will add a new vertex on that line to move around. +- Move the Zone-Markers to the desired locations, to create a bordered area with the shape and size needed (Or change the radius in case of a Circular Zone) +- To add additional vertices, click on the borderline of the zone you are editing. This will add a new vertex to that line to move around. ![image](https://github.com/user-attachments/assets/eacb6d3c-62d3-4bab-8874-1543c0a6b06d) - Add additional Zones as you like, Zones can be separated but also overlapping (See [Limitations]( ) for details) - After finishing the zone setup, click the "Store in EEPROM" Button to save the zones on the Flight Controller. It is important that the FC reboots after storing, as the Zones can only be used after a fresh boot process. ![image](https://github.com/user-attachments/assets/4b278dd0-aa65-45f6-b914-22bdd753feaf) ## Global Settings -- In the Advanced Tuning Panel you will find additional global settings for Geozones +- In the Advanced Tuning Panel, you will find additional global settings for Geozones ![image](https://github.com/user-attachments/assets/db567521-e256-4fb6-8ca6-6e6b8b57d7a9) - Detection Distance `geozone_detection_distance`: Defines at what distance a Geozone will be shown as a System Message if a breach is imminent. - - Avoid Altitude Range `geozone_avoid_altitude_range`: When the Aircraft approaches a NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is. + - Avoid Altitude Range `geozone_avoid_altitude_range`: When the Aircraft approaches an NFZ that has a upper limit (can be overflown at higher altitude), INAV will climb above the Zone automatically if the altitude difference between Zone ceiling and current Aircraft altitude is less, than this value. For fixed wing, you need to consider how steep the possible climb angle is. - Safe Altitude Distance `geozone_safe_altitude_distance`: Vertical safety margin to avoid a ceiling or floor altitude breach at high vertical speed. If your FZ Ceiling is at 100m and this value set to 10m, the aircraft will not allow you to fly above 90m and descents if the Aircraft overshoots. - Safehome as Inclusive `geozone_safehome_as_inclusive`: Defines every Safehome location as a circular Inclusive zone with the radius of `safehome_max_distance` to allow a FZ at ground altitude (For Landings) if the general FZ around it might have a minimum altitude. - Safehome Zone Action `geozone_safehome_zone_action`: Defines the action on zone breach if Safehome is enabled as inclusive. This is helpful for flying fields with distance or altitude restrictions for LOS Pilots. - Multirotor Stop Distance `geozone_mr_stop_distance:`: Distance from the Border a Multirotor will stop, if the Fence Action is Avoid or Loiter (For fixed wings, this will be calculated from the Loiter-Radius of the Plane). - - No Way Home Action `geozone_no_way_home_action`: If RTH can not find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ. + - No Way Home Action `geozone_no_way_home_action`: If RTH cannot find a possible route in FS or RTH modes, the Aircraft will either emergency land or fly straight back home and ignores NFZ. ## Functions and Behaviors - Zone Type: Inclusive - - If craft is armed inside the Inclusive FZ, everything outside that zone is considered a NFZ. + - If craft is armed inside the Inclusive FZ, everything outside that zone is considered an NFZ. - Inclusive FZ can be combined if they overlap and will be handled as one zone. - Overlapping multiple FZ allows different upper and lower altitude limits for each zone, as long as they still overlap in 3D Space (Both overlapping zones have to have a overlapping altitude range as well). - Arming the aircraft outside of an Inclusive Zone is prohibited within a 2km distance to the next vertex (Distance to a border between two vertex is not checked). Arming override can be used. Arming at a distance bigger than 2km is possible. - Arming a craft outside of an Inclusive FZ will disable all Inclusive zones. - Zone Type: Exclusive - - Arming inside an Exclusive NFZ is prohibited. Arming override can be used but not recommended. If armed inside a NFZ the Pilot keeps control until the NFZ is left, then any configured Action will be executed on re-enter. + - Arming inside an Exclusive NFZ is prohibited. Arming override can be used but not recommended. If armed inside an NFZ the Pilot keeps control until the NFZ is left, then any configured Action will be executed on re-enter. - Exclusive Zones can be combined and overlapped as needed. - Exclusive NFZ with an upper or lower limit other than 0 can be overflown and underflown. The Automatic avoidance will only fly above NFZ if possible and never below. - Actions: - - Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary at the same angle it approached it, similar to a pool ball bouncing off the table border. Multirotor will switch into "Position Hold". + - Avoid: Also called “Bounce” (only airplanes): The aircraft flies away from the boundary at the same angle it approached it, like a pool ball bouncing off the table border. Multirotor will switch into "Position Hold". - Hold: Position in front of the boundary is held. Airplances will adjust their loiter center according to the loider radius, to stay away from the border while circling. - - RTH: Triggers return to home. The Failsafe RTH Procedure is executed, so RTH Trackback is also used if enabled for Failsafe situations. + - RTH: Triggers Return To Home. The Failsafe RTH Procedure is executed, so RTH Trackback is also used if enabled for Failsafe situations. - None: No action (only info in OSD). - RTH: - If RTH is enabled by Failsafe, User Command or Zone Action, INAV will calculate a path to the Home Location that automatically avoids NFZ and tries to stay inside the current FZ. @@ -71,7 +71,7 @@ The most important feature for safety, is the automatic path planning for RTH (R - When direct "Line of sight" with the Home location is reached (No zones blocking path), regular RTH settings are executed. - To abort the Smart-RTH feature and come back on a direct way, disable and Re-Enable RTH within 1 Second. This temporarily ignores all FZ and NFZ borders. - Return to Zone: - - If the Aircraft breaches into a NFZ or out of a FZ (by avoiding in tight angled Zones or flown in Acro mode and then the mode switches to any Self-Level mode), RTZ is initiated and the aircraft flies back into the last permitted zone on the shortest possible course. + - If the Aircraft breaches into an NFZ or out of a FZ (by avoiding tight angled Zones or flown in Acro mode and then the mode switches to any Self-Level mode), RTZ is initiated and the aircraft flies back into the last permitted zone on the shortest possible course. ## OSD Elements - Three dedicated OSD Elements have been added: @@ -81,25 +81,25 @@ The most important feature for safety, is the automatic path planning for RTH (R ![image](https://github.com/user-attachments/assets/87dd3c5a-1046-4bd4-93af-5f8c9078b868) - The Flight-Mode will show AUTO if the Aircraft executes any kind of Fence-Action. - The System-Message shows the distance to a potential fence breach point, based on the current aircraft Attitude and Heading. -- Additionally the System Message shows the current Fence Action that is Executed. +- Additionally, the System Message shows the current Fence Action that is Executed. ## Limitations -- The maximum amount of dedicated zones of any type is 63. -- The maximum amount of vertices of all zones combined is 127. Every circular zone uses 2 vertices while every polygon has to consist of at least 3 vertices. -- INAV can only execute one border-breach action at a time. This is especially important to consider for Airplanes that can not hover. +- The maximum number of dedicated zones of any type is 63. +- The maximum number of vertices of all zones combined is 127. Every circular zone uses 2 vertices while every polygon has to consist of at least 3 vertices. +- INAV can only execute one border-breach action at a time. This is especially important to consider for Airplanes that cannot hover. - Complicated Zone setups with overlaps and tight areas can cause a loiter or "bounce" into another NFZ that was not considered before. - This can lead to a "Return to FZ" action that tries to find the shortest path into an allowed area. -- All Geozone Actions are disabled when in Waypoint Mode. The Pilot is responsible to plan his mission accordingly, to not create a path that crosses NFZ areas. If a mission leads to such area and the pilot disables WP mode, a "Return to FZ" action will be executed. +- All Geozone Actions are disabled when in Waypoint Mode. The Pilot is responsible for planning his mission accordingly, to not create a path that crosses NFZ areas. If a mission leads to such an area and the pilot disables WP mode, a "Return to FZ" action will be executed. - All Geozone Actions are disabled in ACRO and MANUAL Mode. INAV will not take over control in these modes and only OSD Warnings are shown. -- Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clock wise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before upload. +- Planning the Geozone as a polygon, needs to have the vertex numbering to be counter clockwise in ascending order. One vertex must not be dragged over another border to create crossing borders within one zone. INAV Configurator and MWP will check for that before uploading. - Examples of Zones that are not allowed: ![image](https://github.com/user-attachments/assets/50f1a441-39da-4f1c-9128-7375bc593fa5) -- To properly combine multiple Inclusion FZ into one area, the Zones need to overlap at 2 borders and the points where the borders touch, have to be at least 2.5x Loiter-Radius apart for Airplanes at at least 2.5x Multirotor Stop Distance apart for Multirotors. +- To properly combine multiple Inclusion FZ into one area, the Zones need to overlap at 2 borders and the points where the borders touch, must be at least 2.5x Loiter-Radius apart from Airplanes at least 2.5x Multirotor Stop Distance apart for Multirotor. - Example: ![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63) - If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 50m. -- It is not recommended, to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can leat to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. +- It is not recommended to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can lead to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. ## CLI The Geozone Information are stored in two separate data arrays. The first array holds the main Geozone Information and settings. The second array holds the Geozone vertices. @@ -108,8 +108,8 @@ The following commands are available for users: - `geozone` without argument lists the current settings - `geozone vertex` - lists all vertices. - `geozone vertex reset` - deletes all vertices. -- `geozone` vertex reset ` - Deletes all vertices of the zone. -- `geozone` vertex reset ` - Deletes the vertex with the corresponding id from a zone. +- `geozone vertex reset ` - Deletes all vertices of the zone. +- `geozone vertex reset ` - Deletes the vertex with the corresponding id from a zone. The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY CLI_! @@ -120,7 +120,7 @@ The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY - type: 0 = Exclusive, 1 = Inclusive - minimum altitude: In centimetres, 0 = ground - maximum altitude: In centimetres, 0 = infinity -- fence action: 0 = None, 1 = Avoid, 2 = Position hold, 3 = Return to home +- fence action: 0 = None, 1 = Avoid, 2 = Position hold, 3 = Return To Home `geozone vertex ` From b9700f889584f9fe6e35938ff53aaeb3e528c1e0 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 22:21:14 +0100 Subject: [PATCH 12/16] Update Geozones.md added missing CLI commands and array field --- docs/Geozones.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index b6648182790..c94167d2040 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -106,6 +106,7 @@ The Geozone Information are stored in two separate data arrays. The first array The following commands are available for users: - `geozone` without argument lists the current settings +- `geozone reset ` resets a specific geozone and all related vertices. If no ID proveded, all geozones and vertices will be deleted. - `geozone vertex` - lists all vertices. - `geozone vertex reset` - deletes all vertices. - `geozone vertex reset ` - Deletes all vertices of the zone. @@ -113,7 +114,7 @@ The following commands are available for users: The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY CLI_! -`geozone ` +`geozone ` - id: 0 - 63 - shape: 0 = Circular, 1 = Polygonal @@ -121,6 +122,7 @@ The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY - minimum altitude: In centimetres, 0 = ground - maximum altitude: In centimetres, 0 = infinity - fence action: 0 = None, 1 = Avoid, 2 = Position hold, 3 = Return To Home +- vertices count: 0-126 - Sanity check if number of vertices matches with configured zones `geozone vertex ` From 74b0a9b86fb25a9d522b5b40ffc92edc3b739bcc Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 22:44:30 +0100 Subject: [PATCH 13/16] Update Geozones.md --- docs/Geozones.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Geozones.md b/docs/Geozones.md index c94167d2040..4f9e8494c13 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -99,6 +99,7 @@ The most important feature for safety is the automatic path planning for RTH (St - Example: ![image](https://github.com/user-attachments/assets/cc50e24b-dc83-4408-bcba-90d6da33eb63) - If multiple zones with different minimum and maximum altitudes are combined, they need to vertically overlap at least 50m. +- There is a chance that Smart RTH cannot find a path around NFZ areas, if there are multiple very big zones blocking the path. Due to hardware limitations, the amount of waypoints that Smart RTH can create are limited. Many Zones with very long border lines (>500m) cause additional waypoints. - It is not recommended to edit geozones in CLI by hand as this bypasses a lot of sanity checks. Potential errors in zones will disable them or can lead to unexpected behaviors. Transferring Geozones with a DIFF between aircraft is fine. ## CLI From 4c3049c8b3210f0781fccb3a23048175afb7f8b0 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Thu, 14 Nov 2024 22:56:07 +0100 Subject: [PATCH 14/16] Update Geozones.md added AMSL to geozone fields --- docs/Geozones.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index 4f9e8494c13..e4d898ac780 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -115,13 +115,14 @@ The following commands are available for users: The following information are for app-developers. _DO NOT EDIT GEOZONES MANUALLY CLI_! -`geozone ` +`geozone ` - id: 0 - 63 - shape: 0 = Circular, 1 = Polygonal - type: 0 = Exclusive, 1 = Inclusive - minimum altitude: In centimetres, 0 = ground - maximum altitude: In centimetres, 0 = infinity +- is_amsl: 0 = relative, 1 = AMSL - fence action: 0 = None, 1 = Avoid, 2 = Position hold, 3 = Return To Home - vertices count: 0-126 - Sanity check if number of vertices matches with configured zones From 4873cd7e1d882711f2bdbbefda302386eace32b7 Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Fri, 15 Nov 2024 14:45:17 +0100 Subject: [PATCH 15/16] Added MWP required snapshot date --- docs/Geozones.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index e4d898ac780..4f68709ce3c 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -13,7 +13,7 @@ The most important feature for safety is the automatic path planning for RTH (St ## Compatibility - INAV Version: 8.0 or later - INAV Configurator: 8.0 or Later -- [MWPTools:](https://github.com/stronnag/mwptools) Snapshot 2024-11-xx or later +- [MWPTools:](https://github.com/stronnag/mwptools) Snapshot 2024-11-15 or later - Only flight controller with more than 512k of Flash (STM32F405, STM32F765, STM32H743, etc.) - Plane, Multirotor (Rover and Boat are untested at time of writing) From 170652aee1ab48e64b063316f307d5b186c6089f Mon Sep 17 00:00:00 2001 From: b14ckyy <33039058+b14ckyy@users.noreply.github.com> Date: Fri, 15 Nov 2024 14:47:21 +0100 Subject: [PATCH 16/16] Added application links and changed format --- docs/Geozones.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/Geozones.md b/docs/Geozones.md index 4f68709ce3c..483faaef05a 100644 --- a/docs/Geozones.md +++ b/docs/Geozones.md @@ -11,9 +11,9 @@ The most important feature for safety is the automatic path planning for RTH (St ## Compatibility -- INAV Version: 8.0 or later -- INAV Configurator: 8.0 or Later -- [MWPTools:](https://github.com/stronnag/mwptools) Snapshot 2024-11-15 or later +- [INAV Version: 8.0 or later](https://github.com/iNavFlight/inav/releases) +- [INAV Configurator: 8.0 or Later](https://github.com/iNavFlight/inav-configurator/releases) +- [MWPTools: Snapshot 2024-11-15 or later](https://github.com/stronnag/mwptools) - Only flight controller with more than 512k of Flash (STM32F405, STM32F765, STM32H743, etc.) - Plane, Multirotor (Rover and Boat are untested at time of writing)