Flight Plans

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 file using the following line:

<!DOCTYPE flight_plan SYSTEM "flight_plan.dtd">

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

Structure of flight plan files

Extract from the DTD:

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

So a flight plan is composed two compulsory elements: waypoints and blocks and typically contains optional include's and global exceptions.

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: 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.
• alt: the default altitude of waypoints
• max_dist_from_home: the maximum allowed distance (in meters) from the HOME waypoint.

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" ground_alt="185" security_height="25" qfu="270" alt="250">

Waypoints

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified with its name and its relative coordinates:

 <waypoint name x y [alt] /> 

where x and y are the coordinates in meters from point {0,0}. alt is optional and can be used to assign an altitude to a particular waypoint that is different from the globally defined alt above. Note that a waypoint named HOME is required as it is used by the failsafe HOME mode procedure.

One example: <waypoints>

 <waypoint name="HOME" x="0.0" y="30.0"/>
 <waypoint name="1" x="-100.0" y="60.0" alt="270."/>
 <waypoint name="2" x="-130.0" y="217.5" alt="3000."/>

</waypoints>

Waypoints are easyly edited with the GCS editor.

Include

include is used to add blocks defined in an external procedure. It’s useful to use ever made procedure with only few arguments and then clarify the flight plan. Here is the structure:

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

where name will be used in this flight plan to jump to the blocks of the procedure, the XML referenced file. The procedure can be shifed (x meters east, y meters north) and rotated (clockwise degrees, north=0). Named arguments may be be given with their value in the arg elements. The with tag allows to link labels from the procedure to blocks of the main flight plan. Then, each blocks of the procedure is like any block of the flight plan and is designated with a dotted idenfifier: block b of a procedure named p is named b.p .

Here is an example:

<include name="hippo1" procedure="hippo.xml" x="-100" y="150" rotate="0">
 <arg name="alt" value="GROUND ALT+100"/>
 <with from="event1" to="penta"/>
</include>

where a jump to event1 inside the hippo.xml procedure will actually jump to the penta block of the current flight plan.

Blocks

Block elements are the main part of a flight plan: they describe each units 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 go 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>

If your system is equipped with a datalink, you can add a button in the [:UserManual/GCSFeatures: strip of the aircraft] with the attribute strip_button:

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

This button will activate the block.

Expressions

Most of the numeric attributes in stages are analyze 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:

  RcEvent1() and RcEvent2(), which correspond to radio control events (set with the GAIN1 channel)

  Qdr(value), in a circle stage, is true when QDR of the aircraft from the center of the circle is around the given value

  RadOfDeg(degrees) to convert degrees to radians

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

Exceptions

The flight manager can handle exceptions. They consist into conditions checked periodically (at the same pace than 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 there are some example of exceptions:

<exception cond="(RcEvent1())" deroute="go_again"/>
<exception cond="(ground_alt+10 > estimator z)" deroute="go_again"/>
<exception cond="(RcEvent2())" deroute="stop"/>
<exception cond="(estimator_flight_time > 840)" deroute="quick_land"/>

Exceptions can be local to a block a global to the flight plan (in a <exceptions> element).

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 the while element which 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 > block_time"/>
</while>

In this example, we run an infinite loop, going to 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, we circle around HOME 10 seconds at height 50m, 10s at height 100m, ... until height 250m. Note: Bounded loops using the same 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 theses 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-win 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 theses 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 radian) 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 radian, 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="0.3" alt="ground_alt+50"/>

Note that it is not a safe navigation mode. 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 until height of 30m is reached:

<heading course="QFU" vmode="throttle" throttle="0.8" pitch="0.3" 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 that 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 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"/>

With extra attributes, new target waypoints can be specified relatively to actual ones. For example, if you want to navigate from a point 100m north of 1 to a point 50m east of 2:

<go from="wp1" from_qdr="0" from_dist="100" wp="wp2" wp_qdr="90" wp_dist="50" hmode="route"/>

Note that during the flight plan preprocessing, these virtual waypoints will be created and they will appear in the GCS as wp1_0_100 and wp2_90_50.

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 UAV fly 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, 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="0.3" until="10>PowerVoltage()"/>

Follow

The follow is a special primitive which makes your UAV follow the another UAV (real or simulated, named with its ac_id) at a given distance (in meters) behind and and 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"/>

Stay

The stay is a mode for UAVs able to hover:

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

Xyz

xyz is a special mode where the UAV 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 used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value the default ground altitude, a variable used by the home mode failsafe procedure (an 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.

Procedures

Procedures are libraries which can be included in flight plans. They are composed of waypoints 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, optional global exceptions and blocks:

<!ELEMENT procedure (param*,waypoints,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 by another procedure). A procedure call requires:

• the name of the procedure file, the name given to this inclusion;
• the relative position and the orientation of the procedure in the flight plan;
• values for the parameters;
• backlinks for block name exits of the procedure.

For example:

<include name="hippo1" procedure="hippo.xml" x="-100" y="150" rotate="0">
 <arg name="alt" value="ground_alt+100"/>
 <with from="end" to="landing"/>
</include>

Here is the corresponding procedure hippo.xml:

<procedure>
 <param name="alt"/>
 <param name="radius" default value="75"/>
 <waypoints>
   <waypoint name="c1" x="0" y="0"/>
   <waypoint name="c2" x="250" y="0"/>
 </waypoints>
 <blocks>
   <block name="oneturn">
     <go hmode="route" alt="alt" from="c1" from_qdr="0" from_dist="radius" wp="c2" wp_qdr="0" wp_dist="radius"/>
     <circle wp="c2" radius="radius" until="Qdr(180)" alt="alt"/>
     <go hmode="route" alt="alt" from="c2" from_qdr="180" from_dist="radius" wp="c1" wp_qdr="180" wp_dist="radius"/>
     <circle wp="c1" radius="radius" until="Qdr(0)" alt="alt"/>
     <deroute block="end"/>
   </block>
 </blocks>
</procedure>

Note that the name of procedure block is then hippo1.oneturn:

<deroute block="hippo1.oneturn"/>

will jump to this procedure block.