Flight Plans

Introduction

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

The formal description of the flight plan file is given in the DTD (located in conf/flight_plans/flight_plan.dtd). This DTD must be referenced in the header of your flight plan XML document using the following line:

<!DOCTYPE flight_plan SYSTEM "flight_plan.dtd">

The flight plans are stored in the conf/flight_plans directory. The flight plan editor can be used to create basic flight plans via the GUI.

Structure

Extract from the DTD:

<!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)>

A flight plan is composed of two mandatory elements: waypoints and blocks

The root flight_plan element is specified with several attributes:

<flight_plan name lat0 lon0 ground_alt security_height qfu alt max_dist_from_home>

name: the name of the mission (a text string)
lat0, lon0: describe the latitude and longitude of the point {0,0} in WGS84 degree coordinates
ground_alt: the ground altitude (in meters). It defines the GROUND_ALT constant value which can be used to define waypoint altitudes
security_height: the altitude used by the circle-home failsafe procedure
qfu (optional): defines the global constant QFU. 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.
alt: the default altitude of waypoints (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.
max_dist_from_home: the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value will trigger an exception.

Here is an example of the first line of a flight plan:

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

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

Waypoints

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:

 <waypoint name wpx wpy [alt] [height]/>

where wpx and wpy are real positional coordinates ( lat/lon ) or UTM coordinates ( utm_x0/utm_y0 ) or relative coordinates ( x/y ) in meters from your reference point {0,0} . alt and height are optional parameters and can be used to assign an altitude to a particular waypoint that is different from the globally defined alt parameter of the flightplan. To set the waypoint altitude relative to the ground altitude (ground_alt) of the flight plan for this waypoint, use the height attribute instead of alt.

An example:

Tips

Waypoints are easily adjusted with the 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 HOME is required if the failsafe HOME mode procedure is used.

Sectors

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. 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 sector. Note that sector names are not allowed to contain spaces. The generated function is bool_t InsideSector(float x, float y); where x and y 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.

For example, with the following element in a flight plan.


<sectors>
 <sector name="MyCosySector" color="red">
  <corner name="_1"/>
  <corner name="_2"/>
  <corner name="_3"/>
  <corner name="_4"/>
 </sector>
</sectors>

It is then possible to write a exception. For example if the aircraft for some reason flies outside this sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator NOT in this example. In regular language one would describe "If my airframe is NOT inside the Murret sector anymore then deroute it to the standby waypoint." In Flightplan "Speak" this is written like:

<exception cond="! InsideMyCosySector(estimator_x, estimator_y)" deroute="standby"/>

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 of the sector is not fixed but can be defined by oneself if wished for via the color attribute.

Includes

include 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:

<include name procedure> [<arg name value />]*[<with from to />]*</include>

where name attribute of the include element will be used in this flight plan to prefix the blocks of the procedure, the XML referenced file. Named arguments may be given with their value in the arg elements. The with 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 b of a procedure named p is named b.p .

Here is an example:


<includes>
  <include name="landing" procedure="landing.xml"/>
</includes>

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 blocks element is composed of block elements which are sequence of stages:

<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|circle|deroute|stay|follow
                          |survey_rectangle)*>

Example:

<block name="circlehome">
  <circle radius="75" wp="HOME"/>
</block>

You can add a button in the strip of the aircraft with the attribute strip_button:

<block name="descent" strip_button="Descent">
 <circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>

This button will activate the block. If the attribute group 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:

<block key="D" name="descent" strip_button="Descent">
 <circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>

Modifiers are allowed, using the syntax of GTK accelerators.

An icon can be specified to display the button. The strip_button label then is a tooltip for the icon. The icon must be an image file available in the directory data/pictures/gcs_icons:

<block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff">

You can call functions before or after each execution of the block:

<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
 <circle wp="HOME"/>
</block>

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 examples)
Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
Some utility functions

Some examples of usable expressions are given in the next sections.

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:

<exception cond="..." deroute="...">

where cond is an expression and deroute is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:

<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > estimator_z)" deroute="go_up"/>
<exception cond="(estimator_flight_time > 840)" deroute="quick_land"/>

Exceptions can be local to a block or global to the flight plan, in the <exceptions> 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 Standby block if no message have been received for 22s. This exception is valid for all the blocks.

<flight_plan ...>
 <waypoints> ... </waypoints>
 <exceptions>
   <exception cond="datalink_time > 22" deroute="Standby"/>
 </exceptions>
 <blocks> ...

Deroute

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

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

Loops

Unbounded loops are written with while elements whose cond attribute is a boolean expression. Children of while are stages:

<while cond="TRUE">
 <go wp="A"/>
 <go wp="B"/> 
 <go wp="C"/>
 <while cond="5 > stage_time"/>
</while>

In this example, we run an infinite loop, lettin the aircraft try to go via waypoints A, B and C and waiting for 5 seconds before repeating.

Bounded loops are written with the for tag:

<for var="i" from="0" to="3">
...
</for>

where the body of the loop will be run four times.

The variable of a for loop can be used inside expressions appearing as attributes of the stages:

<for var="i" from="1" to="5">
 <circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>

In this example, the aircraft will circle around waypoint HOME for 10 seconds at and altitude above ground of 50m, 10 seconds at altitude 100 meter (50+50), ... until 250m (5x +50).

Note: Two bounded loops using the same control variable are not allowed in the same block.

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;
circle : circle around a waypoint;
stay : hold the position (hard to realize for a fixed-wing aircraft);
follow : follow another aircraft;
xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the vmode 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 alt attribute;
climb : the autopilot keeps the desired vertical speed specified with the climb attribute (in m/s);
throttle : the autopilots sets the desired throttle specified with the throttle 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 pitch attribute to auto and the throttle attribute to a constant allows a vertical control only by controlling the attitude of the A/C. The pitch 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 attitude is the navigation mode which corresponds to the current lowest control loop for horizontal mode. The autopilot then keeps a constant attitude. The roll attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:

<attitude roll="0" vmode="throttle", throttle="0.5"/>

To fly around, holding a given altitude:

<attitude roll="30" alt="ground_alt+50"/>

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

heading primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given course, 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:

<heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(estimator_z > ground_alt+30)"/>

Go

The go primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (wp, the only required attribute). So the simplest thing you can ask for is

<go wp="HOME"/>

which will set the HOME waypoint as the desired target position. Note than since vmode="alt" 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 hmode attribute to route, the navigation will go over a segment joining two waypoints:

<go from="wp1" wp="wp2" hmode="route"/>

The target altitude is the altitude of the target waypoint; it can also be set with the alt attribute. The following example keeps an altitude with fixed throttle:

<go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/>

The attributes related to the vertical control can also be set to replace the default altitude mode:

<go from="wp1" wp="wp2" hmode="route" vmode="climb" climb="1.5"/>

Finally, the approaching_time (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).

<go from="wp1" wp="wp2" hmode="route" approaching_time="1"/>

Circle

The circle primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:

<circle wp="HOME" radius="75"/>

A positive radius makes the UAS move clockwise, a negative counter-clockwise.

The until 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:

<circle wp="wp1" radius="50+(estimator_z-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/>

Follow

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

In this example, the autopilot will try to follow A/C number 4, staying 50m behind and 20m above.

<follow ac_id="4" distance="50" height="20"/>

Note that the traffic_info.c file is required by this feature and the TRAFFIC_INFO flag has to be set to enable it. Then, the following lines must be added in the airframe file:

ap.srcs += traffic_info.c
ap.CFLAGS += -DTRAFFIC_INFO
sim.srcs += traffic_info.c
sim.CFLAGS += -DTRAFFIC_INFO

Stay

The stay is a mode for UAS's able to hover:

<stay wp="HOME" alt="10"/>

XYZ

xyz 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):

<xyz radius="40"/>

Set

The set 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):

<set var="ground_alt" value="ground_alt+50"/>

This directive is extremely powerful and has great potential for error - use with caution.

Call

The call allows the user to define its own navigation procedures in C. The value 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:

<call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/>

where nav_line_init() returns FALSE and nav_line() always returns TRUE (this stage never ends). Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the makefile section)

ap.srcs += nav_line.c
sim.srcs += nav_line.c

These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:

<header>
#include "nav_line.h"
</header>

These C source file and H header file must be located in the sw/airborne directory.

You can also call functions before or after each execution of the block:

<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
 <circle wp="HOME"/>
</block>

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:

<for var = "i" from = "1" to = "5">
 <circle wp = "HOME" radius="75"
         alt = "ground_alt+50*$i"
         until = "stage_time>60" />
</for>

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:

<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"/>

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, ...:

<!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)>

A parameter 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:

<param name="alt"/>
<param name="radius" default_value="75"/>

Procedures are called with the include 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:

<include name="landing" procedure="landing.xml"/>

Here is the corresponding procedure landing.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(estimator_z - WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
   </block>
...
 </blocks>

Note that the name of procedure land block will be renamed into landing.land:

<deroute block="landing.land"/>

will jump to this procedure block.

Suppose you have a go-around condition in your landing procedure. You would write it

<exception cond="..." deroute="go-around"/>

then you must link this block exit with one of your block (e.g. Standby). So you would include the procedure as follows:

<include name="landing" procedure="landing.xml">
 <with from="go-around" to="Standby"/>
</include>\

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 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 <!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd">

Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the flight plan examples page
There are several option to build failsafe features into you flightplan, 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.

Flight Plans

Contents

Introduction

DTD

Structure

Waypoints

Sectors

Includes

Blocks

Expressions

Exceptions

Deroute

Loops

Navigation modes

Attitude

Heading

Go

Circle

Follow

Stay

XYZ

Set

Call

Advanced Examples

Immobilize Actuators

Procedures

Tips and Tricks

Navigation menu

Flight Plans

Introduction

DTD

Structure

Waypoints

Sectors

Includes

Blocks

Expressions

Exceptions

Deroute

Loops

Navigation modes

Attitude

Heading

Go

Circle

Follow

Stay

XYZ

Set

Call

Advanced Examples

Immobilize Actuators

Procedures

Tips and Tricks

Navigation menu

Search