make do-land-start common

common/source/docs/common-do-land-start.rst

@@ -0,0 +1,43 @@
+.. _common-do-land-start:
+[copywiki destination="copter,plane,rover,planner"]
+===================
+Using DO_LAND_START
+===================
+
+The :ref:`DO_LAND_START <mav_cmd_do_land_start>` mission item can be used for two purposes:
+
+#. In Plane, to provide an automatic re-attempt for an aborted NAV_LAND autolanding in a mission. (See :ref:`aborting-autolanding`)
+#. To provide an automatic landing sequence for RTLs in Plane or as a failsafe action in Copter.
+
+.. note:: in Rover, it can be used, but only via Scripting call to start the landing sequence.
+
+[site wiki="plane"]
+To trigger an automatic landing as part of an RTL(return to launch) you need to do two things:
+
+-  add a :ref:`DO_LAND_START <mav_cmd_do_land_start>` mission item to your mission, just before the start of your landing sequence which sets up the approach waypoints and ends with a NAV_LAND item.
+-  set the :ref:`RTL_AUTOLAND <RTL_AUTOLAND>` parameter to 1 or 2
+
+The exact behaviour depends on the :ref:`RTL_AUTOLAND<RTL_AUTOLAND>` value:
+-  If :ref:`RTL_AUTOLAND<RTL_AUTOLAND>` = 1, then the plane will first RTL as normal, then when it starts circling the return point (home or a rally point) it will then switch to the AUTO mission after the ``DO_LAND_START`` 
+-  If :ref:`RTL_AUTOLAND<RTL_AUTOLAND>` = 2, then the plane will bypass the RTL completely and go straight to the landing sequence after the ``DO_LAND_START``.
+
+.. note:: the "landing sequence" whose start is the ``DO_LAND_START`` marker, does not actually have to include a landing! it can be any sequence of valid mission commands. For example, flying to a location, and changing to an indefinite VTOL loiter (applies only to a QuadPlane, obviously).
+
+.. note:: ArduPilot checks to see if there is a ``DO_LAND_START`` mission items before arming, and :ref:`RTL_AUTOLAND<RTL_AUTOLAND>` is set to 0. If so, a pre-arm failure condition will prevent arming. If it is desired to use a ``DO_LAND_START`` only for aborted autolandings and not as an RTL action override, then set :ref:`RTL_AUTOLAND<RTL_AUTOLAND>` = 3, to allow arming. Its use for an aborted autolanding is explained in :ref:`aborting-autolanding`.
+
+.. note:: if you execute an RTL due to a battery failsafe and the :ref:`MIS_OPTIONS<MIS_OPTIONS>` bit 1 (Use distance to land) is set, then if continuing the mission results in a closer landing point, then the mission will proceed.
+
+[/site]
+[site wiki="copter"]
+
+To use, you need to do two things:
+
+-  add a :ref:`DO_LAND_START <mav_cmd_do_land_start>` mission item to your mission, just before the start of your landing sequence(s).
+-  use ``DO_LAND_START`` as a failsafe action. For example, setting :ref:`FS_THR_ENABLE<FS_THR_ENABLE>` = "6" for RC failsafe.
+
+.. note:: the "landing sequence" whose start is the ``DO_LAND_START`` marker, does not actually have to include a landing! it can be any sequence of valid mission commands.
+[/site]
+
+You can optionally include more than one ``DO_LAND_START`` mission item in your mission. If that is done then the latitude/longitude/altitude of the ``DO_LAND_START`` mission items is used to choose which landing sequence to use. The ``DO_LAND_START`` closest to the current location in all three dimensions is used. This can be useful if you have multiple landing sequences for different wind conditions or different areas.
+
+.. note:: If you are already in a landing sequence (NAV_LAND or DO_START_LAND sequence), then it will continue.

common/source/docs/common-mission-planning.rst

@@ -29,6 +29,7 @@ This section contains articles about creating missions that will run when the ve
     Mission Command List <common-mavlink-mission-command-messages-mav_cmd>
     Camera Control in Auto Missions <common-camera-control-and-auto-missions-in-mission-planner>
     Rally Points <common-rally-points>
+    DO_LAND_START <common-do-land-start>
     Geotagging Images with Mission Planner <common-geotagging-images-with-mission-planner>
 
 [site wiki="plane"]

common/source/docs/common-planning-a-mission-with-waypoints-and-events.rst

@@ -179,7 +179,7 @@ The :ref:`MIS_OPTIONS<MIS_OPTIONS>` parameter bits can be set to modify how miss
 ref:`MIS_OPTIONS<MIS_OPTIONS>` bit   Option
 ==================================   ================================
 0                                    Clears the loaded mission on boot. Must be loaded after each boot.
-1 (Plane only)                       Use distance to land calculation on battery failsafe. See :ref:`do_land_start`
+1 (Plane only)                       Use distance to land calculation on battery failsafe. See :ref:`common-do-land-start`
 2                                    Continue after landing. Advances mission item pointer to next mission item after landing complete. If no item exists, RTL.
 ==================================   ================================
 

copter/source/docs/failsafe-battery.rst

@@ -41,7 +41,7 @@ Then one of the following will happen:
   - **3** : SmartRTL or RTL - the vehicle will switch to :ref:`SmartRTL <smartrtl-mode>` mode if possible, if not possible (because SmartRTL's position buffer is full) the vehicle will switch to :ref:`RTL <rtl-mode>`. If RTL is also not possible (because of no good position estimate) the vehicle will switch to :ref:`Land <land-mode>`
   - **4** : SmartRTL or Land - the vehicle will switch to :ref:`SmartRTL <smartrtl-mode>` mode if possible, if not possible (because SmartRTL's position buffer is full) the vehicle will switch to :ref:`Land <land-mode>`
   - **5** : Terminate - the vehicle will disarm the motors. This is a dangerous option that should not be used in most cases
-  - **6** : Auto DO_LAND_START or RTL - the vehicle will jump to the nearest "DO_LAND_START" mission item or RTL if no "DO_LAND_START" mission item has been programmed.
+  - **6** : Auto DO_LAND_START or RTL - the vehicle will jump to the nearest "DO_LAND_START" mission item or RTL if no "DO_LAND_START" mission item has been programmed (see :ref:`common-do-land-start`).
 
 As with all failsafes, the user can re-take control of the vehicle by changing the flight mode switch to another mode. The battery failsafe will not trigger again unless the two-layer failsafe is setup (see below)
 

copter/source/docs/gcs-failsafe.rst

@@ -44,7 +44,7 @@ In Mission Planner's  full parameter list or full parameter tree, set the :ref:`
 -  **Enabled SmartRTL or RTL** (Value 3) will switch the copter to SmartRTL mode. If SmartRTL is not available, the copter will switch to RTL Mode instead.  If the GPS position is not usable, the copter will change to Land Mode instead.
 -  **Enabled SmartRTL or Land** (Value 4) will switch the copter to SmartRTL mode. If SmartRTL is not available, the copter will switch to Land Mode instead.
 -  **Enabled Always Land** (Value 5) will switch the copter to Land Mode.
--  **Auto DO_LAND_START or RTL** (Value 6) will execute a DO_LAND_START auto mission sequence (see :ref:`do_land_start`) or and RTL if no DO_LAND_START sequence exists.
+-  **Auto DO_LAND_START or RTL** (Value 6) will execute a DO_LAND_START auto mission sequence (see :ref:`do_land_start`) or and RTL if no DO_LAND_START sequence exists(see :ref:`common-do-land-start`).
 - **BRAKE or LAND** (Value 7): switch to BRAKE mode if included in firmware or to LAND mode, if not included.
 -  Any invalid value (Such as accidentally enter 99 as a parameter value) will will behave the same as **Enabled Always RTL**
 

copter/source/docs/radio-failsafe.rst

@@ -76,7 +76,7 @@ The :ref:`FS_THR_ENABLE<FS_THR_ENABLE>` parameter can be set in the Mission Plan
 -  **Enabled Always Land** (Value 3) will switch the copter to Land Mode.
 -  **Enabled SmartRTL or RTL** (Value 4) will switch the copter to SmartRTL mode. If SmartRTL is not available, the copter will switch to RTL Mode instead.  If the GPS position is not usable, the copter will change to Land Mode instead.
 -  **Enabled SmartRTL or Land** (Value 5) will switch the copter to SmartRTL mode. If SmartRTL is not available, the copter will switch to Land Mode instead.
--  **Enabled Auto DO_LAND_START or RTL** (value 6) will jump to the nearest "DO_LAND_START" mission item or RTL if no "DO_LAND_START" mission item has been programmed.
+-  **Enabled Auto DO_LAND_START or RTL** (value 6) will jump to the nearest "DO_LAND_START" mission item or RTL if no "DO_LAND_START" mission item has been programmed(see :ref:`common-do-land-start`).
 -  **Enabled always Brake or Land** will BRAKE or LAND if GPS position is not available.
 -  Any invaild value (Such as accidentally enter 99 as a parameter value) will will behave the same as **Enabled Always LAND**
 

plane/source/docs/automatic-landing.rst

@@ -24,7 +24,7 @@ For many vehicles, most of the parameters associated with autolanding can be lef
     Precision Autolanding <precision-autolanding>
     RangeFinder Autolanding <rangefinder-autolanding>
     Using Reverse Thrust in Autolanding <reverse-thrust-autolanding>
-    Using DO_LAND_START <do-land-start>
+    Using DO_LAND_START <common-do-land-start>
 
 Basic Autolanding
 =================