Failsafe

Paparazzi has several built-in failsafe features ranging from lowlevel to highlevel and from implied to optional.
On the lowest level, precise timing of the transmitter pulses creates safety that goes beyond traditional switches enabling safer use of old RC equipment.
On the highest level, the exceptions feature of the flight-plans allow for very flexible custom built failsafe features.
== Fixed-wing Fly By Wire (FBW) ==
=== 'Failsafe Switch' ===
The lowest level of paparazzi is the FBW (Fly By Wire) controller that reads the RC, reads the autopilot commands and drives the servos based on the lowlevel failsafe options.
This is the 'switch' between manual or automatic modes. Therefore there is no need for another failsafe board. Indeed, the paparazzi FBW has evolved with so much intelligence that it is certainly safer than some and probably at least as safe as any other failsafe switches. This is amongst others (besides the highlevel validated code, separated process, ...) because paparazzi FBW unlike generic switches is given precise remote control information in its RC.xml. If you use a wrong type of transmitter (e.g. not the right amount of channels, or not the correct interval or sync pulse length) then even when on the same frequency the FBW will not listen to the commands. Also, if 2 transmitters are on the same frequency, then the chance of both signals together still being read as valid is very small. (This does NOT mean you can fly with 2 planes on the same frequency however. This only means that in this catastrophic scenario paparazzi does a pretty good job in delaying disaster from happening. )
Be aware that there exist many failsafe switches that use a pulse of the RC (e.g. channel 5) to switch 
between autopilot or RC. When using analog RC equipment or any equipment that does not have correctly 
programmed failsafe servo values this is very unsafe as whenever the RC is out of range the switch will 
start switching back and forth putting the UAV out of control even if the autpilot is perfectly OK.
CAUTION! Common receivers today (especially 2.4GHz receivers) has own failsafe mode(s).
Three modes are used in most cases:
# No failsafe: the receiver will switch off servo sinals in case of RC connection lost.Paparazzi own failsafe will be activated in case of RC connection lost.
# Last position: the receiver will keep the last valid servo positions in case of RC connection lost.Paparazzi own failsafe will NOT be activated. (The autopilot will not have information on RC signal lost.)
# Preset servo positions: the receiver will switch servo sinals to a preset value in case of RC connection lost.This values should be set directly in the receiver. (Read manual.) Paparazzi own failsafe will not be activated.BUT! If you set the failsafe value of the channel used for Mode control(Manual/Auto1/Auto2) to the value which commands Auto2, then paparazzi will switch automaticaly to Auto2 mode in case of RC connection lost.
=== FBW logic ===
* RC GOOD: listen to the MODE switch on the Transmitter(this means whenever the remote control is close enough the pilot has the final word)
* RC BAD: go to automatic mode (see further on for handling of automatic modes)
* RC BAD AND AUTOPILOT DATA TIMEOUT: failsafe command values from airframe configuration XML(do not omit to fill in useful failsafe values in the command section; usually slight pitch up for minimal speed, ailerons neutral in order not to roll inverted and of course throttle down: it is not recommended to try to make turns here with aileron deflections. A small rudder deflection on the other hand is recommended when available )
== Fixedwing AutoPilot (AP) ==
=== Home mode ===
The HOME mode is a failsafe mode where the standard navigation (own flightplan) is suspended and the aircraft 
flies a circle around the HOME waypoint at a safe altitude (security_height attribute in your flight-plan). This mode is triggered on different events. 
Leaving this mode is done by clicking on the red HOME text in the GCS.
==== Too far from HOME ====
Home mode is triggered if the distance to the HOME waypoint is greater than a threshold (max_dist_from_home attribute) set in the 
fight-plan (displayed as a circle on the GCS map).
The MAX_DIST_FROM_HOME define is generated (and included via generated/flight_plan.h) from the max_dist_from_home attribute of the flight plan xml file.
==== RC link failure while manual or AUTO1 ====
Home mode is triggered if the RC uplink is lost in MANUAL or AUTO 1 modes.
* When MANUAL the manual mode is restored as soon as the RC link is restored as expected.
* However: In AUTO 1 mode, one must manually leave the HOME mode using the GCS
! Word of caution with respect to AUTO1: 
When flying auto1 with a lot of RC interference (which is not recommended anyway), be prepared that the plane might enter HOME mode.
Also, do not be tempted to fly far away in auto1 mode (possibly out of RC range) without a fully tuned auto2 autopilot or sufficient visual contact to allow manual control. As soon as you are so far that RC packets get lost, paparazzi will switch to HOME and will stay in HOME until you choose MANUAL of re-enable AUTO1 on the GCS !
===== Setting RC lost mode =====
By default when RC is lost (in Manual or Auto1) HOME mode is triggered, you can change this behaviour by setting the RC_LOST_MODE:
 <define name="RC_LOST_MODE" value="PPRZ_MODE_AUTO2"/>
In this example RC_LOST_MODE is set to AUTO2, which can be useful if you experience glitches on your RC on the mode channel and want the aircraft to continue the mission instead of triggering HOME mode. BUT only use this if you have AUTO2 navigation set up properly and everything is initialized correctly! Another scenario to set this value is if you will fly out of your RC range in a long range mission.
You can disable HOME mode locking by adding the following line in your airframe file:
 <define name="UNLOCKED_HOME_MODE" value="TRUE"/>
Then you can restore from HOME mode using the RC and do not need to do this on the GCS if in AUTO1.
Caution! Use these two settings with care, as they might deteriorate the failsafe security of your aircraft.
=== Kill mode ===
In this mode the throttle is killed (this is the default mode when switching on the autopilot). You can enter this mode manually with the kill button (with confirmation). 
Kill mode is also triggered in the following cases:
* Catastrophic battery level
* Way too far from HOME
TODO: Complete the list. [MB]
==== Catastrophic battery level ====
If the battery level goes under the catastrophic low level (defined in the airframe file):
More about battery related settings can be found at Airframe_Configuration#Battery
==== Way too far from HOME ====
The plane goes into kill mode if it is too far away from the HOME waypoint. You can configure this KILL_MODE_DISTANCE in your airframe file:
 <section name="MISC">
 ...
 <define name="KILL_MODE_DISTANCE" value="(1.5*MAX_DIST_FROM_HOME)"/>
 ...
 </section>
In this example it is set to 1.5 times the max_dist_from_home (attribute set in your flight plan).
=== GPS signal lost ===
In this mode, the autopilot uses the failsafe roll, pitch and throttle settings defined in the airframe file. It is recommended to disable throttle and make a shallow turn at low flight speed. When barometric information is available and compass heading information, it is recommended to disable this safety mode and train the GCS operator to bring the plane home on heading and altitude only. 
Do not mix up the <commands> failsafe_value and the <section name="FAILSAFE" prefix="FAILSAFE_"> default values. The first result in fixed servo positions with the plane totally out of control, while the latter still involve the innerloop to stabilize the plane. 
== Rotorcraft autopilot ==
=== Fail modes ===
==== Home mode (>= v5.1) ====
Similar to fixedwing. The airframe fly back to the HOME waypoint at the HOME wp altitude.
With <define name="UNLOCKED_HOME_MODE" value="TRUE"/> you can get out of HOME mode if you have valid RC and are not too_far_from_home, otherwise click on the GCS strip mode indicator.
==== Failsafe mode ====
Zero roll/pitch and current heading setpoint (so hover in attitude mode but not position controlled) and descent at FAILSAFE_DESCENT_SPEED (default now 1.5 m/s). If you define KILL_AS_FAILSAFE, it will go into KILL mode whenever it would normally trigger FAILSAFE.
==== Kill mode ====
Will just kill the motors, to be used as last resort.
=== Distance trigger ===
* if too_far_from_home (defined by circle around HOME with radius MAX_DIST_FROM_HOME), then go into HOME mode
* if you get really too far from HOME (FAILSAFE_MODE_DISTANCE with default 1.5 * MAX_DIST_FROM_HOME), then go into FAILSAFE_MODE_TOO_FAR_FROM_HOME (defaults to AP_MODE_FAILSAFE)
=== RC lost trigger ===
* if RC_REALLY_LOST in a RC mode (not KILL, HOME, FAILSAFE or NAV), go into RC_LOST_MODE (default is same as before: AP_MODE_FAILSAFE)
* nothing if in any of the other modes
=== GPS lost trigger (if USE_GPS) ===
* if in HOME mode, go into AP_MODE_FAILSAFE
* if in NAV and motors_on
** if NO_GPS_LOST_WITH_RC_VALID is defined and RC is ok, do nothing
** else go into AP_MODE_FAILSAFE
=== Battery voltage trigger ===
* if FAILSAFE_ON_BAT_CRITICAL is defined and electrical.bat_critical (voltage below CRITIC_BAT_LEVEL with default of 9.8V), go into AP_MODE_FAILSAFE
== Flight plan based configurable behavior ==
=== Lost datalink communication (optional) ===
This can be done via the a flight-plan exception, e.g. go to the Standby block after 30 seconds:
=== Outside mission boundary (optional) ===
Also use exceptions and/or function calls for this.
For an example see EMAV2009_safety.xml in the directory conf/flight_plans is an example of a safety procedure that can be included in other flight-plans.
It uses two sectors defined in EMAV2009_data.xml, a smaller Green "soft boundary" and a hard boundary defined by the Red sector.
<procedure>
 <exceptions>
 <exception cond="Or(! InsideGreen(GetPosX(), GetPosY()), GetPosAlt() > ground_alt + 150)" deroute="Center"/>
 </exceptions>
 <blocks>
 <block name="Center" pre_call="if (!InsideRed(GetPosX(), GetPosY())) NavKillThrottle();">
 <circle wp="_CENTER" radius="DEFAULT_CIRCLE_RADIUS"/>
 </block>
 </blocks>
</procedure>
The first exception deroutes the plane to the Center block below it, if it is outside the Green sector or higher than 150m over ground.
While in the Center block the statement in the pre_call function gets evaluated each time, if the plane is now also outside of the Red sector throttle is killed.
Category:Software Category:User_Documentation