Copter: Failsafe refactor and FS_OPTIONS parameter

copter/source/docs/failsafe-battery.rst

@@ -42,6 +42,17 @@ Then one of the following will happen:
 
 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)
 
+The :ref:`FS_OPTIONS<FS_OPTIONS>` parameter (Copter 4.0 and later) is a bitmask parameter to select one or more options that modify the standard actions of the radio, GCS, and battery failsafe.  In the Mission Planner full parameter list or full parameter tree, the handy checkbox popup window is an easy what to set this (and any other bitmask) parameter. Be sure to go to Help > Check Beta Updates to pull the latest parameter definitions first while connected to the internet. The FS_OPTIONS bits are as follows:
+
+- bit 0 set: Continue if in auto mode on :ref:`Radio Failsafe <radio-failsafe>`
+- bit 1 set: Continue if in auto mode on :ref:`Ground Control Station Failsafe<gcs-failsafe>`
+- bit 2 set: Continue if in guided mode :ref:`Radio Failsafe <radio-failsafe>`
+- bit 3 set: Continue if landing on any failsafe
+- bit 4 set: Continue in pilot control on :ref:`Ground Control Station Failsafe<gcs-failsafe>`
+- if none of the above are set, then execute the :ref:`BATT_FS_LOW_ACT <BATT_FS_LOW_ACT>` or :ref:`BATT_FS_CRT_ACT <BATT_FS_CRT_ACT>` options as configured.
+
+.. note:: Only bitmask bit 3 affects actions taken during Battery failsafe. This parameter also works in conjunction with the GCS and radio failsafe, so ensure you are taking all options into account when setting this parameter.
+
 .. note::
 
     Even if the failsafe action is set to "None" (i.e. :ref:`BATT_FS_LOW_ACT <BATT_FS_LOW_ACT>` = 0) the buzzer will buzz and the LEDs will flash yellow.  To completely disable the battery failsafe set :ref:`BATT_LOW_VOLT <BATT_LOW_VOLT>` and :ref:`BATT_LOW_MAH <BATT_LOW_MAH>` to zero.

copter/source/docs/gcs-failsafe.rst

@@ -4,58 +4,61 @@
 GCS Failsafe
 ============
 
-This page covers the set-up and testing of the Ground Station Control
-(GCS) failsafe.
+The Ground Station Control (GCS) failsafe controls how Copter will behave if contact with the GCS is lost.  The GCS failsafe monitors the time since the last mavlink heartbeat from the GCS.  If no heartbeat is received in over 2.5 seconds, the GCS failsafe event will trigger based on your parameter settings. Note that if no GCS is ever connected, the GCS failsafe will remain inactive regardless of parameter settings.
 
 .. note::
 
-   Copter also supports other failsafes: :ref:`Radio <radio-failsafe>`,
-   :ref:`Battery <failsafe-battery>`, and :ref:`EKF / DCM Check <ekf-inav-failsafe>`.
-
-Overview
-========
-
-The Ground Station Control (GCS) failsafe controls how Copter will
-behave if contact with the GCS is lost. Depending on the setting and
-vehicle position the failsafe will either RTL/LAND, or continue an
-active mission.
-
-More specifically, if you have been using the GCS to control Copter
-(i.e. using a joystick) and then lose GCS contact for at least 5 seconds
-the following will happen:
-
--  Disarm motors - if you are in stabilize or acro mode and your
-   throttle is zero
--  RTL - if you have a GPS lock and are more than 2 meters from your
-   home position
--  LAND - if you have no GPS lock or are within 2 meters of home
--  Continue with the mission - if you are in AUTO mode and have set the
-   GCS Failsafe Options to 2 (Enabled_continue_in_auto_mode).
-
-If the failsafe clears (contact with the ground station is restored)
-Copter will remain in it's current flight mode. It
-will **not** automatically return to the flight mode that was active
-before the failsafe was triggered. This means that if, for example, you
-are flying in stabilize mode when the failsafe is triggered, and this
-causes the flight mode to change to RTL or LAND, if you wish to re-take
-control of the copter you will need to set your flight mode again back
-to stabilize.
+   Copter also supports other failsafes: :ref:`Radio <radio-failsafe>`, :ref:`Battery <failsafe-battery>`, and :ref:`EKF / DCM Check <ekf-inav-failsafe>`.
+
+When the failsafe will trigger
+==============================
+
+The following situations can cause a loss of GCS mavlink heartbeat, triggering a GCS failsafe event after 2.5 seconds:
+
+-  The operator turns off or otherwise disconnects the GCS
+-  The copter travels beyond the range of the  GCS telemetry radios
+-  The GCS telemetry radio on either end loses power
+-  Wires connecting the GCS telemetry radio to the flight controller or ground equipment become disconnected
+
+What will happen
+================
+
+When a GCS failsafe is triggered, the copter can be configured via parameters to do nothing, land immediately, RTL, or SmartRTL.  It can also be configured to bypass the failsafe in an Auto Mode mission, bypass the failsafe in pilot controlled modes, or to continue landing if already in a landing phase.
+
+- If the copter is disarmed, no failsafe will take place.
+- If the copter is armed but has landed, the copter will immediately disarm.
+- If the copter is armed in Stabilize or Acro modes, and the throttle input is at minimum, the copter will immediately disarm.
+- Otherwise, the copter will take the actions as configured in the parameters described below.
+
+If the failsafe clears (i.e. GCS reconnects and mavlink heartbeat is restored) the copter will remain in its failsafe mode. It will **not** automatically return to the flight mode that was active before the failsafe was triggered. This means that if, for example, the vehicle was in Loiter when the failsafe occurred and the flight mode was automatically changed to RTL, even after the GCS reconnects, the vehicle would remain in RTL.  If the pilot wished to re-take control in Loiter he/she would need to change the flight mode switch to another position and then back to Loiter.
 
 Setting the failsafe
 ====================
 
-In Mission Planner's Advanced Parameter List, set the
-:ref:`FS_GCS_ENABLE <FS_GCS_ENABLE>` parameter to:
+In Mission Planner's  full parameter list or full parameter tree, set the :ref:`FS_GCS_ENABLE <FS_GCS_ENABLE>` parameter to:
+
+-  **Disabled** (Value 0) will disable the GCS failsafe entirely.
+-  **Enabled Always RTL** (Value 1) will switch the copter to RTL Mode.  If the GPS position is not usable, the copter will change to Land Mode instead.
+-  **Enabled Continue with Mission in Auto Mode (Deprecated in 4.0+)** (Value 2) will ignore the failsafe in an Auto Mode mission. Otherwise, it will behave the same as *Enabled Always RTL*. This option no longer exists in ArduCopter 4.0. Instead, see the :ref:`FS_OPTIONS<FS_OPTIONS>` parameter for this function. Setting this value in Copter 4.0 and later version will automatically be converted and set to Value 1 (Always RTL) and the :ref:`FS_OPTIONS<FS_OPTIONS>` bitmask will be modified to include bit (1) for "Continue auto mode mission on GCS failsafe".
+-  **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.
+-  Any invaild value (Such as accidentally enter 99 as a parameter value) will will behave the same as **Enabled Always RTL**
+
+The :ref:`FS_OPTIONS<FS_OPTIONS>` parameter (Copter 4.0 and later) is a bitmask parameter to select one or more options that modify the standard actions of the radio, GCS, and battery failsafe. In the Mission Planner full parameter list or full parameter tree, the handy checkbox popup window is an easy what to set this (and any other bitmask) parameter. Be sure to go to Help > Check Beta Updates to pull the latest parameter definitions first while connected to the internet. The FS_OPTIONS bits are as follows:
+
+- bit 0 set: Continue if in auto mode on :ref:`Radio Failsafe <radio-failsafe>`
+- bit 1 set: Continue if in auto mode on :ref:`Ground Control Station Failsafe<gcs-failsafe>`
+- bit 2 set: Continue if in guided mode :ref:`Radio Failsafe <radio-failsafe>`
+- bit 3 set: Continue if landing on any failsafe
+- bit 4 set: Continue in pilot control on :ref:`Ground Control Station Failsafe<gcs-failsafe>`
+- If none of the above are set, then execute the :ref:`FS_GCS_ENABLE <FS_GCS_ENABLE>` option as configured.
 
--  0 to disable the GCS failsafe
--  1 to enable and always RTL in event of loss of contact
--  2 to RTL unless in AUTO mode in which case we should continue with
-   the mission
+.. note:: Only bitmask bits 1, 3, & 4 affect actions taken during GCS failsafe. This parameter also works in conjunction with the battery and radio failsafe, so ensure you are taking all options into account when setting this parameter.
 
 .. image:: ../images/FailsafeAdvPar801.jpg
     :target: ../_images/FailsafeAdvPar801.jpg
 
 .. note::
 
-   All Failsafe Parameters can be observed or set from the Advanced
-   Parameter List.
+   All Failsafe Parameters can be observed or set from the Advanced Parameter List.