docs/Safehomes.md

   1 # INav - Safehomes
   2
   3 ## Introduction
   4
   5 The "Home" position is used for the landing point when landing is enabled or in an emergency situation.  It is usually determined by the GPS location where the aircraft is armed.
   6
   7 For airplanes, the landing procedure is explained very well by Pawel Spychalski [here.](https://quadmeup.com/inav-1-8-automated-landing-for-fixed-wings/)
   8
   9 <img src="https://quadmeup.com/wp-content/uploads/2017/06/fixed-wing-landing-1024x683.png" width="600">
  10
  11 One potential risk when landing is that there might be buildings, trees and other obstacles in the way as the airplance circles lower toward the ground at the arming point.  Most people don't go the middle of the field when arming their airplanes.
  12
  13 ## Safehome
  14
  15 Safehomes are a list of GPS coordinates that identify safe landing points.  You can define up to 8 safehomes for different locations you fly at.  When the flight controller is armed, it checks the list of safehomes.  The nearest safehome that is enabled and within ```safehome_max_distance``` (default 200m) of the current position is identified.  The arming home location remains as home.
  16
  17 When RTH is activated, whether by radio failsafe, or using the RTH radio control mode, the safehome identified during arming will replace the home location.  If RTH is turned off, either by regaining radio control or turning off the RTH radio control mode, the home location will return back to arming point.
  18
  19 The safehome operating mode is set using ```safehome_usage_mode```.  If ```OFF```, safehomes will not be used.  If ```RTH```, the safehome will replace the arming location when RTH is activated, either manually or because of RX failsafe.  If ```RTH_FS```, the safehome will only be used for RX failsafe.  This option can be changed using the OSD menu.
  20
  21 If you frequently use RTH to return back to the arming point, you may not want the aircraft to fly to the safehome.  Let it do this at least once to confirm safehomes is working as expected.  Afterward, `set safehome_usage_mode = RTH_FS` and the safehome will only be used for failsafe.
  22
  23 When using mode `RTH_FS`, you should confirm that your radio's failsafe configuration triggers the INAV failsafe mode.  With many receivers, you have the ability to specify what signal to output during failsafe conditions.
  24
  25 When you are choosing safehome locations, ensure that the location is clear of obstructions for a radius more than 50m (`nav_fw_loiter_radius`).  As the plane descends, the circles aren't always symmetrical, as wind direction could result in some wider or tighter turns.  Also, the direction and length of the final landing stage is also unknown.  You want to choose a point that has provides a margin for variation and the final landing.
  26
  27 If your safehome is not visible from your current location, use extra caution.  A visual check of the safehome is recommend prior to flying.  If the safehome is in use, you can use the OSD menu to disable safehome usage prior to your flight.
  28
  29 ## OSD Message when Armed
  30
  31 When the aircraft is armed, the OSD briefly shows `ARMED` and the current GPS position and current date and time.
  32
  33 If a safehome is selected, an additional message appears:
  34 ```
  35      H - DIST -> SAFEHOME n  <- New message
  36                                 n   is the Safehome index (0-7)
  37             ARMED               DIST is the distance from
  38         GPS LATITUDE                 your current position to this safehome
  39         GPS LONGITUDE
  40         GPS PLUS CODE
  41
  42          CURRENT DATE
  43          CURRENT TIME
  44 ```
  45 The GPS details are those of the arming location, not the safehome.
  46 To draw your attention to a safehome being selected, the message flashes and stays visible longer.
  47
  48 If a safehome was found, but ``safehome_usage_mode``` is ```OFF```, the message ```SAFEHOME FOUND; MODE OFF``` will appear.
  49
  50 ## OSD Message during RTH
  51
  52 If RTH is in progress to a safehome, the message "DIVERTING TO SAFEHOME" will be displayed.
  53
  54 ## CLI command `safehome` to manage safehomes
  55
  56 `safehome` - List all safehomes
  57
  58 `safehome reset` - Clears all safehomes.
  59
  60 `safehome <n> <enabled> <lat> <lon>` - Set the parameters of a safehome with index `<n>`.
  61
  62 Parameters:
  63
  64   * `<enabled>` - 0 is disabled, 1 is enabled.
  65   * `<lat>` - Latitude (WGS84), in degrees * 1E7 (for example 123456789 means 12.3456789).
  66   * `<lon>` - Longitude.
  67
  68 Note that coordinates from Google Maps only have five or six decimals, so you need to pad zero decimals until you have seven before removing the decimal period to set the correct safehome location. For example, coordinates 54.353319 -4.517927 obtained from Google Maps need to be entered as 543533190 -45179270, coordiniates 43.54648 -7.86545 as 435464800 -78654500 and 51.309842 -0.095651 as 513098420 -00956510.
  69
  70 Safehomes are saved along with your regular settings and will appear in `diff` and `dump` output.  Use `save` to save any changes, as with other settings.
  71
  72 ### `safehome` example
  73
  74 ```
  75 # safehome
  76 safehome 0 1 543533190 -45179270
  77 safehome 1 1 435464800 -78654500
  78 safehome 2 1 513098420 -00956510
  79 safehome 3 0 0 0
  80 safehome 4 0 0 0
  81 safehome 5 0 0 0
  82 safehome 6 0 0 0
  83 safehome 7 0 0 0
  84
  85 ```
  86