Difference between revisions of "Flight Plans"

From PaparazziUAV
Jump to navigation Jump to search
(Updated for v5.0.0_stable changes to use state interface in a number of variables useful in flightplans)
(Update sectors)
 
(62 intermediate revisions by 13 users not shown)
Line 11: Line 11:


Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
Extract from the [http://en.wikipedia.org/wiki/Document_Type_Definition DTD]:
  <tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>
  <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]]'''
'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''
Line 17: Line 17:
The root <tt>flight_plan</tt> element is specified with several attributes:
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>'''<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>'''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>'''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). It defines the <tt>GROUND_ALT</tt> constant value which can be used to define waypoint altitudes
; <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>'''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>'''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>'''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>'''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>: the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value will trigger an exception.
; <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 the first line of a flight plan:
 
''Here is an '''example''' of such a line in the top of a flight plan:''


<source lang="xml">
<source lang="xml">
   <flight_plan name="Example Muret"
   <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" >
  lat0="43.46223" lon0="1.27289" max_dist_from_home="300" qfu="270"
  ground_alt="185" security_height="25" alt="250" home_mode_height="150">
</source>
</source>


Note that a flight plan could also contain optional <tt>include</tt>'s and <tt>exceptions</tt> cases.
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 ==
== Waypoints ==
Line 40: Line 41:
The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
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>
  <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> and <tt>height</tt> are optional parameters 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. To set the waypoint altitude relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint, use the <tt>height</tt> attribute instead of <tt>alt</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:
An example:
Line 59: Line 60:
'''Tips'''
'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* 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.
* 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.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.
* 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 ==
== 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.
Flat ''Sectors'' can be described as an area defined by a 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 <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>sector</tt>. Note that sector names are not allowed to contain spaces. 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. 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.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector.
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.
Note that sector names are not allowed to contain spaces.
 
'''Note:''' The edges of the polygon should not cross each other.


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


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 <tt>NOT</tt> 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:  
 
It is then possible to add an exception clause to your flightplan. 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 <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>
 
'''Tip:''' The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.
 
=== Before version 6.0 ===
Before version 6.0, there was "static" and "dynamic" sectors. The default type of a sector was "static", except if the extra attribute '''type="dynamic"''' was added.
 
Static sectors have these limitations:
* The polygon need to be <b>convex</b> and described in a <b>clockwise</b> order.
* If the flight plan is dynamically relocated, such a sector will be relocated but the display is not updated on the GCS.
* editing of the waypoints of the sector during the flight do not dynamically update the inside function. It will always check if the position is inside the original sector.
 
 
== 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">
<source lang="xml">
<exception cond="! InsideMyCosySector(GetPosX(), GetPosY())" deroute="standby"/>
  <variables>
    <variable var="my_var" init="10" type="int"/>
  </variables>
</source>
</source>


'''Tips'''
To produce an automatic setting for a variable, at least '''min''', '''max''' and '''step''' attributes need to be specified:
* 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.
<source lang="xml">
* The color of the sector is not fixed but can be defined by oneself if wished for via the color attribute.
  <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 ==
== Includes ==
Line 154: Line 209:
Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to  
Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to  
* numeric constants
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* 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 binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions
* Some utility functions
* Since some operators are not very compliant with the XML specifications (especially '<'), you can use some alternate naming:
** @LT (less than, <)
** @GT (greater than, >)
** @LEQ (less or equal, <=)
** @GEQ (greater or equal, >=)
** @AND ( && )
** @OR ( || )
** @DEREF ( -> )


Some examples of usable expressions are given in the next sections.
Some examples of usable expressions are given in the next sections.
=== Initialization  Blocks ===
=== Initialization  Blocks ===
The first three blocks of flight plan are 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.
The first block waits until the GPS fix has been established, as shown below.
Line 185: Line 249:
     </block>
     </block>
</source>
</source>
=== Exceptions ===
=== Exceptions ===


Line 194: Line 259:
<source lang="xml">
<source lang="xml">
   <exception cond="10 > PowerVoltage()" deroute="go_down"/>
   <exception cond="10 > PowerVoltage()" deroute="go_down"/>
   <exception cond="(ground_alt+10 > GpsPosAlt())" deroute="go_up"/>
   <exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
   <exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
   <exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>
</source>
Line 214: Line 279:


Note that this primitive should not be used to execute loops which are provided by the following elements.
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 ===
=== Loops ===
Line 227: Line 297:
   </while>
   </while>
</source>
</source>
In this example, we run an infinite loop, lettin the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.
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:
Bounded loops are written with the <tt>for</tt> tag:
Line 244: Line 314:
</source>
</source>


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).
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.
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 ===
Line 261: Line 331:
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).
* 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  
The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are  
Line 292: Line 362:


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


=== Go ===
=== Go ===
Line 320: Line 390:


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


=== Circle ===
=== Circle ===
Line 329: Line 399:


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:
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+(GpsPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>
<source lang="xml"><circle wp="wp1" radius="50+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></source>


=== Oval ===
=== Oval ===
Line 336: Line 406:


=== Eight ===
=== Eight ===
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.  
'''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>
<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 ===
=== Follow ===
Line 345: Line 419:
In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m 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>
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>
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 ===
=== Stay ===


The <tt>stay</tt> is a mode for UAS's able to hover:
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>
<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 ===
=== XYZ ===
Line 377: Line 453:
This feature is illustrated with the '''line''' pattern:
This feature is illustrated with the '''line''' pattern:
<source lang="xml">
<source lang="xml">
   <call fun="nav_line_init()"/>
   <call fun="nav_line_setup()"/>
   <call fun="nav_line(WP_1, WP_2, nav_radius)"/>
   <call fun="nav_line_run(WP_1, WP_2, nav_radius)"/>
</source>
</source>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
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)
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<br />
<tt>ap.srcs += nav_line.c
 
sim.srcs += nav_line.c</tt>
To call ''any'' function exactly once regardless of the return value (e.g. call a void function), add <tt>loop="FALSE"</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<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">
<source lang="xml">
   <header>
   <header>
#include "nav_line.h"
#include "path/to/header.h"
   </header>
   </header>
</source>
</source>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.
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:
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">
<source lang="xml">
   <block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
   <block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
Line 399: Line 485:
</source>
</source>


== Advanced Examples ==
=== Pre Call ===
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">
<source lang="xml">
  <for var = "i" from = "1" to = "5">
<block name="Standby" strip_button="Standby" strip_icon="home.png" pre_call="if(!InsideKill(GetPosX(), GetPosY())) NavKillThrottle();">
    <circle wp = "HOME" radius="75"
          alt = "ground_alt+50*$i"
          until = "stage_time>60" />
  </for>
</source>
</source>


=== Immobilize Actuators ===  
=== Post Call ===


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">
<source lang="xml">
  <set var="h_ctl_disabled" value="TRUE"/>
  <block name="traj" pre_call="formation_pre_call()" post_call="formation_flight()"> <!-- formation flight is call after all other navigation tasks -->
<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>
</source>


Line 458: Line 534:
         <call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
         <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="NavCircleCount() > 0.5" wp="_BASELEG"/>
         <circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GpsPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
         <circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
       </block>
       </block>
       ...
       ...
Line 476: Line 552:
     <with from="go-around" to="Standby"/>
     <with from="go-around" to="Standby"/>
   </include>
   </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
== Extentending ==
By adding navigaition type of modules to you airframe your flightplan options can be massively extended.
[[Advanced_Navigation_Routines|Take a look on this page to see which modules are on offer]]
In case all the basic options and modules still do not let you fly autonomous like you want to, nothing prevends you from creating andother nav module. Before you set out on that task, make sure that there really is no way or module that can make your wanted behaviour a reality.
== Examples ==
Take a good look at other flight plans included with Paparazzi, you can learn a lot from them. Be sure to also visit the [[Flight_Plan_Examples|flight plan examples]] page to enhance your knowledge on flightplans.
== 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>
</source>


Line 485: Line 632:
* 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>
* 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]].
* 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.
* 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]]
[[Category:Software]] [[Category:User_Documentation]]

Latest revision as of 16:08, 4 May 2021

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

Extract from the DTD:

<!ELEMENT flight_plan (header?,waypoints,sectors?,variables?,includes?,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 home_mode_height qfu alt max_dist_from_home>
name
The name of the mission (a text string)
lat0, lon0
Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
ground_alt
The ground altitude (in meters), Above Sea Level where you are flying. It defines the GROUND_ALT constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
security_height
The height (over ground_alt) 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 security_height (usually the case for the landing point)
home_mode_height (optional)
This optional attribute available since v4.2 allows to override security_height as failsafe height in home mode. If home_mode_height Is set lower than security_height, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
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
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:

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

Note that a flight plan could also contain optional include's and exceptions 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:

 <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 is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined alt parameter of the flightplan. The height attribute can be used to set the waypoint height relative to the ground altitude (ground_alt) of the flight plan for this waypoint.

An example:

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

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.
  • A waypoints index/reference pointer is derived by prefixing the waypoint name with "WP_". Useful when a call function uses the waypoints reference index vs. it's name.

Sectors

Flat Sectors can be described as an area defined by a 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. For a sector named MyBigGarden the generated function for the example here would be bool_t InsideMyBigGarden(float x, float y); where x and y are east and north coordinated, in meters, relative to the geographic reference of the flight plan. Note that sector names are not allowed to contain spaces.

Note: The edges of the polygon should not cross each other.

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

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


It is then possible to add an exception clause to your flightplan. 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 MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:

 <exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>

Tip: The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

Before version 6.0

Before version 6.0, there was "static" and "dynamic" sectors. The default type of a sector was "static", except if the extra attribute type="dynamic" was added.

Static sectors have these limitations:

  • The polygon need to be convex and described in a clockwise order.
  • If the flight plan is dynamically relocated, such a sector will be relocated but the display is not updated on the GCS.
  • editing of the waypoints of the sector during the flight do not dynamically update the inside function. It will always check if the position is inside the original sector.


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 setting.

The following code will produce a float variable initialized to 0:

  <variables>
    <variable var="my_var"/>
  </variables>

The type and the initial value can be changed with the type and init attributes:

  <variables>
    <variable var="my_var" init="10" type="int"/>
  </variables>

To produce an automatic setting for a variable, at least min, max and step attributes need to be specified:

  <variables>
    <variable var="my_var" min="0." max="10." step="0.1"/>
  </variables>

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:

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

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|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>

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 internal variables section below and other examples)
  • Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
  • Some utility functions
  • Since some operators are not very compliant with the XML specifications (especially '<'), you can use some alternate naming:
    • @LT (less than, <)
    • @GT (greater than, >)
    • @LEQ (less or equal, <=)
    • @GEQ (greater or equal, >=)
    • @AND ( && )
    • @OR ( || )
    • @DEREF ( -> )

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.

  <blocks>
    <block name="Wait GPS">
      <set value="1" var="kill_throttle"/>
      <while cond="!GpsFixValid()"/>
    </block>

The second block updates the local waypoints with respect to the UAV.

    <block name="Geo init">
      <while cond="LessThan(NavBlockTime(), 10)"/>
      <call fun="NavSetGroundReferenceHere()"/>
    </block>

This next block prevents the UAV from starting the engine and taking off.

    <block name="Holding point">
      <!--set var="nav_mode" value="NAV_MODE_ROLL"/-->
      <set value="1" var="kill_throttle"/>
      <attitude roll="0" throttle="0" vmode="throttle"/>
    </block>

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 > GetPosAlt())" deroute="go_up"/>
  <exception cond="(autopilot_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.

Return

The return is also a goto directive that brings you back to the last block (and last stage). It has no argument.

<return/>

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, letting 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 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 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="(GetPosAlt() > 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"/>

Path

The path primitive is just a shorthand expression for a set of go primitives. A list of waypoints defined with the wpts attribute is pre-processed into a set of go primitives with the hmode attribute. For example:

<path wpts="wp1, wp2, wp3"/>

Other attributes are optional:

<path wpts="wp3, wp1, wp2" approaching_time="1" pitch="auto" throttle="0.5"/>

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+(GetPosAlt()-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/>

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.

 <oval p1="1" p2="2" radius="nav_radius"/>

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.

  <eight center="1" radius="nav_radius" turn_around="2"/>

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.

  <survey_rectangle wp1="1" wp2="2" grid="200" orientation="NS"/>

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

Stay

The stay 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,stay will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.

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

Abide

The abide 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,stay will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.

<abide wp="SAMPLEME" alt="95"/>

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

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_setup()"/>
  <call fun="nav_line_run(WP_1, WP_2, nav_radius)"/>

where nav_line_setup() returns FALSE and nav_line_run() always returns TRUE (this stage never ends). Note that a waypoints index is derived/denoted by prefixing the waypoint name with WP_(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 loop="FALSE"

  <call fun="viewvideo_take_shot(TRUE)" loop="FALSE"/>

or use the call_once alias:

  <call_once fun="viewvideo_take_shot(TRUE)"/>

Such extra navigation functions are usually written as a 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

  <header>
#include "path/to/header.h"
  </header>

where the path is relative to the sw/airborne 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).

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

Pre Call

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

Post Call

 <block name="traj" pre_call="formation_pre_call()" post_call="formation_flight()"> <!-- formation flight is call after all other navigation tasks -->

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(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
      </block>
      ...
    </blocks>
  </procedure>

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>

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)
  • ground_alt: altitude above ground level in meter (float) (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 state interface API
  • all functions from the waypoint API
  • all variables declared in modules headers

Extentending

By adding navigaition type of modules to you airframe your flightplan options can be massively extended.

Take a look on this page to see which modules are on offer

In case all the basic options and modules still do not let you fly autonomous like you want to, nothing prevends you from creating andother nav module. Before you set out on that task, make sure that there really is no way or module that can make your wanted behaviour a reality.

Examples

Take a good look at other flight plans included with Paparazzi, you can learn a lot from them. Be sure to also visit the flight plan examples page to enhance your knowledge on flightplans.

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>

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

<call_once fun="gh_set_max_speed(2.0)"/>

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

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">
  • 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.

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.