From f6c8dfd45c22f2be3e4a49b2386dfb36da1b644e Mon Sep 17 00:00:00 2001 From: Matt Lawrence Date: Thu, 17 Oct 2019 19:32:48 -0400 Subject: [PATCH] Copter: Failsafe refactor and FS_OPTIONS parameter --- copter/source/docs/failsafe-battery.rst | 11 ++ copter/source/docs/gcs-failsafe.rst | 85 ++++++------ copter/source/docs/radio-failsafe.rst | 171 ++++++++---------------- 3 files changed, 114 insertions(+), 153 deletions(-) diff --git a/copter/source/docs/failsafe-battery.rst b/copter/source/docs/failsafe-battery.rst index 3be80d782e..45443bd969 100644 --- a/copter/source/docs/failsafe-battery.rst +++ b/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` 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 ` +- bit 1 set: Continue if in auto mode on :ref:`Ground Control Station Failsafe` +- bit 2 set: Continue if in guided mode :ref:`Radio Failsafe ` +- bit 3 set: Continue if landing on any failsafe +- bit 4 set: Continue in pilot control on :ref:`Ground Control Station Failsafe` +- if none of the above are set, then execute the :ref:`BATT_FS_LOW_ACT ` or :ref:`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 ` = 0) the buzzer will buzz and the LEDs will flash yellow. To completely disable the battery failsafe set :ref:`BATT_LOW_VOLT ` and :ref:`BATT_LOW_MAH ` to zero. diff --git a/copter/source/docs/gcs-failsafe.rst b/copter/source/docs/gcs-failsafe.rst index e3183f586f..fcd03cdd67 100644 --- a/copter/source/docs/gcs-failsafe.rst +++ b/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 `, - :ref:`Battery `, and :ref:`EKF / DCM Check `. - -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 `, :ref:`Battery `, and :ref:`EKF / DCM Check `. + +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 ` parameter to: +In Mission Planner's full parameter list or full parameter tree, set the :ref:`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` 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` 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` 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 ` +- bit 1 set: Continue if in auto mode on :ref:`Ground Control Station Failsafe` +- bit 2 set: Continue if in guided mode :ref:`Radio Failsafe ` +- bit 3 set: Continue if landing on any failsafe +- bit 4 set: Continue in pilot control on :ref:`Ground Control Station Failsafe` +- If none of the above are set, then execute the :ref:`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. diff --git a/copter/source/docs/radio-failsafe.rst b/copter/source/docs/radio-failsafe.rst index 220d234df5..75ad76ec1d 100644 --- a/copter/source/docs/radio-failsafe.rst +++ b/copter/source/docs/radio-failsafe.rst @@ -4,19 +4,14 @@ Radio Failsafe ============== -Copter supports Return-To-Launch in cases where contact between the -Pilot's RC transmitter and the flight controller's receiver is lost. -This page explains this failsafe's setup and testing. Note the "Radio -failsafe" was previously called "Throttle failsafe" because of the way -in which some receivers use the throttle channel to signal the loss of -contact. +Copter supports several configurable failsafe options in cases where contact between the Pilot's RC transmitter and the flight controller's receiver is lost. This page explains this failsafe's setup and testing. Note the "Radio failsafe" was previously called "Throttle failsafe" because of the way in which some receivers use the throttle channel to signal the loss of contact. .. image:: ../images/RadioFailsafe_Intro.jpg :target: ../_images/RadioFailsafe_Intro.jpg .. note:: - Copter also supports :ref:`Battery `, :ref:`Ground Station ` and :ref:`EKF/DCM failsafes `. + Copter also supports other failsafes, including: :ref:`Battery `, :ref:`Ground Station ` and :ref:`EKF/DCM failsafes `. See the :ref:`failsafe-landing-page` for more details. When the failsafe will trigger ============================== @@ -24,129 +19,80 @@ When the failsafe will trigger If enabled and set-up correctly the radio failsafe will trigger if: - The pilot turns off the RC transmitter -- The vehicle travels outside of RC range (usually at around 500m ~ - 700m) +- The vehicle travels outside of RC range +- The pilot forces the throttle channel below :ref:`FS_THR_VALUE` from the transmitter - The receiver loses power (unlikely) - The wires connecting the receiver to the flight controller are broken - (unlikely). Note: with APM2 only the ch3 connection between receiver - and flight controller will trigger the failsafe. + (unlikely). What will happen ================ -When a radio failsafe is triggered one of the following will happen: - -- **Nothing** if the vehicle is already disarmed -- **Motors will be immediately disarmed** if the vehicle is landed OR - in stabilize or acro mode and the pilot's throttle is at zero -- **Return-to-Launch (RTL)** if the vehicle has a GPS lock and is more - than 2 meters from the home position -- **LAND** if the vehicle has: - - - no GPS lock OR - - is within 2 meters of home OR - - the FS_THR_ENABLE parameter is set to "Enabled Always Land" - -**Continue with the mission** if the vehicle is in AUTO mode and the -FS_THR_ENABLE parameter is set to "Enabled Continue with Mission in -Auto Mode". - -If the failsafe clears (i.e. transmitter and receiver regain contact) -the copter will remain in its 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, the -vehicle was in Loiter when the failsafe occurred and the flight mode was -automatically changed to RTL, even after the transmitter and receiver -regained contact, the vehicle would remain in RTL. If the pilot wished -to re-take control in Loiter he/she would need to change your flight -mode switch to another position and then back to Loiter. - -Receiver and flight controller set-up -===================================== - -By default, a newly purchased receiver will be set-up to simply hold all -channels at their last known position when the receiver and transmitter -lose contact. This is not good because the flight controller has no way -to know that the Pilot has lost control of the vehicle. Instead the -receiver must be set-up to signal to the flight controller it has lost -contact and there are two ways that it can do this (the method depends -upon the receiver): - -- "Low-Throttle" method - the receiver pulls the throttle channel - (normally channel 3) to a value below the bottom of it's normal range - (normally below 975). This method is used by Futaba systems and many - older systems. -- "No Signal" method - the receiver stops sending signals to the flight - controller. This is the preferred method and is how most modern - FrSky receivers operate. - -Each brand of Transmitter/Receiver is slightly different so please refer -to your transmitter's user manual to determine which method is available -and how to set it up. - -Set-up for low-throttle method ------------------------------- +When a radio 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, or to continue landing if already in a landing phase. -.. youtube:: qf8YinLKQww - :width: 100% +- 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. -Above is the setup method for a Futaba T7C Transmitter with R617FS or -TFR4-B receiver which uses the "low throttle" method. +If the failsafe clears (i.e. transmitter and receiver regain contact) 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 transmitter and receiver regained contact, the vehicle would remain in RTL. If the pilot wished to re-take control in Loiter he/she would need to change your flight mode switch to another position and then back to Loiter. -With the LiPo battery disconnected: +Receiver Configuration +====================== -- Connect your flight controller to the mission planner and select - Initial Setup >> Mandatory Hardware >> Failsafe. -- Set the Failsafe Options to one of the three options: +By default, most newly purchased receivers will simply not output pulses if contact with the transmitter is lost. However, some low end receivers will be set-up to simply hold all channels at their last known position. This is not good because the flight controller has no way to know that the Pilot has lost control of the vehicle. Instead the receiver must be set-up to signal to the flight controller it has lost contact and there are two ways that it can do this (the method depends upon the receiver). Each brand of Transmitter/Receiver is slightly different so please refer to your transmitter's user manual to determine which method is available and how to set it up. - - "Enabled always RTL" to force the vehicle to always RTL even if - flying a mission in AUTO mode - - "Enabled Continue with Mission in AUTO" to allow the vehicle to - continue with missions even if it takes the vehicle outside of RC - range (not recommended). In all other cases the vehicle will RTL. - - "Enable always LAND" to force the vehicle to Land immediately if - it loses RC contact +Receiver configuration for low-throttle method +---------------------------------------------- +The **"Low-Throttle" method** pulls the throttle channel (normally channel 3) to a value below the bottom of it's normal range (normally below 1000us). This method is used by Futaba systems and many older systems. Below is the setup method for a Futaba T7C Transmitter with R617FS or TFR4-B receiver which uses the "low throttle" method. -Set the "FS Pwm" value to be: - -- at least 10 PWM higher than your Channel 3's PWM value when the - throttle stick is fully down and the transmitter is **off** -- at least 10 lower than your channel 3's PWM value when the throttle - stick is fully down and the transmitter is **on**\ +.. youtube:: qf8YinLKQww + :width: 100% -- *above 910* -.. image:: ../images/RadioFailsafe_MPSetup.png - :target: ../_images/RadioFailsafe_MPSetup.png +Many receivers allow for the failsafe positions to be set either by simply pressing a button on the receiver, or directly from the transmitter. In this case, the transmitter is temporarily adjusted to output a throttle signal below the normal low idle position (if low idle is 1000us, then 990uS would be sent) setting this as the failsafe value for the receiver, then adjusting low stick back to normal idle position. This below throttle idle value is then set for :ref:`FS_THR_VALUE`, as discussed below. -Set-up for No-Signal method ---------------------------- +Receiver configuration for No-Signal method +------------------------------------------- +**"No Signal" method** - the receiver stops sending signals to the flight controller. This is the preferred method and is how most modern FrSky receivers operate. Below is the setup method for a FlySky 9 channel transmitter with FrSky D4R-II receiver which uses the "No Signal" method. .. youtube:: FhKREgqjCpM :width: 100% -Above is the setup method for a FlySky 9 channel transmitter with FrSky -D4R-II receiver which uses the "No Signal" method. -Similar to the "Low-Throttle" method, with the LiPo battery -disconnected: +Parameter Configuration +======================== + +The :ref:`FS_THR_ENABLE` parameter can be set in the Mission Planner full parameter list or full parameter tree, or can also be set using the Mission Planner *failsafe options* dropdown in the Initial Setup >> Mandatory Hardware >> Failsafe menu. -- Connect your flight controller to the mission planner and select - Initial Setup >> Mandatory Hardware >> Failsafe. -- Set the Failsafe Options to one of the three options: +- **Disabled** (Value 0) will disable the radio 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` parameter for this function. Setting this value in Copter 4.0 and later version will automatically be converted and set to (Value 1) and the :ref:`FS_OPTIONS` will be modified to include bit (0) in the bitmask for "Continue if in auto mode on Radio Failsafe". +- **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. +- Any invaild value (Such as accidentally enter 99 as a parameter value) will will behave the same as **Enabled Always LAND** - - "Enabled always RTL" to force the vehicle to always RTL even if - flying a mission in AUTO mode - - "Enabled Continue with Mission in AUTO" to allow the vehicle to - continue with missions even if it takes the vehicle outside of RC - range (not recommended). In all other cases the vehicle will RTL. - - "Enable always LAND" to force the vehicle to Land immediately if - it loses RC contact +The :ref:`FS_THR_VALUE` parameter can be set in the Mission Planner full parameter list or full parameter tree, or can also be set using the Mission Planner *FS PWM* value in the Initial Setup >> Mandatory Hardware >> Failsafe menu. +- At least 10 PWM higher than your Channel 3's PWM value when the throttle stick is fully down and the transmitter is **off** +- At least 10 PWM lower than your channel 3's PWM value when the throttle stick is fully down and the transmitter is **on** +- Above 910 PWM -Because the throttle is not pulled low, there is normally no need to -adjust the "FS Pwm" value from it's default (975). Just ensure that -it's well below (i.e. at least 10pwm points below) the minimum value -that channel 3 (throttle) can be. +The :ref:`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 ` +- bit 1 set: Continue if in auto mode on :ref:`Ground Control Station Failsafe` +- bit 2 set: Continue if in guided mode :ref:`Radio Failsafe ` +- bit 3 set: Continue if landing on any failsafe +- bit 4 set: Continue in pilot control on :ref:`Ground Control Station Failsafe` +- if none of the above are set, then execute the :ref:`FS_THR_ENABLE` option as configured. + +.. note:: Only bitmask bits 0, 2, & 3 affect actions taken during radio failsafe. This parameter also works in conjunction with the battery and GCS failsafe, so ensure you are taking all options into account when setting this parameter. + +Below is a screenshot of the Mission Planner Initial Setup >> Mandatory Hardware >> Failsafe menu. + +.. image:: ../images/RadioFailsafe_MPSetup.png + :target: ../_images/RadioFailsafe_MPSetup.png Testing ======= @@ -173,7 +119,7 @@ channel drops with loss of radio contact** .. image:: ../images/MPFailsafeSetup1.jpg :target: ../_images/MPFailsafeSetup1.jpg -Test #2 : ensuring motors disarm if in stabilize or acro with throttle +Test #2 : ensuring motors disarm if in STABILIZE or ACRO with throttle at zero - Switch to stabilize mode, arm your motors but keep your throttle at @@ -203,9 +149,10 @@ Test #5 (optional) : removing power from the receiver - Switch to stabilize mode, arm your motors and keep your throttle above zero. - Carefully disconnect the power wires connecting the receiver to the - APM + flight controller - The Flight Mode should switch to RTL or LAND as described in Test #3 -- Warning: unplug the APM so that it is powered down before reattaching + +.. warning:: Unplug the flight controller so that it is powered down before reattaching the receiver's power Using the receiver to set the flight mode (not recommended) @@ -213,9 +160,9 @@ Using the receiver to set the flight mode (not recommended) Instead of setting up the receiver and flight controller as described above (i.e. "Low-Throttle" and "No Signal" methods) the receiver can be -set-up to set channel 5 (flight mode channel) to a :ref:`flight mode `\ slot that has +set-up to set channel 5 (flight mode channel) to a :ref:`flight mode ` slot that has been set to RTL. For example the receiver could be setup to move ch5's -pwm value to 1700 which is "Flight Mode 5" which could then be set to +pwm value to 1700us which is "Flight Mode 5" which could then be set to RTL on the Mission Planner's Initial Setup >> Mandatory Hardware >> Flight Modes screen.