PaparazziUAV - User contributions [en]

Airframe Configuration

2017-11-28T13:27:42Z

Tomvand: Mention flight plan modules section

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Airframe_Configuration</categorytree>

== About ==

The airframe file is the most important configuration file and contains all the hardware and software settings for your airframe. It describes what hardware you have and which firmware, sensors, algorithms, etc. you want to use and also holds your configuration parameters. All gains, trims, and behavior settings are defined with standard XML elements.

The XML airframe configuration file is located in <tt>conf/airframes/<yourairframe>.xml</tt> and always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line and should look like this
{{Box Code|conf/airframes/<yourairframe>.xml|<source lang="xml">
<!DOCTYPE airframe SYSTEM "airframe.dtd">
<airframe name="yourairframe">

</airframe>
</source>}}

Also see the wiki pages for [[Fixedwing_Configuration|fixedwing specific configuration]] and [[Rotorcraft_Configuration|rotorcraft specific configuration]].

== Creating a new Aircraft ==

While the airframe file is where you configure most aspects of your aircraft, a fully specified aircraft needs several XML configuration files:
* Airframe (what this page is about)
* [[Flight_Plans|Flight Plan]]
* [[Settings]]
* [[Radio_Control|Radio]] (if you use a PPM based R/C system)
* [[Telemetry]]
* [[settings_modules]]
Each aircraft is assigned a name, unique ID and the associated configuration files in [[Conf.xml|<tt>conf/conf.xml</tt>]]. To create a new Aircraft, click new in the menu A/C in the [[Paparazzi_Center|Paparazzi Center]] and select your new airframe file, etc. (or specify it by hand in [[Conf.xml|<tt>conf/conf.xml</tt>]]).

== Firmware and Hardware definitions ==
First you should specify which firmware you want to use, that is if you have a <tt>[[Fixedwing_Configuration|fixedwing]]</tt> aircraft or a <tt>[[Rotorcraft_Configuration|rotorcraft]]</tt>:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
</firmware>
</source>
}}

=== Select your Board ===

To specify autopilot hardware you are using and it's low-level settings you have to add a ''target''-tag.
Each ''target'' has two attributes, which are ''name'' and a corresponding ''board'' attribute.
The ''name'' attribute is either "ap" (autopilot) or "sim/jsbsim/nps" (simulation).

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
<target name="sim" board="pc"/> 
<target name="ap" board="lisa_m_1.0"/> 
...
</firmware>
</source>
}}

==== Simulation targets ====

target name="sim","jsbsim","nps" 
board="pc" 

More Information at [[Simulation]].

==== Board targets ====

target name="ap" 
board=
"apogee_0.99",
"apogee_1.0",
"ardrone2",
"booz_1.0",
"classix",
"hb_1.1",
"krooz_sd",
"lisa_l_1.0",
"lisa_l_1.1",
"lisa_m_1.0",
"lisa_m_2.0",
"lisa_mx_2.0",
"lisa_s_0.1",
"logom_2.6",
"navgo_1.0",
"sdlog_1.0",
"stm32f4_discovery",
"tiny_0.99",
"tiny_1.1",
"tiny_2.1",
"tiny_2.11",
"twog_1.0",
"umarim_1.0",
"umarim_lite_2.0",
"yapa_2.0",

All targets can be found in /conf/boards.

==== Direct Makefile ====

Optionally you can also add a raw [http://en.wikipedia.org/wiki/Makefile Makefile] section. This is only needed in very advanced setups. For example when testing newly developed hardware.

=== LEDs ===

You can configure the LEDs on the autopilot to be used for different status indicators:
; ''SYS_TIME_LED'': blinks with 1Hz
; ''AHRS_ALIGNER_LED'': blinks until the AHRS is aligned (gyro bias initialized) and then stays on
; ''GPS_LED'': blinking if trying to get a fix, on if 3D fix
; ''RADIO_CONTROL_LED'': on if RC signal is ok
; ''BARO_LED'' : only on booz and navgo boards: blinks until baro offset is initialized and then stays on

Depending on your board some of the LEDs on it are already assigned to some indicators by default, check the appropriate autopilot board makefile for the defaults.

To reconfigure the default assignment, assign the indicator to an other value. Use ''none'' if indicator should not be assigned to any LED.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<configure name="SYS_TIME_LED" value="1"/>
<configure name="RADIO_CONTROL_LED" value="2"/>
<configure name="GPS_LED" value="none"/>
</firmware>
</source>
}}

Beware that you can only assign '''one''' indicator to a LED number. So if the LED you want to use is already in use because another indicator is set to that number by default you have to disable that other indicator by setting it to ''none'' or reconfigure it to an other LED.

== Subsystems ==
{| class="wikitable"
|-
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. The roadmap of Paparazzi is to convert existing subsystems to [[modules]].
|}
Each autopilot features certain [[Subsystems|subsystems]] which need to be configured properly.
The most important ones are described below.

=== IMU ===

Add the [[Subsystem/imu|imu subsystem]] with the type you are using.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="imu" type="aspirin_v1.5"/>
</firmware>
</source>
}}

See the [[Subsystem/imu|imu subsystem]] page for more details.
Also see the [[ImuCalibration|IMU calibration]] page.

=== AHRS ===

The [[Subsystem/ahrs|AHRS subsystem]] specifies which attitude estimation filter you are using, e.g. for the complementary filter:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="ahrs" type="int_cmpl_euler"/>
</firmware>
</source>
}}
All AHRS algorithms depend on an imu subsystem, except for the ahrs_infrared which depends on the infrared module.
See the [[Subsystem/ahrs|AHRS subsystem page]] for more details.

If the magnetometer should be used the [[Subsystem/ahrs#Local_Magnetic_Field|local magnetic field section]] must be filled in.

=== Radio Control ===

Supported types are:
* ''ppm''
* ''spektrum''
* ''datalink''

Just specify the appropriate [[Subsystem/radio_control|radio control subsystem]] in your firmware section, e.g.:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="radio_control" type="ppm"/>
</firmware>
</source>
}}

=== Telemetry (Modem) ===

The modem protocol and baud rate must be set in both the airframe file and ground station. Any standard baud rate can be used, with 9600 being adequate and 57600 recommended for most users to allow high speed telemetry for more detailed flight data analysis. The actual data rate is determined by the number of messages being sent and the period of each message as defined in your [[Telemetry|telemetry file]], e.g. <tt>conf/telemetry/default.xml</tt>. Those wishing to experiment with "alternative" modems can reduce the number and period of each telemetry message to fit within most any bandwidth constraint.

The [[Subsystem/telemetry|telemetry subsystem]] supports the following modem protocols:
* Standard transparent serial (pprz) - this is compatible with all modems and can be used to connect the autopilot directly to a PC for testing without a modem.
* Maxstream API protocol (xbee) - compatible with all Maxstream modems including the 9XTend and Zigbee. This protocol enables hardware addressing, allowing multiple aircraft to be managed from a single ground modem.

Just specify the appropriate [[Subsystem/telemetry|telemetry subsystem]] in your firmware section. You can currently choose between the types ''transparent'', ''transparent_usb'' and ''xbee_api''.

'''The default baudrate is 57600 baud, see the [[Subsystem/telemetry|telemetry subsystem]] page for more details and configuration options.'''
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="telemetry" type="transparent"/>
</firmware>
</source>
}}

=== GPS ===

The serial port settings must match that of the GPS and are configured here along with the necessary files to interpret the u-blox UBX binary protocol:

Just specify the appropriate [[Subsystem/gps|gps subsystem]] in your firmware section. You can currently choose between the types '''ublox''' and '''ublox_utm''' for the older series 4 modules which still provide a UTM message.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="gps" type="ublox"/>
</firmware>
</source>
}}

The correct UART is already defined by default according to your board.
The default GPS baudrate is 38400baud.

If you need to set different baud rates or UART see the [[Subsystem/gps]] page for the options.

'''Note:'''
* u-blox GPS modules are factory configured for 9600 baud, 38,400 baud is recommended along with the other required changes. The GPS can be accessed directly through the [[tunnel|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center|Configured with u-center]]

== XML Parameters ==

'''When defining parameters you can use [[Units|automatic unit conversion]] to conveniently set it in e.g. degrees.'''

=== Commands ===

The <tt>commands</tt> lists the abstract commands you need to control the aircraft. In a simple fixed-wing example, we have only three:
<source lang="xml">
<commands>
<axis name="THROTTLE" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="PITCH" failsafe_value="0"/>
</commands>
</source>
For rotorcraft, it is usually:
<source lang="xml">
<commands>
<axis name="PITCH" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="YAW" failsafe_value="0"/>
<axis name="THRUST" failsafe_value="0"/>
</commands>
</source>

Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board. The range of these values is [-9600:9600]. For <tt>"THROTTLE"</tt>, the range is [0, 9600] and in the corresponding <tt>servo</tt> definition the <tt>neutral</tt> and <tt>min</tt> are usually the same for PWM based servos (see below). Note that these commands do not necessarily match the servo actuators. For example, the <tt>"ROLL"</tt> command is typically linked to two aileron actuators.

=== Servos ===

The above commands get translated to the <tt>servos</tt> here. In the example below we use two elevons and a motor. ([http://en.wikipedia.org/wiki/Elevon ''Elevons''] are surfaces used for both pitch and roll as on a flying wing.) These servos are listed in the <tt>servos</tt> section:
<source lang="xml">
<servos>
<servo name="THROTTLE" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="ELEVON_LEFTSIDE" no="1" min="2000" neutral="1500" max="1000"/>
<servo name="ELEVON_RIGHTSIDE" no="2" min="1000" neutral="1500" max="2000"/>
</servos>
</source>

Names are associated to the corresponding '''real physical connector''' to which a servo is connected '''on the autopilot board'''. For example no="2" means connector two on the board. Also the servo neutral value, total range and direction are defined. Min/max/neutral values are expressed in microseconds. The direction of travel can be reversed by exchanging min with max (as in <tt>"ELEVON_LEFTSIDE"</tt>, above). The ''standard'' travel for a hobby servo is 1000µs - 2000µs with a 1500µs neutral. Trim can be added by changing this neutral value. Absolute servo travel limits can be increased or reduced with the min/max values. The <tt>"THROTTLE"</tt> servo typically has the same value for the <tt>neutral</tt> and <tt>min</tt>.

The attribute <tt>driver</tt> for <tt>servos</tt> node tells which actuators' driver is associated to the listed servos. After the version '''v4.9_devel-164-gdb0d004''', multiple servos sections can be defined and used together, if the correct [[Subsystem/actuators| actuators subsystems]] are loaded. Some boards are automatically loading a default driver, the one used when no <tt>driver</tt> attribute is specified.

Note the following important tips:
* Reverse the servo direction by exchanging min/max
* Trim should always be adjusted mechanically if possible to avoid asymmetrical travel
* Any reduction of the total travel range should be done mechanically to maintain precision
* Many servos will respond well to values slightly outside the normal 1000-2000µs range but experiment carefully as the servo may not operate reliably outside this range and may even suffer permanent damage.
* Board connector numbering starts with zero (0) not with one
* Servos are also known under the synonym actuators
* (after version '''v4.9_devel-164-gdb0d004''') For I2C based motor speed control using the [[Rotorcraft_Configuration#Motor_Mixing|motor mixing]]:
** min: command to stop the motor
** neutral: motor idle command
** max: max thrust command

The <tt>servos</tt> are then linked to the commands in the <tt>command_laws</tt> section:
<source lang="xml">
<command_laws>
<let var="aileron" value="@ROLL * 0.3"/>
<let var="elevator" value="@PITCH * 0.7"/>
<set servo="THROTTLE" value="@THROTTLE"/>
<set servo="ELEVON_LEFTSIDE" value="$elevator + $aileron"/>
<set servo="ELEVON_RIGHTSIDE" value="$elevator - $aileron"/>
</command_laws>
</source>

[[Image:airframe_sign_conventions.jpg|thumb|Sign conventions for flight dynamics]]
where the third line is the simplest: the throttle servo value equals throttle command value. The other lines define and control the pitch/roll mixing. Elevon values are computed with a combination of two commands, '''ROLL''' and '''PITCH'''. This ''mixer'' is defined with two intermediate variables '''aileron''' and '''elevator''' introduced with the <tt>let</tt> element. The '''@''' symbol is used to reference a command value in the <tt>value</tt> attribute of the <tt>set</tt> and <tt>let</tt> elements. In the above example, the servos are limited to +/- 70% of their full travel for pitch and 30% for roll, only in combination can the servos reach 100% deflection. Note that these numbers ''should add up 100% or more, never less''. For example, you may want 100% travel available for pitch - this means if a roll is commanded along with maximum pitch only one servo will respond to the roll command as the other has already reached its mechanical limit. If you find after tuning that these numbers add to less than 100% consider reducing the surface travel mechanically.

Note that the signs used in the description follow the standard convention.

After '''v4.9_devel-164-gdb0d004''', the <tt>command_laws</tt> section is mandatory for both fixedwing and rotorcraft firmwares, only for fixedwing otherwise.

=== Battery ===

This section gives characteristics for monitoring the main power battery.

<tt>MILLIAMP_AT_FULL_THROTTLE</tt> represents the actual current (in mA) when full THROTTLE is applied. Note that when flying the current typically is significantly lower than in static tests at home on your workbench. <tt>MILLIAMP_AT_FULL_THROTTLE</tt> is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message when no [[Current_sensor|Current sensor]] is mounted in the airframe. This value can also be used in flight plans. For example, if at full throttle your motor consumes 10 Amps, use a value of 10000. You can "tweak" this number after a few flights to match the capacity of your battery. If upon landing your bat.energy messages says that you used 2500 mAh while the energy recharged into the battery is only 2000 mAh, you could reduce the <tt>MILLIAMP_AT_FULL_THROTTLE</tt> value by 20% to match your in-flight current consumption. This tweaking is most precise if you fly full throttle only (respectively no throttle to glide down again).

The <tt>CURRENT_ESTIMATION_NONLINEARITY</tt> can be added to tweak the energy estimation for non full throttle cruise. As the current consumption is nonlinear, at 50% throttle it is likely to be substantially less than 50%. A superellipse is used to approximate this nonlinearity. The default setting is 1.2 and is used if the <tt>CURRENT_ESTIMATION_NONLINEARITY</tt> is not defined in your airframe file. A value 1 corresponds to linear behaviour, 1.5 corresponds to strong nonlinearity. The tweaking is done same as described above for <tt>MILLIAMP_AT_FULL_THROTTLE</tt>, but only partial throttle (cruise throttle) should be applied in flight.

If both <tt>MILLIAMP_AT_FULL_THROTTLE</tt> and <tt>CURRENT_ESTIMATION_NONLINEARITY</tt> are tweaked well, you get precise energy estimations with less than 5% error independent of your flight pattern without even requiring a [[Current_sensor|current sensor]].

The <tt>CATASTROPHIC_BAT_LEVEL</tt> (was previously <tt>LOW_BATTERY</tt>) value defines the voltage at which the autopilot will lock the throttle at 0% in autonomous mode (kill_throttle mode). This value is also used by the ground server to issue a '''CATASTROPHIC''' alarm message on the bus (this message will be displayed in the console of the GCS). <tt>CRITIC</tt> and <tt>LOW</tt> values will also used as threshold for '''CRITIC''' and '''WARNING''' alarms. They are optional and the respective defaults are 10.0 and 10.5V.

The <tt>MAX_BAT_LEVEL</tt> may be specified to improve the display of the battery gauge in the strip or in "papgets". Note that this definition is optional, with a default value of 12.5V.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
...
<define name="ADC_CHANNEL_VSUPPLY" value="ADC_4" />
</firmware>
...
<section name="BAT">
<define name="MILLIAMP_AT_FULL_THROTTLE" value="12000" unit="mA" />
<define name="CATASTROPHIC_BAT_LEVEL" value="6.0" unit="V"/>
<define name="CRITIC_BAT_LEVEL" value="6.5" unit="V"/>
<define name="LOW_BAT_LEVEL" value="7.0" unit="V"/>
<define name="MAX_BAT_LEVEL" value="8.4" unit="V"/>
</section>
</source>
}}

The conversion of ADC measurements to Voltage is already defined for the different autopilot boards, if you need to override these defaults you can use the <tt>VoltageOfAdc(adc)</tt> define and also specify offsets or anything else you might need, e.g.:

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="BAT">
...
<define name="VOLTAGE_ADC_SCALE" value="0.0177531"/>
<define name="VOLTAGE_OFFSET" value="0.5" unit="V"/>
<define name="VoltageOfAdc(adc)" value="(VOLTAGE_ADC_SCALE * adc + VOLTAGE_OFFSET)"/>
</section>
</source>
}}

Calculating '''VOLTAGE_ADC_SCALE''':

<math>VOLTAGE\_ADC\_SCALE=\frac{Vref}{ADCresolution-1}\div\frac{R2}{R1+R2}</math>

*Vref - Voltage reference for the ADC (will be 3.3V in most cases, can be found in mcu/adc datasheet)
*ADCresolution - ADC bit depth (e.g. 2^12=4096 for a 12 bit ADC)
*R1 - Resistor between battery and ADC input pin of MCU
*R2 - Resistor between ADC input pin of the MCU and GND

It is also a good idea to measure the actual voltage of the battery with a precision voltage meter, compare it with the calculated value from the autopilot (e.g. via [[Paparazzi_Center#Messages]]) and edit the vales for ADC scaling. Since the resistors have a tolerance, this can fine tune the measurement.

=== Modules ===

The [[Modules|modules]] allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.

<source lang="xml">
<modules main_freq="60">
<load name="demo_module.xml"/>
</modules>
</source>

* The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz

{| class="wikitable"
|-
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. It is therefore also possible to use the modules the same way subsystems used to be (i.e. as children of the ''firmware'' node and not only the ''modules'' node as presented above. The roadmap of Paparazzi is to convert existing subsystems to [[modules]].
|}

{| class="wikitable"
|-
| Starting from '''v5.12''' the ''modules'' element will gradually be phased out. Instead, the modules should be added inside the ''firmware'' tags of the airframe file:
|}
<source lang="xml>
<firmware name="fixedwing or rotorcraft">
...
<module name="demo_module"/>
</firmware>
</source>

Additional modules can also be added from the [[Flight Plans#Modules|flight plan]].

=== GCS ===

[[Image:ac_icon_multi_uav.png|thumb|Various A/C icons demonstrated on a multi UAV simulation session]]

[[Image:Icons_Theme_Default.png|thumb|Default Theme]]

[[Image:Icons_Theme_Flat.png|thumb|Flat Theme]]

Use this optional section to help customize parts of the GCS for a specific airframe:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="GCS">
...
<define name="ICONS_THEME" value="flat_theme"/>
<define name="ALT_SHIFT_PLUS_PLUS" value="30"/>
<define name="ALT_SHIFT_PLUS" value="5"/>
<define name="ALT_SHIFT_MINUS" value="-5"/>
<define name="SPEECH_NAME" value="Quad"/>
<define name="AC_ICON" value="flyingwing"/>
</section>
</source>
}}

* <tt>ICONS_THEME</tt> can be used to define an alternate/custom GCS icons theme for a given aircraft The '''flat_theme''' is one example of an alternate set of GCS icons.
* <tt>ALT_SHIFT_PLUS_PLUS</tt> sets the number of metres the target altitude will change when the double up arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>ALT_SHIFT_PLUS</tt> sets the number of metres the target altitude will change when the up arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>ALT_SHIFT_MINUS</tt> sets the number of metres the target altitude will change when the down arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>SPEECH_NAME</tt> a string ([a-zA-Z0-9_]) that will be used in place of the aircraft name specified in <tt>conf.xml</tt> for the [[Speech|speech]] and [[GCS#Alarms|alarms]] functionality. Set this to "_" to prevent the speech function from saying the aircraft name. Useful if your aircraft name takes a long time to say (i.e. "UAV1-A_with_spektrum" can be shortened to "Plane").
* <tt>AC_ICON</tt> can be used to define the vehicle icon (or overwrite the default icon) that shows up on the 2D-map of the GCS. Available values are: <tt>flyingwing</tt> , <tt>fixedwing</tt> , <tt>rotorcraft</tt> , <tt>quadrotor</tt> , <tt>hexarotor</tt> , <tt>octorotor</tt> , <tt>quadrotor_x</tt> , <tt>hexarotor_x</tt> , <tt>octorotor_x</tt> , <tt>home</tt>.

==== Custom Icons Theme Support ====

A custom icons theme is supported through the use of the '''ICONS_THEME''' attribute. Set the '''ICONS_THEME''' attribute ''value'' to the path of your custom icons theme directory and the given aircraft will now display your custom icons. Note that the path is relative to the default GCS icons path root: ''$PAPARAZZI_HOME/data/pictures/gcs_icons''

{{Box Code|code snippet|
<source lang="xml">
<section name="GCS">
<define name="ICONS_THEME" value="myawesome_icons"/>
</section>
</source>
}}

The directory that contains your custom icons, in this example named ''myawesome_icons'', is located at ''$PAPARAZZI_HOME/data/pictures/gcs_icons''.

[[Category:User_Documentation]] [[Category:Airframe_Configuration]]

Flight Plans

2017-11-28T10:46:59Z

Tomvand: Fix typo

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line: 

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,variables?,includes?,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.
* A waypoints index/reference pointer is derived by prefixing the waypoint name with "WP_". Useful when a [[#Call |call function]] uses the waypoints reference index vs. it's name.

== Sectors ==

=== Static sectors (default) ===

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is convex and described in a clockwise order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

=== Dynamic sectors ===

With the latest version (v5.5-devel-628), it is possible to create dynamic sectors. The procedure to create the sector is the same than for the static version with an extra attribute '''type="dynamic"''':
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red" type="dynamic">
<corner name="C1"/>
<corner name="C2"/>
<corner name="C3"/>
<corner name="C4"/>
</sector>
</sectors>
</source>

It is also recommended to avoid using hidden waypoints (no _ prefix), so you can move the corner of your sector from the GCS. The polygon is updated on the 2D map to reflect the new waypoints positions.
Beside the possibility to change the shape of the area in flight, one of the main benefit is that the algorithm behind allows concave hulls. The only restriction is that the edges of the polygon should not cross each other.

The generated function is the same than the static version and can be used the same way.

== Variables ==

'''Available since v5.9'''

It is possible to declare a list of variables that will be automatically created during the flight plan generation and available for the rest of the system from the generated flight plan header and of course inside the flight plan itself. With appropriate attributes, it is also possible to make the variables accessible from the telemetry as a [[Settings|setting]].

The following code will produce a '''float''' variable initialized to 0:
<source lang="xml">
<variables>
<variable var="my_var"/>
</variables>
</source>

The type and the initial value can be changed with the '''type''' and '''init''' attributes:
<source lang="xml">
<variables>
<variable var="my_var" init="10" type="int"/>
</variables>
</source>

To produce an automatic setting for a variable, at least '''min''', '''max''' and '''step''' attributes need to be specified:
<source lang="xml">
<variables>
<variable var="my_var" min="0." max="10." step="0.1"/>
</variables>
</source>
They will appear under the '''Flight Plan''' settings tab in the GCS. So more attributes can be specified: '''shortname''', '''unit''', '''alt_unit''', '''alt_unit_coef''', '''values'''. See [[Settings]] page for more information about these options.

== Modules ==
Additional modules can be added to the airframe using the ''modules'' element inside the flight plan. The same syntax is used as in the airframe file:

<source lang="xml">
<modules>
<module name="demo_module">
<define name="MY_DEFINE" value="0"/>
<configure name="MY_CONF" value="0"/>
...
</module>
</modules>
</source>

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see [[Flight_Plans#Internal_Variables_in_Flight_Plans|internal variables section]] below and other examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learning to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Return ===

The <tt>return</tt> is also a ''goto'' directive that brings you back to the last block (and last stage). It has no argument.
<source lang="xml"><return/></source>

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, letting the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at an altitude above ground of 50m (1x50), 10 seconds at an altitude of 100m (2x50), ... until 250m (5x50).

Note: Two bounded loops using the same control variable are not allowed in the same block. Further, I tested a specific implementation installation of PaparazziUAV v5.10 and I found the maximum range of the looping variable to be -128 to 126.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point where XY moveable with the RC transmitter stick, Z with other stick or slider

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
'''Works only for Fixed-wing!''' Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Survey rectangle ===
Fly a survey rectangle defined by two waypoints. The distance between the legs of the grid (in meter) and the orientation of the grid (NS or WE) can be set by the operator. The plane will turn outside of the border of the rectangle before starting a new leg.
<source lang="xml"> <survey_rectangle wp1="1" wp2="2" grid="200" orientation="NS"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>

=== Stay ===

The <tt>stay</tt> Here the UAS with try to stay at the waypoint as best as it can. For an aircraft capable of hovering it will just hang above the waypoint. If the UAV has no hover capabilities,<tt>stay</tt> will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== Abide ===

The <tt>abide</tt> Here the UAS with try to abide at the waypoint as best as it can. For an aircraft capable only capable of hovering it will just hang above the waypoint. For a fixedwing or a Hybrid type UAV,<tt>stay</tt> will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.
<source lang="xml"><abide wp="SAMPLEME" alt="95"/></source>

''Note that you current Paparazzi version might not have this option yet.'', use stay as an alternative

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_setup()"/>
<call fun="nav_line_run(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_setup()</tt> returns FALSE and <tt>nav_line_run()</tt> always returns TRUE (this stage never ends). '''Note''' that a waypoints index is derived/denoted by prefixing the waypoint name with <tt>WP_</tt>(i.e.: 1 --> WP_1, 2 --> WP_2)
 

To call ''any'' function exactly once regardless of the return value (e.g. call a void function), add <tt>loop="FALSE"</tt>
<source lang="xml">
<call fun="viewvideo_take_shot(TRUE)" loop="FALSE"/>
</source>
or use the <tt>call_once</tt> alias:
<source lang="xml">
<call_once fun="viewvideo_take_shot(TRUE)"/>
</source>

Such extra navigation functions are usually written as a [[Modules|Module]] and the header files are included automatically.

If you want to call functions that are not part of a module, you need to include the header file which contains the function declaration:or supplementary C file which must be specified in the
<source lang="xml">
<header>
#include "path/to/header.h"
</header>
</source>
where the path is relative to the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continuously on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

=== Pre Call ===

<source lang="xml">
<block name="Standby" strip_button="Standby" strip_icon="home.png" pre_call="if(!InsideKill(GetPosX(), GetPosY())) NavKillThrottle();">
</source>

=== Post Call ===

<source lang="xml">
<block name="traj" pre_call="formation_pre_call()" post_call="formation_flight()"> 
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Internal Variables in Flight Plans ==

The flight plan can use several internal variables, macros and functions coming from the rest of the system or the flight plan API itself. The following list present some of the most commonly used variables, but much more are actually available:

* '''autopilot_flight_time''': time in seconds since autopilot was booted (integer)
* '''datalink_time''': time in seconds since last connection of telemetry to ground control station (including ''subsystems/datalink/datallink.h'' in the '''header''' section is required) (integer)
* '''GetPosAlt()''': returns the current altitude above ground level in meter (float)
* '''GetPosX()''': returns x (easting) of current position relative to reference in meter (float)
* '''GetPosY()''': returns y (northing) of current position relative to reference in meter (float)
* <s>'''ground_alt''': altitude above ground level in meter (float)</s> (v5.8 and higher - use '''GetAltRef()''' instead)
* '''GetAltRef()''': returns reference altitude, usually ground_alt
* '''NavSetGroundReferenceHere()''': reset position and altitude reference point to current position
* '''NavSetAltitudeReferenceHere()''': reset altitude reference to current alt but keep previous horizontal position reference
* '''NavSetWaypointHere(_wp)''': set position of a waypoint given as argument to the current position
* '''WaypointX(_wp)''': returns x (easting) of waypoint position relative to reference in meter (float)
* '''WaypointY(_wp)''': returns y (northing) of waypoint position relative to reference in meter (float)
* '''WaypointAlt(_wp)''': returns waypoint altitude in meter (float)
* '''nav_radius''': free variable usually used to set circle radius in flight plan
* '''NavKillThrottle()''': function to switch off throttle
* '''PowerVoltage()''': returns current voltage of the battery
* all functions from the [http://docs.paparazziuav.org/latest/group__state__interface.html state interface API]
* all functions from the [http://docs.paparazziuav.org/latest/subsystems_2navigation_2waypoints_8h.html waypoint API]
* all variables declared in [[modules]] headers

== Advanced Examples ==

Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

Below you find some random examples of the posibilities. This is only the tip of the iceberg, use your imagination and go wild with new creative ideas for your flightplan

=== Gains on the fly ===

It is very well possible to set specific gain for an airframe if it reaches e.g a certain block.

=== Dynacmically adjustable maximum speed ===

<source lang="xml">
<call_once fun="gh_set_max_speed(2.0)"/>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the h_ctl_disabled flag:

<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

=== V5.8+ ===
* If you don't like the '''No SRTM data found to check altitude''' warning, either in your flight plan editor or in GCS itself click on the '''Nav->display SRTM'''. It will ask you whether you want to download SRTM data. Say yes, and it will save the data in ''data/srtm'' directory, so you don't get the warning any more and check the ground altitude even without GPS.

[[Category:Software]] [[Category:User_Documentation]]

Flight Plans

2017-11-28T10:46:19Z

Tomvand: Add modules section

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line: 

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans via the GUI.

Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,variables?,includes?,exceptions?,blocks)></tt>

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

<source lang="xml">
<flight_plan alt="250" ground_alt="185" lat0="43.46223" lon0="1.27289" name="Example Muret" max_dist_from_home="300" qfu="270" security_height="25" >
</source>

Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.
* A waypoints index/reference pointer is derived by prefixing the waypoint name with "WP_". Useful when a [[#Call |call function]] uses the waypoints reference index vs. it's name.

== Sectors ==

=== Static sectors (default) ===

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is convex and described in a clockwise order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

For example, with the following element in a flight plan.
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</source>

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

=== Dynamic sectors ===

With the latest version (v5.5-devel-628), it is possible to create dynamic sectors. The procedure to create the sector is the same than for the static version with an extra attribute '''type="dynamic"''':
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red" type="dynamic">
<corner name="C1"/>
<corner name="C2"/>
<corner name="C3"/>
<corner name="C4"/>
</sector>
</sectors>
</source>

It is also recommended to avoid using hidden waypoints (no _ prefix), so you can move the corner of your sector from the GCS. The polygon is updated on the 2D map to reflect the new waypoints positions.
Beside the possibility to change the shape of the area in flight, one of the main benefit is that the algorithm behind allows concave hulls. The only restriction is that the edges of the polygon should not cross each other.

The generated function is the same than the static version and can be used the same way.

== Variables ==

'''Available since v5.9'''

It is possible to declare a list of variables that will be automatically created during the flight plan generation and available for the rest of the system from the generated flight plan header and of course inside the flight plan itself. With appropriate attributes, it is also possible to make the variables accessible from the telemetry as a [[Settings|setting]].

The following code will produce a '''float''' variable initialized to 0:
<source lang="xml">
<variables>
<variable var="my_var"/>
</variables>
</source>

The type and the initial value can be changed with the '''type''' and '''init''' attributes:
<source lang="xml">
<variables>
<variable var="my_var" init="10" type="int"/>
</variables>
</source>

To produce an automatic setting for a variable, at least '''min''', '''max''' and '''step''' attributes need to be specified:
<source lang="xml">
<variables>
<variable var="my_var" min="0." max="10." step="0.1"/>
</variables>
</source>
They will appear under the '''Flight Plan''' settings tab in the GCS. So more attributes can be specified: '''shortname''', '''unit''', '''alt_unit''', '''alt_unit_coef''', '''values'''. See [[Settings]] page for more information about these options.

== Modules ==
Additional modules can be added to the airframe using the ''modules'' element. The same syntax is used as in the aiframe file:

<source lang="xml">
<modules>
<module name="demo_module">
<define name="MY_DEFINE" value="0"/>
<configure name="MY_CONF" value="0"/>
...
</module>
</modules>
</source>

== Includes ==

<tt>include</tt> is used to add some flight plan elements defined in an external procedure. It’s useful to include pre-written procedures with only few arguments and then clarify the flight plan.
Here is the structure:
<tt><include name procedure> [<arg name value />]*[<with from to />]*</include></tt>
where <tt>name</tt> attribute of the include element will be used in this flight plan to prefix the blocks of the <tt>procedure</tt>, the XML referenced file.
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels (e.g. attribute of a deroute instruction or of an exception) from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<source lang="xml">
<includes>
<include name="landing" procedure="landing.xml"/>
</includes>
</source>

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

In the same way, a key shortcut can be specified:
<source lang="xml">
<block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
Modifiers are allowed, using the syntax of [http://library.gnome.org/devel/gtk/2.15/gtk-Keyboard-Accelerators.html#gtk-accelerator-parse GTK accelerators].

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<source lang="xml"><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></source>

You can call functions before or after each execution of the block:
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

==== Expressions ====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see [[Flight_Plans#Internal_Variables_in_Flight_Plans|internal variables section]] below and other examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learning to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== Exceptions ===

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<source lang="xml"><exception cond="..." deroute="..."></source>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<source lang="xml">
<flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...
</source>

=== Deroute ===

The <tt>deroute</tt> is the ''goto'' directive of the flight plan; it switches the navigation to the given block:
<source lang="xml"><deroute block="landing"/></source>

Note that this primitive should not be used to execute loops which are provided by the following elements.

=== Return ===

The <tt>return</tt> is also a ''goto'' directive that brings you back to the last block (and last stage). It has no argument.
<source lang="xml"><return/></source>

=== Loops ===

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, letting the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at an altitude above ground of 50m (1x50), 10 seconds at an altitude of 100m (2x50), ... until 250m (5x50).

Note: Two bounded loops using the same control variable are not allowed in the same block. Further, I tested a specific implementation installation of PaparazziUAV v5.10 and I found the maximum range of the looping variable to be -128 to 126.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point where XY moveable with the RC transmitter stick, Z with other stick or slider

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

=== Attitude ===

Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

To fly around, holding a given altitude:
<source lang="xml"><attitude roll="30" alt="ground_alt+50"/></source>

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

=== Heading ===

<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up (15 degrees) until height of 30m is reached:
<source lang="xml"><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(GetPosAlt() > ground_alt+30)"/></source>

=== Go ===

The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<source lang="xml"><go wp="HOME"/></source>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route"/></source>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<source lang="xml"><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></source>

The attributes related to the vertical control can also be set to replace the default altitude mode:
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/></source>

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<source lang="xml"><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></source>

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

Other attributes are optional:
<source lang="xml"><path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/></source>

=== Circle ===

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<source lang="xml"><circle wp="HOME" radius="75"/></source>
A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The <tt>until</tt> attribute may be used to control the end of the stage. The following example defines an ascending trajectory at constant throttle, nose up (15 degrees), over growing circles, until the battery level is low:
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
'''Works only for Fixed-wing!''' Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Survey rectangle ===
Fly a survey rectangle defined by two waypoints. The distance between the legs of the grid (in meter) and the orientation of the grid (NS or WE) can be set by the operator. The plane will turn outside of the border of the rectangle before starting a new leg.
<source lang="xml"> <survey_rectangle wp1="1" wp2="2" grid="200" orientation="NS"/> </source>

=== Follow ===

The <tt>follow</tt> is a special primitive which makes the UAS follow another UAS (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>

=== Stay ===

The <tt>stay</tt> Here the UAS with try to stay at the waypoint as best as it can. For an aircraft capable of hovering it will just hang above the waypoint. If the UAV has no hover capabilities,<tt>stay</tt> will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.
<source lang="xml"><stay wp="HOME" alt="10"/></source>

=== Abide ===

The <tt>abide</tt> Here the UAS with try to abide at the waypoint as best as it can. For an aircraft capable only capable of hovering it will just hang above the waypoint. For a fixedwing or a Hybrid type UAV,<tt>stay</tt> will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.
<source lang="xml"><abide wp="SAMPLEME" alt="95"/></source>

''Note that you current Paparazzi version might not have this option yet.'', use stay as an alternative

=== XYZ ===

<tt>xyz</tt> is a special mode where the UAS circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<source lang="xml"><xyz radius="40"/></source>

=== Set ===

The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
This directive is extremely powerful and has great potential for error - use with caution.

=== Call ===

The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<call fun="nav_line_setup()"/>
<call fun="nav_line_run(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_setup()</tt> returns FALSE and <tt>nav_line_run()</tt> always returns TRUE (this stage never ends). '''Note''' that a waypoints index is derived/denoted by prefixing the waypoint name with <tt>WP_</tt>(i.e.: 1 --> WP_1, 2 --> WP_2)
 

To call ''any'' function exactly once regardless of the return value (e.g. call a void function), add <tt>loop="FALSE"</tt>
<source lang="xml">
<call fun="viewvideo_take_shot(TRUE)" loop="FALSE"/>
</source>
or use the <tt>call_once</tt> alias:
<source lang="xml">
<call_once fun="viewvideo_take_shot(TRUE)"/>
</source>

Such extra navigation functions are usually written as a [[Modules|Module]] and the header files are included automatically.

If you want to call functions that are not part of a module, you need to include the header file which contains the function declaration:or supplementary C file which must be specified in the
<source lang="xml">
<header>
#include "path/to/header.h"
</header>
</source>
where the path is relative to the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continuously on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

=== Pre Call ===

<source lang="xml">
<block name="Standby" strip_button="Standby" strip_icon="home.png" pre_call="if(!InsideKill(GetPosX(), GetPosY())) NavKillThrottle();">
</source>

=== Post Call ===

<source lang="xml">
<block name="traj" pre_call="formation_pre_call()" post_call="formation_flight()"> 
</source>

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints, sectors and blocks. The header of a procedure may contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, ...:
<source lang="xml"><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></source>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<source lang="xml">
<param name="alt"/>
<param name="radius" default_value="75"/>
</source>

Procedures are called with the <tt>include</tt> element in a flight plan. A procedure cannot be included twice or by another procedure. A procedure call requires:

* the name of the procedure file, the name given to this inclusion;
* values for the parameters;
* backlinks for block name exits of the procedure.

For example:
<source lang="xml"><include name="landing" procedure="landing.xml"/></source>

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

Note that the name of procedure '''land''' block will be renamed into '''landing.land''':
<source lang="xml"><deroute block="landing.land"/></source>
will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it
<source lang="xml"><exception cond="..." deroute="go-around"/></source>
then you must link this block exit with one of your block (e.g. <tt>Standby</tt>). So you would include the procedure as follows:
<source lang="xml">
<include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include>
</source>

== Internal Variables in Flight Plans ==

The flight plan can use several internal variables, macros and functions coming from the rest of the system or the flight plan API itself. The following list present some of the most commonly used variables, but much more are actually available:

* '''autopilot_flight_time''': time in seconds since autopilot was booted (integer)
* '''datalink_time''': time in seconds since last connection of telemetry to ground control station (including ''subsystems/datalink/datallink.h'' in the '''header''' section is required) (integer)
* '''GetPosAlt()''': returns the current altitude above ground level in meter (float)
* '''GetPosX()''': returns x (easting) of current position relative to reference in meter (float)
* '''GetPosY()''': returns y (northing) of current position relative to reference in meter (float)
* <s>'''ground_alt''': altitude above ground level in meter (float)</s> (v5.8 and higher - use '''GetAltRef()''' instead)
* '''GetAltRef()''': returns reference altitude, usually ground_alt
* '''NavSetGroundReferenceHere()''': reset position and altitude reference point to current position
* '''NavSetAltitudeReferenceHere()''': reset altitude reference to current alt but keep previous horizontal position reference
* '''NavSetWaypointHere(_wp)''': set position of a waypoint given as argument to the current position
* '''WaypointX(_wp)''': returns x (easting) of waypoint position relative to reference in meter (float)
* '''WaypointY(_wp)''': returns y (northing) of waypoint position relative to reference in meter (float)
* '''WaypointAlt(_wp)''': returns waypoint altitude in meter (float)
* '''nav_radius''': free variable usually used to set circle radius in flight plan
* '''NavKillThrottle()''': function to switch off throttle
* '''PowerVoltage()''': returns current voltage of the battery
* all functions from the [http://docs.paparazziuav.org/latest/group__state__interface.html state interface API]
* all functions from the [http://docs.paparazziuav.org/latest/subsystems_2navigation_2waypoints_8h.html waypoint API]
* all variables declared in [[modules]] headers

== Advanced Examples ==

Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

Below you find some random examples of the posibilities. This is only the tip of the iceberg, use your imagination and go wild with new creative ideas for your flightplan

=== Gains on the fly ===

It is very well possible to set specific gain for an airframe if it reaches e.g a certain block.

=== Dynacmically adjustable maximum speed ===

<source lang="xml">
<call_once fun="gh_set_max_speed(2.0)"/>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the h_ctl_disabled flag:

<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

=== V5.8+ ===
* If you don't like the '''No SRTM data found to check altitude''' warning, either in your flight plan editor or in GCS itself click on the '''Nav->display SRTM'''. It will ask you whether you want to download SRTM data. Say yes, and it will save the data in ''data/srtm'' directory, so you don't get the warning any more and check the ground altitude even without GPS.

[[Category:Software]] [[Category:User_Documentation]]

Airframe Configuration

2017-11-28T10:33:59Z

Tomvand: Fix xml examples to use module instead of subsystem. Update modules description to state that these should be placed inside the firmware tags.

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Airframe_Configuration</categorytree>

== About ==

The airframe file is the most important configuration file and contains all the hardware and software settings for your airframe. It describes what hardware you have and which firmware, sensors, algorithms, etc. you want to use and also holds your configuration parameters. All gains, trims, and behavior settings are defined with standard XML elements.

The XML airframe configuration file is located in <tt>conf/airframes/<yourairframe>.xml</tt> and always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line and should look like this
{{Box Code|conf/airframes/<yourairframe>.xml|<source lang="xml">
<!DOCTYPE airframe SYSTEM "airframe.dtd">
<airframe name="yourairframe">

</airframe>
</source>}}

Also see the wiki pages for [[Fixedwing_Configuration|fixedwing specific configuration]] and [[Rotorcraft_Configuration|rotorcraft specific configuration]].

== Creating a new Aircraft ==

While the airframe file is where you configure most aspects of your aircraft, a fully specified aircraft needs several XML configuration files:
* Airframe (what this page is about)
* [[Flight_Plans|Flight Plan]]
* [[Settings]]
* [[Radio_Control|Radio]] (if you use a PPM based R/C system)
* [[Telemetry]]
* [[settings_modules]]
Each aircraft is assigned a name, unique ID and the associated configuration files in [[Conf.xml|<tt>conf/conf.xml</tt>]]. To create a new Aircraft, click new in the menu A/C in the [[Paparazzi_Center|Paparazzi Center]] and select your new airframe file, etc. (or specify it by hand in [[Conf.xml|<tt>conf/conf.xml</tt>]]).

== Firmware and Hardware definitions ==
First you should specify which firmware you want to use, that is if you have a <tt>[[Fixedwing_Configuration|fixedwing]]</tt> aircraft or a <tt>[[Rotorcraft_Configuration|rotorcraft]]</tt>:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
</firmware>
</source>
}}

=== Select your Board ===

To specify autopilot hardware you are using and it's low-level settings you have to add a ''target''-tag.
Each ''target'' has two attributes, which are ''name'' and a corresponding ''board'' attribute.
The ''name'' attribute is either "ap" (autopilot) or "sim/jsbsim/nps" (simulation).

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
<target name="sim" board="pc"/> 
<target name="ap" board="lisa_m_1.0"/> 
...
</firmware>
</source>
}}

==== Simulation targets ====

target name="sim","jsbsim","nps" 
board="pc" 

More Information at [[Simulation]].

==== Board targets ====

target name="ap" 
board=
"apogee_0.99",
"apogee_1.0",
"ardrone2",
"booz_1.0",
"classix",
"hb_1.1",
"krooz_sd",
"lisa_l_1.0",
"lisa_l_1.1",
"lisa_m_1.0",
"lisa_m_2.0",
"lisa_mx_2.0",
"lisa_s_0.1",
"logom_2.6",
"navgo_1.0",
"sdlog_1.0",
"stm32f4_discovery",
"tiny_0.99",
"tiny_1.1",
"tiny_2.1",
"tiny_2.11",
"twog_1.0",
"umarim_1.0",
"umarim_lite_2.0",
"yapa_2.0",

All targets can be found in /conf/boards.

==== Direct Makefile ====

Optionally you can also add a raw [http://en.wikipedia.org/wiki/Makefile Makefile] section. This is only needed in very advanced setups. For example when testing newly developed hardware.

=== LEDs ===

You can configure the LEDs on the autopilot to be used for different status indicators:
; ''SYS_TIME_LED'': blinks with 1Hz
; ''AHRS_ALIGNER_LED'': blinks until the AHRS is aligned (gyro bias initialized) and then stays on
; ''GPS_LED'': blinking if trying to get a fix, on if 3D fix
; ''RADIO_CONTROL_LED'': on if RC signal is ok
; ''BARO_LED'' : only on booz and navgo boards: blinks until baro offset is initialized and then stays on

Depending on your board some of the LEDs on it are already assigned to some indicators by default, check the appropriate autopilot board makefile for the defaults.

To reconfigure the default assignment, assign the indicator to an other value. Use ''none'' if indicator should not be assigned to any LED.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<configure name="SYS_TIME_LED" value="1"/>
<configure name="RADIO_CONTROL_LED" value="2"/>
<configure name="GPS_LED" value="none"/>
</firmware>
</source>
}}

Beware that you can only assign '''one''' indicator to a LED number. So if the LED you want to use is already in use because another indicator is set to that number by default you have to disable that other indicator by setting it to ''none'' or reconfigure it to an other LED.

== Subsystems ==
{| class="wikitable"
|-
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. The roadmap of Paparazzi is to convert existing subsystems to [[modules]].
|}
Each autopilot features certain [[Subsystems|subsystems]] which need to be configured properly.
The most important ones are described below.

=== IMU ===

Add the [[Subsystem/imu|imu subsystem]] with the type you are using.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="imu" type="aspirin_v1.5"/>
</firmware>
</source>
}}

See the [[Subsystem/imu|imu subsystem]] page for more details.
Also see the [[ImuCalibration|IMU calibration]] page.

=== AHRS ===

The [[Subsystem/ahrs|AHRS subsystem]] specifies which attitude estimation filter you are using, e.g. for the complementary filter:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="ahrs" type="int_cmpl_euler"/>
</firmware>
</source>
}}
All AHRS algorithms depend on an imu subsystem, except for the ahrs_infrared which depends on the infrared module.
See the [[Subsystem/ahrs|AHRS subsystem page]] for more details.

If the magnetometer should be used the [[Subsystem/ahrs#Local_Magnetic_Field|local magnetic field section]] must be filled in.

=== Radio Control ===

Supported types are:
* ''ppm''
* ''spektrum''
* ''datalink''

Just specify the appropriate [[Subsystem/radio_control|radio control subsystem]] in your firmware section, e.g.:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="radio_control" type="ppm"/>
</firmware>
</source>
}}

=== Telemetry (Modem) ===

The modem protocol and baud rate must be set in both the airframe file and ground station. Any standard baud rate can be used, with 9600 being adequate and 57600 recommended for most users to allow high speed telemetry for more detailed flight data analysis. The actual data rate is determined by the number of messages being sent and the period of each message as defined in your [[Telemetry|telemetry file]], e.g. <tt>conf/telemetry/default.xml</tt>. Those wishing to experiment with "alternative" modems can reduce the number and period of each telemetry message to fit within most any bandwidth constraint.

The [[Subsystem/telemetry|telemetry subsystem]] supports the following modem protocols:
* Standard transparent serial (pprz) - this is compatible with all modems and can be used to connect the autopilot directly to a PC for testing without a modem.
* Maxstream API protocol (xbee) - compatible with all Maxstream modems including the 9XTend and Zigbee. This protocol enables hardware addressing, allowing multiple aircraft to be managed from a single ground modem.

Just specify the appropriate [[Subsystem/telemetry|telemetry subsystem]] in your firmware section. You can currently choose between the types ''transparent'', ''transparent_usb'' and ''xbee_api''.

'''The default baudrate is 57600 baud, see the [[Subsystem/telemetry|telemetry subsystem]] page for more details and configuration options.'''
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="telemetry" type="transparent"/>
</firmware>
</source>
}}

=== GPS ===

The serial port settings must match that of the GPS and are configured here along with the necessary files to interpret the u-blox UBX binary protocol:

Just specify the appropriate [[Subsystem/gps|gps subsystem]] in your firmware section. You can currently choose between the types '''ublox''' and '''ublox_utm''' for the older series 4 modules which still provide a UTM message.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<module name="gps" type="ublox"/>
</firmware>
</source>
}}

The correct UART is already defined by default according to your board.
The default GPS baudrate is 38400baud.

If you need to set different baud rates or UART see the [[Subsystem/gps]] page for the options.

'''Note:'''
* u-blox GPS modules are factory configured for 9600 baud, 38,400 baud is recommended along with the other required changes. The GPS can be accessed directly through the [[tunnel|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center|Configured with u-center]]

== XML Parameters ==

'''When defining parameters you can use [[Units|automatic unit conversion]] to conveniently set it in e.g. degrees.'''

=== Commands ===

The <tt>commands</tt> lists the abstract commands you need to control the aircraft. In a simple fixed-wing example, we have only three:
<source lang="xml">
<commands>
<axis name="THROTTLE" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="PITCH" failsafe_value="0"/>
</commands>
</source>
For rotorcraft, it is usually:
<source lang="xml">
<commands>
<axis name="PITCH" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="YAW" failsafe_value="0"/>
<axis name="THRUST" failsafe_value="0"/>
</commands>
</source>

Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board. The range of these values is [-9600:9600]. For <tt>"THROTTLE"</tt>, the range is [0, 9600] and in the corresponding <tt>servo</tt> definition the <tt>neutral</tt> and <tt>min</tt> are usually the same for PWM based servos (see below). Note that these commands do not necessarily match the servo actuators. For example, the <tt>"ROLL"</tt> command is typically linked to two aileron actuators.

=== Servos ===

The above commands get translated to the <tt>servos</tt> here. In the example below we use two elevons and a motor. ([http://en.wikipedia.org/wiki/Elevon ''Elevons''] are surfaces used for both pitch and roll as on a flying wing.) These servos are listed in the <tt>servos</tt> section:
<source lang="xml">
<servos>
<servo name="THROTTLE" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="ELEVON_LEFTSIDE" no="1" min="2000" neutral="1500" max="1000"/>
<servo name="ELEVON_RIGHTSIDE" no="2" min="1000" neutral="1500" max="2000"/>
</servos>
</source>

Names are associated to the corresponding '''real physical connector''' to which a servo is connected '''on the autopilot board'''. For example no="2" means connector two on the board. Also the servo neutral value, total range and direction are defined. Min/max/neutral values are expressed in microseconds. The direction of travel can be reversed by exchanging min with max (as in <tt>"ELEVON_LEFTSIDE"</tt>, above). The ''standard'' travel for a hobby servo is 1000µs - 2000µs with a 1500µs neutral. Trim can be added by changing this neutral value. Absolute servo travel limits can be increased or reduced with the min/max values. The <tt>"THROTTLE"</tt> servo typically has the same value for the <tt>neutral</tt> and <tt>min</tt>.

The attribute <tt>driver</tt> for <tt>servos</tt> node tells which actuators' driver is associated to the listed servos. After the version '''v4.9_devel-164-gdb0d004''', multiple servos sections can be defined and used together, if the correct [[Subsystem/actuators| actuators subsystems]] are loaded. Some boards are automatically loading a default driver, the one used when no <tt>driver</tt> attribute is specified.

Note the following important tips:
* Reverse the servo direction by exchanging min/max
* Trim should always be adjusted mechanically if possible to avoid asymmetrical travel
* Any reduction of the total travel range should be done mechanically to maintain precision
* Many servos will respond well to values slightly outside the normal 1000-2000µs range but experiment carefully as the servo may not operate reliably outside this range and may even suffer permanent damage.
* Board connector numbering starts with zero (0) not with one
* Servos are also known under the synonym actuators
* (after version '''v4.9_devel-164-gdb0d004''') For I2C based motor speed control using the [[Rotorcraft_Configuration#Motor_Mixing|motor mixing]]:
** min: command to stop the motor
** neutral: motor idle command
** max: max thrust command

The <tt>servos</tt> are then linked to the commands in the <tt>command_laws</tt> section:
<source lang="xml">
<command_laws>
<let var="aileron" value="@ROLL * 0.3"/>
<let var="elevator" value="@PITCH * 0.7"/>
<set servo="THROTTLE" value="@THROTTLE"/>
<set servo="ELEVON_LEFTSIDE" value="$elevator + $aileron"/>
<set servo="ELEVON_RIGHTSIDE" value="$elevator - $aileron"/>
</command_laws>
</source>

[[Image:airframe_sign_conventions.jpg|thumb|Sign conventions for flight dynamics]]
where the third line is the simplest: the throttle servo value equals throttle command value. The other lines define and control the pitch/roll mixing. Elevon values are computed with a combination of two commands, '''ROLL''' and '''PITCH'''. This ''mixer'' is defined with two intermediate variables '''aileron''' and '''elevator''' introduced with the <tt>let</tt> element. The '''@''' symbol is used to reference a command value in the <tt>value</tt> attribute of the <tt>set</tt> and <tt>let</tt> elements. In the above example, the servos are limited to +/- 70% of their full travel for pitch and 30% for roll, only in combination can the servos reach 100% deflection. Note that these numbers ''should add up 100% or more, never less''. For example, you may want 100% travel available for pitch - this means if a roll is commanded along with maximum pitch only one servo will respond to the roll command as the other has already reached its mechanical limit. If you find after tuning that these numbers add to less than 100% consider reducing the surface travel mechanically.

Note that the signs used in the description follow the standard convention.

After '''v4.9_devel-164-gdb0d004''', the <tt>command_laws</tt> section is mandatory for both fixedwing and rotorcraft firmwares, only for fixedwing otherwise.

=== Battery ===

This section gives characteristics for monitoring the main power battery.

<tt>MILLIAMP_AT_FULL_THROTTLE</tt> represents the actual current (in mA) when full THROTTLE is applied. Note that when flying the current typically is significantly lower than in static tests at home on your workbench. <tt>MILLIAMP_AT_FULL_THROTTLE</tt> is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message when no [[Current_sensor|Current sensor]] is mounted in the airframe. This value can also be used in flight plans. For example, if at full throttle your motor consumes 10 Amps, use a value of 10000. You can "tweak" this number after a few flights to match the capacity of your battery. If upon landing your bat.energy messages says that you used 2500 mAh while the energy recharged into the battery is only 2000 mAh, you could reduce the <tt>MILLIAMP_AT_FULL_THROTTLE</tt> value by 20% to match your in-flight current consumption. This tweaking is most precise if you fly full throttle only (respectively no throttle to glide down again).

The <tt>CURRENT_ESTIMATION_NONLINEARITY</tt> can be added to tweak the energy estimation for non full throttle cruise. As the current consumption is nonlinear, at 50% throttle it is likely to be substantially less than 50%. A superellipse is used to approximate this nonlinearity. The default setting is 1.2 and is used if the <tt>CURRENT_ESTIMATION_NONLINEARITY</tt> is not defined in your airframe file. A value 1 corresponds to linear behaviour, 1.5 corresponds to strong nonlinearity. The tweaking is done same as described above for <tt>MILLIAMP_AT_FULL_THROTTLE</tt>, but only partial throttle (cruise throttle) should be applied in flight.

If both <tt>MILLIAMP_AT_FULL_THROTTLE</tt> and <tt>CURRENT_ESTIMATION_NONLINEARITY</tt> are tweaked well, you get precise energy estimations with less than 5% error independent of your flight pattern without even requiring a [[Current_sensor|current sensor]].

The <tt>CATASTROPHIC_BAT_LEVEL</tt> (was previously <tt>LOW_BATTERY</tt>) value defines the voltage at which the autopilot will lock the throttle at 0% in autonomous mode (kill_throttle mode). This value is also used by the ground server to issue a '''CATASTROPHIC''' alarm message on the bus (this message will be displayed in the console of the GCS). <tt>CRITIC</tt> and <tt>LOW</tt> values will also used as threshold for '''CRITIC''' and '''WARNING''' alarms. They are optional and the respective defaults are 10.0 and 10.5V.

The <tt>MAX_BAT_LEVEL</tt> may be specified to improve the display of the battery gauge in the strip or in "papgets". Note that this definition is optional, with a default value of 12.5V.

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing">
...
<define name="ADC_CHANNEL_VSUPPLY" value="ADC_4" />
</firmware>
...
<section name="BAT">
<define name="MILLIAMP_AT_FULL_THROTTLE" value="12000" unit="mA" />
<define name="CATASTROPHIC_BAT_LEVEL" value="6.0" unit="V"/>
<define name="CRITIC_BAT_LEVEL" value="6.5" unit="V"/>
<define name="LOW_BAT_LEVEL" value="7.0" unit="V"/>
<define name="MAX_BAT_LEVEL" value="8.4" unit="V"/>
</section>
</source>
}}

The conversion of ADC measurements to Voltage is already defined for the different autopilot boards, if you need to override these defaults you can use the <tt>VoltageOfAdc(adc)</tt> define and also specify offsets or anything else you might need, e.g.:

{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="BAT">
...
<define name="VOLTAGE_ADC_SCALE" value="0.0177531"/>
<define name="VOLTAGE_OFFSET" value="0.5" unit="V"/>
<define name="VoltageOfAdc(adc)" value="(VOLTAGE_ADC_SCALE * adc + VOLTAGE_OFFSET)"/>
</section>
</source>
}}

Calculating '''VOLTAGE_ADC_SCALE''':

<math>VOLTAGE\_ADC\_SCALE=\frac{Vref}{ADCresolution-1}\div\frac{R2}{R1+R2}</math>

*Vref - Voltage reference for the ADC (will be 3.3V in most cases, can be found in mcu/adc datasheet)
*ADCresolution - ADC bit depth (e.g. 2^12=4096 for a 12 bit ADC)
*R1 - Resistor between battery and ADC input pin of MCU
*R2 - Resistor between ADC input pin of the MCU and GND

It is also a good idea to measure the actual voltage of the battery with a precision voltage meter, compare it with the calculated value from the autopilot (e.g. via [[Paparazzi_Center#Messages]]) and edit the vales for ADC scaling. Since the resistors have a tolerance, this can fine tune the measurement.

=== Modules ===

The [[Modules|modules]] allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.

<source lang="xml">
<modules main_freq="60">
<load name="demo_module.xml"/>
</modules>
</source>

* The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz

{| class="wikitable"
|-
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. It is therefore also possible to use the modules the same way subsystems used to be (i.e. as children of the ''firmware'' node and not only the ''modules'' node as presented above. The roadmap of Paparazzi is to convert existing subsystems to [[modules]].
|}

{| class="wikitable"
|-
| Starting from '''v5.12''' the ''modules'' element will gradually be phased out. Instead, the modules should be added inside the ''firmware'' tags of the airframe file:
|}
<source lang="xml>
<firmware name="fixedwing or rotorcraft">
...
<module name="demo_module"/>
</firmware>
</source>

=== GCS ===

[[Image:ac_icon_multi_uav.png|thumb|Various A/C icons demonstrated on a multi UAV simulation session]]

[[Image:Icons_Theme_Default.png|thumb|Default Theme]]

[[Image:Icons_Theme_Flat.png|thumb|Flat Theme]]

Use this optional section to help customize parts of the GCS for a specific airframe:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<section name="GCS">
...
<define name="ICONS_THEME" value="flat_theme"/>
<define name="ALT_SHIFT_PLUS_PLUS" value="30"/>
<define name="ALT_SHIFT_PLUS" value="5"/>
<define name="ALT_SHIFT_MINUS" value="-5"/>
<define name="SPEECH_NAME" value="Quad"/>
<define name="AC_ICON" value="flyingwing"/>
</section>
</source>
}}

* <tt>ICONS_THEME</tt> can be used to define an alternate/custom GCS icons theme for a given aircraft The '''flat_theme''' is one example of an alternate set of GCS icons.
* <tt>ALT_SHIFT_PLUS_PLUS</tt> sets the number of metres the target altitude will change when the double up arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>ALT_SHIFT_PLUS</tt> sets the number of metres the target altitude will change when the up arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>ALT_SHIFT_MINUS</tt> sets the number of metres the target altitude will change when the down arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>SPEECH_NAME</tt> a string ([a-zA-Z0-9_]) that will be used in place of the aircraft name specified in <tt>conf.xml</tt> for the [[Speech|speech]] and [[GCS#Alarms|alarms]] functionality. Set this to "_" to prevent the speech function from saying the aircraft name. Useful if your aircraft name takes a long time to say (i.e. "UAV1-A_with_spektrum" can be shortened to "Plane").
* <tt>AC_ICON</tt> can be used to define the vehicle icon (or overwrite the default icon) that shows up on the 2D-map of the GCS. Available values are: <tt>flyingwing</tt> , <tt>fixedwing</tt> , <tt>rotorcraft</tt> , <tt>quadrotor</tt> , <tt>hexarotor</tt> , <tt>octorotor</tt> , <tt>quadrotor_x</tt> , <tt>hexarotor_x</tt> , <tt>octorotor_x</tt> , <tt>home</tt>.

==== Custom Icons Theme Support ====

A custom icons theme is supported through the use of the '''ICONS_THEME''' attribute. Set the '''ICONS_THEME''' attribute ''value'' to the path of your custom icons theme directory and the given aircraft will now display your custom icons. Note that the path is relative to the default GCS icons path root: ''$PAPARAZZI_HOME/data/pictures/gcs_icons''

{{Box Code|code snippet|
<source lang="xml">
<section name="GCS">
<define name="ICONS_THEME" value="myawesome_icons"/>
</section>
</source>
}}

The directory that contains your custom icons, in this example named ''myawesome_icons'', is located at ''$PAPARAZZI_HOME/data/pictures/gcs_icons''.

[[Category:User_Documentation]] [[Category:Airframe_Configuration]]

Speech

2017-11-28T09:27:29Z

Tomvand: Add install command for espeak, is not included by default with Ubuntu 16.04

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>GCS</categorytree>
__TOC__

==Speech==

The [[GCS]] is able to provide the messages of the console via the speakers by starting with the option [[GCS_Configuration|-speech]].

'''On Ubuntu this works out of the box with speech-dispatcher and espeak.'''

Make sure speech-dispatcher and espeak are installed
sudo apt-get install speech-dispatcher espeak

You can test your setup with
spd-conf -d

'''On OS X (10.6 tested) this works out of the box with say.'''

You can test your setup with
say "whatever you want your computer to say"

Note that in OS X, multiple calls in quick succession from the GCS will start multiple say processes, resulting in multiple messages being spoken at the same time, making it sound rather garbled. This tends to happen when the GCS is first initialized.

== Using festival ==
If you want to use festival instead you need to install some packages and configure the speech-dispatcher to use festival.

=== Packages Installation===
Install festival, speech-dispatcher, speech-dispatcher-festival and python-speechd packages, if not already installed. 
sudo apt-get install festival speech-dispatcher speech-dispatcher-festival python-speechd

=== Configuration===
Edit '''speechd.conf''' in /etc/speech-dispatcher/ with the command
sudo gedit /etc/speech-dispatcher/speechd.conf

AddModule "espeak" "sd_espeak" "espeak.conf" 
AddModule "festival" "sd_festival" "festival.conf" 
#AddModule "flite" "sd_flite" "flite.conf" 
#AddModule "espeak-generic" "sd_generic" "espeak-generic.conf" 
#AddModule "epos-generic" "sd_generic" "epos-generic.conf" 
#AddModule "dtk-generic" "sd_generic" "dtk-generic.conf" 
#AddModule "ibmtts" "sd_ibmtts" "ibmtts.conf" 
#AddModule "cicero" "sd_cicero" "cicero.conf" 
 
DefaultModule festival

'''Optionally''' edit festival.conf in /etc/speech-dispatcher/modules/ and change/uncomment the following lines (these are the defaults so they don't need to be uncommented if not changed): 
# Address where the Festival server runs (you have to 
# have a Festival server running, please see documentation).
 
FestivalServerHost "localhost" 
FestivalServerPort 1314

=== Starting the applications/servers===
Type in the command window: 
festival --server

You can test with
spd-conf --test-festival
spd-conf -d

You might have to kill your current speech-dispatcher for the changes to take effect.

Start the [[GCS_Configuration|GCS]] with the -speech option and there you go!

[[Category:GCS]] [[Category:User_Documentation]]