Flight Plans

2009-11-19T05:10:47Z

Msquared: /* Blocks */

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

<tt><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></tt>

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 in the GUI.

== Structure of the flight plan file ==

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

A flight plan is composed of two compulsory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]] and typically contains optional <tt>include</tt>'s and global <tt>exceptions</tt>.

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt><flight_plan name lat0 lon0 ground_alt security_height qfu alt max_dist_from_home></tt>
* <tt>name</tt>: the name of the mission (a text string)
* <tt>lat0, lon0</tt>: describe the latitude and longitude of the point {0,0} in WGS84 degree coordinates
* <tt>ground_alt</tt>: the ground altitude (in meters). It defines the <tt>GROUND_ALT</tt> constant value which can be used to define waypoint altitudes
* <tt>security_height</tt>: the altitude used by the circle-home failsafe procedure
* <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.
* <tt>alt</tt>: the default altitude of waypoints
* <tt>max_dist_from_home</tt>: the maximum allowed distance (in meters) from the HOME waypoint.

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

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

=== Waypoints ===

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified with its name and its relative coordinates:
<tt> <waypoint name x y [alt] /> </tt>
where <tt>x</tt> and <tt>y</tt> are the coordinates in meters from point {0,0}. <tt>alt</tt> is optional and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> above. Note that a waypoint named <tt>HOME</tt> is required as it is used by the failsafe HOME mode procedure.

One example:
<tt>
<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>
</tt>

Waypoints are easily edited with the [[Flight_Plan_Editor|flight plan editor]].

Waypoints which name starts with an underscore are not displayed in the GCS, except in editor mode.

=== Sectors ===
Flat ''Sectors'' can be described as a list of waypoint corners. Such an area will be displayed in the GCS (a optional color can be specified).
A function is generated to check if a point (usually the aircraft itself) is ''inside'' the polygon. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>sector</tt>, the generated function is <tt>bool_t InsideSector(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. Note: If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS.

For example, with the following element in a flight plan (waypoints which name starts with an underscore are not displayed in the GCS, except in editor mode)
<tt>
<sectors>
<sector name="Muret" color="red">
<corner name="_1"/>
<corner name="_2"/>
<corner name="_3"/>
<corner name="_4"/>
</sector>
</sectors>
</tt>
it is then possible to write a exception to stay inside it:
<tt>
<exception cond="! InsideMuret(estimator_x, estimator_y)" deroute="standby"/>
</tt>

=== 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:
<tt><includes>
<include name="landing" procedure="landing.xml"/>
</includes></tt>

=== 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 go 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'':
<tt><!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|circle|deroute|stay|follow
|survey_rectangle)*></tt>

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

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<tt><block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block> </tt>
This button will activate the block.

In the same way, a key shortcut can be specified:
<tt><block key="D" name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block> </tt>
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>:
<tt><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></tt>

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

===== 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:
<tt><exception cond="..." deroute="..."></tt>
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:
<tt><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"/></tt>

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.
<tt><flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...</tt>

==== Deroute ====

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

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

==== 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:
<tt><while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while></tt>
In this example, we run an infinite loop, going to 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:
<tt><for var="i" from="0" to="3">
...
</for></tt>
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:
<tt><for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for></tt>
In this example, we circle around '''HOME''' 10 seconds at height 50m, 10s at height 100m, ... until height 250m.
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 <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:
<tt><attitude roll="0" vmode="throttle", throttle="0.5"/></tt>

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

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:
<tt><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(estimator_z > ground_alt+30)"/></tt>

==== 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
<tt><go wp="HOME"/></tt>
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:
<tt><go from="wp1" wp="wp2" hmode="route"/></tt>

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:
<tt><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></tt>

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

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).
<tt><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></tt>

==== 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:
<tt><circle wp="HOME" radius="75"/></tt>
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:
<tt><circle wp="wp1" radius="50+(estimator_z-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></tt>

==== 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.
<tt><follow ac_id="4" distance="50" height="20"/></tt>
Note that the <tt>traffic_info.c</tt> file is required by this feature and the <tt>TRAFFIC_INFO</tt> flag has to be set to enable it. Then, the following lines must be added in the airframe file:
<tt>ap.srcs += traffic_info.c</tt>
<tt>ap.CFLAGS += -DTRAFFIC_INFO</tt>
<tt>sim.srcs += traffic_info.c</tt>
<tt>sim.CFLAGS += -DTRAFFIC_INFO</tt>

==== Stay ====

The <tt>stay</tt> is a mode for UAS's able to hover:
<tt><stay wp="HOME" alt="10"/></tt>

==== 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'''):
<tt><xyz radius="40"/></tt>

==== 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):
<tt><set var="ground_alt" value="ground_alt+50"/></tt>
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:
<tt><call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/></tt>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> 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 <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<tt><header>
#include "nav_line.h"
</header></tt>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

== 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, ...:
<tt><!ELEMENT procedure (param*,header?,waypoints?,sectors?,exceptions?,blocks?)></tt>

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:
<tt><param name="alt"/>
<param name="radius" default_value="75"/></tt>

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:
<tt><include name="landing" procedure="landing.xml"/></tt>

Here is the corresponding procedure '''landing.xml''':
<tt><!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>
</tt>

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

Suppose you have a go-around condition in your landing procedure. You would write it
<tt><exception cond="..." deroute="go-around"/></tt>
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:
<tt><include name="landing" procedure="landing.xml">
<with from="go-around" to="Standby"/>
</include></tt>

== Flight Simulation ==
Complex flight plans should always be carefully tested prior to flight. See the [[Simulation|simulation]] page for details.

Conf.xml

2009-11-19T04:29:17Z

Msquared:

The <tt><b>conf/conf.xml</b></tt> document associates the flight plan and various hardware/software configuration files with a particular aircraft, identified by <tt>name</tt> and <tt>ac_id</tt>. The values in this document are set and handled by the [[Paparazzi_Center|Paparazzi Center]] so it is usually not needed to edit the configuration document manually.

== Syntax ==
<tt>
<aircraft
name="Plaster"
ac_id="7"
airframe="airframes/plaster1.xml"
radio="radios/cockpitMM.xml"
flight_plan="flight_plans/generic.xml"
telemetry="telemetry/default.xml"
settings="settings/basic.xml"
gui_color="red"
/></tt>

where:
* <tt>name</tt> is the name of the aircraft which will appear in different places in the [[GCS|GCS]]
* <tt>ac_id</tt> is a unique integer (between 1 and 255) identifying the aircraft (especially needed in the communication messages)
* <tt>airframe</tt> is the file name containing the parameters of the aircraft
* <tt>radio</tt> is the file name containing the description of the RC transmitter
* <tt>flight_plan</tt> is the sequence of actions and waypoints describing the desired trajectory
* <tt>telemetry</tt> is the file name containing the set of messages sent over the telemetry link
* <tt>settings</tt> is the file name containing the set of parameters that can be configured through the telemetry link
* <tt>gui_color</tt> is the color assigned to this aircraft in the GCS

All these attributes are required except the last two (<tt>settings</tt> and <tt>gui_color</tt>) which are optional.

The following sections describe these xml documents:
* [[Radio_Control|Radio Control]]
* [[Airframe_Configuration|Airframe]]
* [[Flight_Plans|Flight plans]]
* [[Telemetry|Telemetry]]
* [[Settings]]

PaparazziUAV - User contributions [en]

Flight Plans

Conf.xml