PaparazziUAV - User contributions [en]

Sensors/GPS

2010-05-09T08:29:28Z

Nathan: /* GPS configuration using U-Center */

{| align=right
|-
| __TOC__
|}

==Overview==
[[Image:U-blox_color_warm_60.gif|100px]]

Paparazzi autopilots are designed around the popular [http://www.u-blox.com u-blox] brand of receivers.

*Features:
**Small size
**Excellent performance
**4Hz position update rate

The '''[[Tiny]]''' features an onboard LEA series GPS receiver and patch antenna, while '''[[Classix]]''' and '''[[Previous_Autopilots|AVR-based]]''' boards require an external receiver+antenna such as the [[#Paparazzi_Stand-alone_GPS_Receivers|Paparazzi GPS]] or [[#u-Blox_SAM-LS_GPS_Smart_Antenna|SAM-LS]]. Please note that the receivers must be configured (prior to use with the autopilot) as indicated below. Both modules have proven reliable and robust.

{|align = center
|-
|[[Image:Lea big.jpg|200px|thumb|center|u-blox LEA GPS Receiver]]
|[[Image:Ublox_SAM-LS.jpg|200px|thumb|center|u-blox SAM-LS GPS receiver (w/built-in Smart Antenna)]]
|}

'''Note:''' The proprietary UBX protocol is used as it offers more information and efficiency than the universal NMEA protocol. The protocol is parsed in <tt>sw/airborne/gps_ubx.c</tt>. Other GPS brands would require a similar parsing file to be written for NMEA or other proprietary protocols.

==GPS Receivers==

===u-Blox LEA Series Receivers===
[[Image:Lea big.jpg|100px|thumb|right|u-blox LEA]]
The '''[[TWOG_v1|TWOG]]''', '''[[Classix]]''' and '''[[Previous_Autopilots|AVR-based]]''' boards require an external GPS module and antenna. The '''[[Tiny]]''' features an integrated receiver and antenna. Either type is designed for [http://www.u-blox.com/ u-blox] 4 and 5 series GPS receivers and the proprietary UBX binary protocol. An external battery or capacitor is typically used to enable the GPS to retain data while powered off for significantly faster signal re-aquisition. Any of the LEA-4 and LEA-5 series receivers can be used including the less expensive LEA-4A, 4S, 5A and 5S models as the special boot configuration code required for these models is already written.

*4Hz Position update rate
*Supports active or passive antennas
*Supports [http://en.wikipedia.org/wiki/DGPS DGPS], [http://en.wikipedia.org/wiki/WAAS WAAS], [http://en.wikipedia.org/wiki/EGNOS EGNOS], and [http://en.wikipedia.org/wiki/MSAS MSAS]
*Low position [http://paparazzi.enac.fr/wiki_images/Gps_rx_noise.pdf noise] figure
[[Image:Lea5htiny13.jpg|thumb|center|250px|LEA-4P installed on the Tiny]]
 

===Paparazzi Stand-alone GPS Receivers===
<gallery>
Image:Ppzgps13med01.jpg|Top
Image:Ppzgps13_lrg_02.jpg|Bottom
</gallery>
Paparazzi CVS provides a design for an external GPS board (required for TWOG and Classix Autopilots).
Programming it is similar to the Tiny2.11 GPS configuration. If you build your own you will want to upload the latest u-blox firmware before you configure. See "Getting Hardware" for sources of assembled boards.

The Paparazzi design in http://cvs.savannah.gnu.org/viewcvs/paparazzi/paparazzi3/hw/sensors/gps_13.brd is based on a u-blox LEA-4P however an LEA-5H seems to work just fine as well. The board is very small and light as it has only the components required. It is powered from the 5v line on the "downloads" connector of a TWOG. Also note it is a 4-layer PCB that means better noise resistance. The board has pins for USB connection but requires a different cable and a solder jumper to be move from the ground (default) to 3.3v input to enable the USB port on the module.


[http://paparazzi.enac.fr/wiki_images/Gps_13_BOM.xls V1 BOM.xls] 
[http://paparazzi.enac.fr/wiki_images/TinygpsBOM.txt Eagle Parts List Output.txt] 
See [[Get_Hardware|Get Hardware]] page for suppliers.

==== Wiring Diagram ====
[[Image:TWOG to GPS.jpg|thumb|left]]
 

----

===3rd Party u-blox reference design boards:===

[[Image:LEA5HExternalModulePinout.jpg|100px|thumb|right|LEA-5H Full Board Pinout]]
The only other GPS board in use seems to be u-blox reference designs or similar to it. They have either LEA-4P or LEA-5H (typically) and several interfaces. Often a larger antenna as well.


If this needs fixing don't be shy, fix away.

 

===NAVILOCK NL-507ETTL===
[[Image:Navilock NL-507ETTL.jpg|thumb|left|NAVILOCK NL-507TTL]]
The NAVILOCK NL-507TTL u-blox TTL Modul 60416 features an LEA-4 series receiver and 25mm patch antenna on a 30mm x 30mm board.
* Datasheet: [http://www.navilock.de/download/Dokumente_SLASH_Sonstiges/60415_-_Datenblatt_u-blox_GPS_Module/481 http://www.navilock.de/download/Dokumente_SLASH_Sonstiges/60415_-_Datenblatt_u-blox_GPS_Module/481]
* Purchase: Available for 28€ at [http://www.amazon.de/Navilock-NL-507TTL-u-blox-TTL-Modul/dp/B0011E6VQG www.amazon.de]
 

===SPK GS406===
[[Image:GS406.jpg|thumb|left|SPK GS406 with LEA-5]]
[http://www.sparkfun.com/commerce/product_info.php?products_id=8889 Sparkfun] sells a nice small module featuring the newer 5-series receiver and the highly rated Sarantel antenna for about $90. The design is based around the active version of the Sarantel instead of the more appropriate passive model and there's some potentially tricky soldering involved to get around the ribbon cable but the price is great for this hardware.

[http://store.diydrones.com/ProductDetails.asp?ProductCode=BR-0008-01 DIYDrones] has build a adapter board for this GPS module. It looks like a great solution to use this GPS module with Paparazzi.
 

===u-Blox C04-5H Reference Design===
[[Image:abavimage.jpg|100px|thumb|left|u-blox C04-5H]]
u-Blox sells a complete module with antenna for around $200 and will also provide complete schematics, BOM, and PCB files for free if you wish to make your own. Two versions are offered, one with an 18mm patch antenna and the other with the Sarantel P2 helical antenna.
See [http://www.u-blox.com/products/c04_5h.html http://www.u-blox.com/products/c04_5h.html] for more info.
 

====Connecting external receivers to Classix, 1.2.1, Lite, and RoboStix boards====

The u-blox receivers require 3.3v power and all current models have 5V tolerant data lines. The best way to connect to the SAM-LS is to remove the bottom case and solder the 4 wires directly to the TIM-LL module (GND (pin 1) ,VCC (pin 2),TX (Pin 5),RX (pin 4)) check the TIM-LL datasheet for pinout diagrams.[http://www.u-blox.com/products/Data_Sheets/TIM-LL_Data_Sheet(GPS.G3-MS3-04035).pdf] The Classix and Lite boards feature a 3.3V regulator to power the GPS.
To open the casing on a SAM-LS, remove the bottom of the casing by pulling gently, then work around popping off the solder joints (they are fairly weak) by pressing a small screwdriver against each tab in turn until it pops off. You should then be able to access the GPS chip directly.

===Sourcing from u-blox===

u-blox keeps tight control over the distribution of their products. They must be obtained DIRECTLY from their own reseller offices. These offices may not be available in your area, for example Canada does not have a reseller. Sample quantities can be obtained from uBlox but overnight or 2 day shipping is required which drives the cost up considerably. While it is a large hassle obtaining these devices, it is undoubtedly worth it.

Talking with ublox sale for two years, Confirmed, that Order is possiable Directly from ublox, by knowing what project it was for & how was it to be use. After long reply waiting time, the answer was: - YES, but at least 2K-3K in volume, otherwise they're not interested. Like to share the order ? It is 500pcs/Roll.

===Other potential source of u-blox GPS===

There seems to be a few alternative source of u-blox GPS out there. They are considerably cheaper then the samples u-blox offers (at least in america). We didn't buy from these sources yet. Do not take this as a recommandation, we do not know the level of service they offer, etc.

If you do order from any of them, please update this page with your feedback.

Here's a few link worth exploring:
*http://www.rfdesign.co.za/pages/5645456/Products/GPS-Products/Antaris-4-Modules.asp
*http://www.comet.srl.ro/shop/info.html?ID=6195 ( Link error )
*http://www.expedienttech.com/product.htm ( Singapore )

==GPS configuration using U-Center==

[[Image:U-center_screencap.jpg|thumb|u-center configuration software]]
[http://www.u-blox.com/products/u_center.html U-Center] is a very comprehensive freeware program intended for the configuration and evaluation of u-blox receivers.
* [http://www.u-blox.com/en/evaluation-tools-a-software/u-center/u-center.html Download u-center]

* Note 1: You must [[Compiling#USB_flashing|install the UART tunnel]] to enable direct access to the built-in GPS on the [[Tiny|Tiny]].

* Note 2: You will need a driver for your FTDI cable if you run u-center on Windows, which can be found [http://www.ftdichip.com/Drivers/D2XX.htm here].

* Note 3: You can run u-center on Linux by installing "Wine" ([http://www.winehq.org/site/download-deb Installation of Wine]) and set up COM1 as /dev/ttyUSB0. You need to create a symbolic link from the COM device to TTY like this:
ln -s /dev/ttyUSB0 ~/.wine/dosdevices/COM1

or what worked in Ubuntu 9.10

ln -s /dev/ttyUSB0 ~/.wine/dosdevices/com1
This command will create the symbolic link from ttyUSB0 to COM1. See Info on Wine for "dosdevices" setup. Just download the u-setup.exe and run it with Wine, follow prompts. This has been tested with Ubuntu7.10 and Ubuntu 8.04 so far.

The u-blox and Tiny UARTs both operate at 3.3V TTL levels and are 5V TTL tolerant. You must use a level shifter such as the common MAX232 to connect these devices to a standard PC serial port. The easiest and most recommended method is to connect to a USB port instead of serial with the $20 [http://www.ftdichip.com/Products/EvaluationKits/TTL-232R.htm FTDI USB-TTL converter cable] available from Digikey, Mouser, or direct from FTDI. Other similar converters are available from [http://www.pololu.com/products/pololu/0391/ pololu] / [http://www.sparkfun.com/commerce/product_info.php?products_id=199 sparkfun]. A stand-alone GPS such as the SAM-LS will require clean 3.3V/50mA power and a common ground with the TTL converter.

* U-blox occasionally releases firmware updates. Log on to the u-blox website using ''paparazzi'' for username & password to view or download the latest firmware images. There have 'never' been any updates released for the Antaris-4 series used in the Tiny.

Start U-center and choose your com port from the pull down list under the connect button near the top left corner of the window. Choose your baudrate from the pull down box to the right of the connect button or select the auto-baud button to the right of that. U-blox default is 9600 baud. This must be changed to 19200 or higher to accomodate the 4Hz update rate.
 [[Image:U-center_buttons.jpg|connect, baud, and autobaud buttons]]
 

===Uploading the Configuration File===
Download the appropriate configuration file below and use u-center to load in onto your receiver. Under the ''Tools'' menu, choose ''GPS configuration''. Be sure the box 'Store configuration into BBR/Flash' is checked and hit the button ''File>>GPS''. A few errors and retries are normal, but a significant number of errors may indicate a poor connection and the software will notify you if it is unable to send all the data successfully.
* [[Media:Tiny_LEA-4P-v6.zip|LEA-4P]]
* [[Media:Tim-LL-V5.zip|TIM-LL]]
* [http://paparazzi.enac.fr/wiki_images/Tiny_LEA-5H-v5.zip LEA-5H (For Use w/ Firmware V5 ONLY!)]

===Manual Configuration===
If you prefer to setup your receiver manually or have a model not listed above, here are instructions to configure your receiver in u-center.
Open the message window (menu View->messages view) to start the configuration process by changing the following settings:

====LEA-4P====

1. Right Click on the '''NMEA''' Icon and choose '''disable child'''
2. Choose UBX->CFG->NAV2(Navigation 2) - set it to use '''Airborne 4G''' (tells the Kalman filter to expect significant changes in direction)
3. UBX->CFG->PRT - set '''USART1''' to '''38400bps''' (must match the value in your [[Airframe_Configuration#Hardware_definitions_-_Makefile|Airframe file]])
4. Change the baudrate of U-Center to 38400bps if the connection is lost at this point
5. UBX->CFG->RXM(Receiver Manager) - change '''GPS Mode''' to '''3 - Auto''' (Enabling faster bootup only if signal levels are very good)
6. UBX->CFG->RATE(Rates) - change the '''Measurement Period''' to '''250ms''' (4 Hz position updates)
7. UBX->CFG->SBAS : '''Disable''' (SBAS appears to cause occasional severe altitude calcuation errors)
8. UBX->NAV (not UBX->CFG->NAV): double click on '''POSUTM, SOL, STATUS, SVINFO, VELNED.''' They should change from grey to black
9. UBX->CFG->CFG : '''save current config''', click '''"send"''' in the lower left corner to permanently save these settings to the receiver

====LEA-5H====

1. Right Click on the '''NMEA''' Text on top of the tree and choose '''disable child messages'''
2. Choose UBX->CFG->NAV5(Navigation 5) - set it to use '''Airborne 8 <4G'''. This tells the Kalman filter to expect significant changes in direction.
Note that this setting is only good for faster moving airplanes. For a fixed position hovering heli, 'pedestrian' setting is better
3. UBX->CFG->PRT - set '''USART1''' to '''38400bps''' (must match the value in your [[Airframe_Configuration#Hardware_definitions_-_Makefile|Airframe file]])
4. Change the baudrate of U-Center to 38400bps if the connection is lost at this point
5. UBX->CFG->RATE(Rates) - change the '''Measurement Period''' to '''250ms''' This gives a 4 Hz position update since 4 x 250ms is one second.
6. UBX->CFG->SBAS : '''Disable''' (SBAS appears to cause occasional severe altitude calcuation errors)
7. UBX->NAV (not UBX->CFG->NAV): double click on '''POSLLH, SOL, STATUS, SVINFO, VELNED.''' They should change from grey to black
(add the flag -DGPS_USE_LATLONG in your [[Airframe_Configuration#Hardware_definitions_-_Makefile|Airframe file]]) also make sure you set tiny_2_1_1.h if you have the latest boards Tiny/TinyWOG)
8. UBX->CFG->CFG : '''save current config''', click '''"send"''' in the lower left corner to permanently save these settings to the receiver

* Cycle the power and verify that the new configuration was saved
* To reset the receiver to the factory defaults go to ''UBX->CFG->CFG'', select 'Revert to default configuration', and click ''Send'' at the bottom left corner. To permanently save these values choose 'Save current configuration' and click ''Send''.
* To backup the configuration to a file on your PC: under the tools menu, choose GPS configuration, then click GPS>>file. This file can be re-loaded in a similar manner to configure additional identical receivers. Be sure the box 'Store configuration into BBR/Flash' is checked when reloading a configuration file to make the changes permanent.
* To update the firmware on a LEA-5H get u-center >= 5.03, revert the GPS receiver to the default configuration, get an appropriate image from u-blox (fitting your receivers serial number), find the flash identification flash.txt file in the u-center install directory and be prepared to wait a long time.

#NOTE: If you have a Tiny with LEA-5H module you must use u-center and manually setup the parameters as shown above (at least switch to 38400 baud manually before transferring the configuration file).
#NOTE: POSUTM is not available on LEA-5H. Instead, use POSLLH. Additionally, add the flag -DGPS_USE_LATLONG in the makefile section of the airframe xml file.

===Reset to Default Settings===
The GPS module can be reset to its original default settings by pulling BOOT_INT high(3.3V) during a power cycle ([http://www.u-blox.com/customersupport/gps.g4/ANTARIS4_Modules_SIM(GPS.G4-MS4-05007).pdf Antaris Manual, p. 122]). It may be required after a wrong firmware upgrade or a bad configuration change.

===DGPS (Differential GPS)===
Differential GPS is any method of improving GPS accuracy by comparing the GPS-indicated position of a nearby location to the known value and transmitting any error to the mobile unit. DGPS was originally created as a means of bypassing the deliberately introduced inaccuracies in civilian GPS signals. The original method used low frequency ground radios to relay correction data to the mobile unit and is still used today at airports, shipping ports, and even individual farms. Satellite Based Augmentation System (SBAS) is a modern form of DGPS where the ground stations relay correction data to a GEO-Stationary satellite, which then relays it to the mobile unit on standard GPS frequencies eliminating the need for a separate radio reciever. SBAS is currently available in 3 regions, [http://www.esa.int/esaNA/ESAF530VMOC_egnos_1.html WAAS, EGNOS, and MSAS regions] though only WAAS and EGNOS are officially operational. U-blox receivers support all common varieties of DGPS [http://www.u-blox.com/customersupport/gps.g3/ENGOS_Issues(GPS.G3-CS-04009).pdf read the u-blox SBAS application note].
* It is important to note that DGPS methods only improve the ''accuracy'' of the position calculation, not the ''precision''. Since Paparazzi navigation is typically performed relative to the power-on location, any static error that could be corrected with DGPS is irrelevant.

====WAAS issues====
WAAS has been officially operational and "suitable for safety-of-life applications" since 2003. The default setting of all u-blox receivers ignores WAAS correction data and only uses the WAAS satellites for regular navigation like any other satellite. U-blox recommends further limiting this setting to exclude any stray EGNOS/MSAS satellites in North America, and completely disabling all SBAS functions for use outside North America. In 2006 one formerly reliable Paparazzi aircraft began having great GPS problems and displaying very erratic altitude calculations, disabling WAAS immediately resolved the issue and this phenomenon was recreated several times for verification. Turns out a new WAAS satellite was being added to the system and the others were being moved that week for better distribution. Our advice is to completely disable WAAS.

====EGNOS issues====
EGNOS officially became operational on 1 October 2009. ESA claims that it can determine position to within 2 metres compared with about 20 metres for GPS alone. Note that the service is currently provided only in western Europe. For further information see [http://www.esa.int/esaNA/egnos.html ESA EGNOS website].

According to the [http://ec.europa.eu/transport/egnos/programme/doc/2009_egnos_sdd_os_v1.pdf EC] the EGNOS transmission will keep the "Do not use" type0/2 flag until it is certified for safety of life operations in (hopfefully) mid 2010. So you will have to enable the "Allow test mode use (Msg 0)" switch in the u-center under UBX-CFG-SBAS together with the correction to try EGNOS.

The [http://www.u-blox.com/en/faq.html u-blox FAQ] states the following:
* "Do you see issues with EGNOS?"
*:"Yes. The data transmitted by EGNOS in the past were usually good and valuable although sometimes unreliable, e.g. when system tests were performed. u-blox does not guarantee performance and status of EGNOS system. For the latest update about functionality of EGNOS please check the website: [http://www.gsa.europa.eu European GNSS Supervisory Authority]"

===Troubleshooting===

Problem: I keep getting this error with my nice shiny Tiny v2.1 with a LEA-5H:
Invalid_argument("Latlong.of_utm")

Solution: Add the flag -DGPS_USE_LATLONG to your airframe file.

===Further Reading===

The u-blox [http://www.u-blox.com/customersupport/antaris4_doc.html System Integration Manual] covers a lot of GPS theory as well as product specific topics.

== Antenna options for the Tiny and Paparazzi GPS units ==

The '''[[Tiny|Tiny 1.1]]''' features a 28mm square ground plane intended to be centered below the [[#Sangshin_13mm_Patch|Sangshin 13mm patch antenna]]. Much better performance has been seen with the 18mm antennas and an augmented ground plane. The ground plane is a critical part of the antenna affecting not only the gain and polarization characteristics but also the center frequency of the system. Users are advised to expand the ground plane to approximately 36mm square, centered on the ceramic portion of the antenna (not the pin). This can be done with copper foil soldered to the vias of the existing ground plane.
[[image:gps_antenna_comparison.jpg|thumb|500px|left|SAM-LS 25mm / Emtac 20mm / Emtac 18mm / Sangshin 18mm / Sangshin 13mm / Sarantel P2]]
 

=== Sangshin 18mm Patch ===
[[image:Sangshin_18mm.jpg|thumb|Sangshin 18mm x 4mm 1580Mhz]]
The Sangshin KSA-ST1580MS18 antenna has proven to offer the best performance of the currently available options. These are available from any Sanshin distributor such as [http://www.rfmw.com rfmw] ([http://www.rfmw.com/PortalProductDetail.aspx?ProdId=232436&fmt=1 here]) and cost approximately $6.50/ea. in small quantities.

 

=== EMTAC 18mm Patch ===
[[image:Emtac_18mm.jpg|thumb|Emtac 18mm x 4mm 1580Mhz]]
Offering identical performance to the Sangshin in a less attractive package is the Emtac 18mm antenna. The part number for the standard 1580MHz 18x18x4mm is ANA1580T18D40 and is not listed on their website. Other frequencies are available on a special order basis and the 1584Mhz has proven to outperform all other frequencies when used with a 36mm ground plane and no radome. The use of a radome (any material covering the antenna) or a larger ground plane should theoretically favor even higher frequencies.

'''Availability'''

* [http://www.transplantgps.com/modules.html TransplantGPS] in MN, USA. The 1580Mhz models are usually available at a cost of $3.55ea but there may be a minimum order requirement of ~$50 USD.

=== Sangshin 13mm Patch ===

[[image:Sangshin_13mm_onboard.jpg|thumb|Sangshin 13mm x 4mm 1580Mhz]]
Part of interest: '''[http://www.sangshinec.com/eng/patch_spec.htm KSA-ST1580MS13]'''

The Tiny 0.99 (not 0.9) and 1.1 were designed around this antenna but users are advised to install 18mm units for better performance.

Size: 13 x 13 mm 
Center Frequency: 1580 MHz 
Bandwidth: 5 MHz 
@Fo: -15 dB 
GAIN (dBi): 0 dBi 
Ground Plane: 50 x 50 mm 

'''Available From'''

[http://www.systroninc.com/ Systronic INC.] - Alberta, Canada
 

=== Emtac 20mm Patch ===

[[image:Salvaged_20mm_onboard.jpg|thumb|Emtac 20mm x 4mm]]
The Tiny 0.9 was designed around this 1583Mhz antenna and performed extremely well. Emtac has replaced this with an 18mm model that they claim offers even better performance.

* Obsolete
 

=== Spectrum Control Patch ===

[[image:PDC_Tiny21_S1.jpg|thumb|Spectrum Control 25mm]]
25mm patch testing on Tiny v2.1. Manufacturer Part Number [http://www.specemc.com/docs/antenna_catalog.pdf PA251575008SALF]. These are available from Mouser for about $3: [http://www.mouser.com/Search/ProductDetail.aspx?qs=sGAEpiMZZMukjKvgqb7HxzmcutVCLrkxFUj/3HCdKwE%3d 657-PA251575008SALF]

 

=== Sarantel GeoHelix-P2 ===

[[image:Geohelix-p2.jpg|thumb|Sarantel Geohelix P-2 1575Mhz]]

This antenna is popular among UAV designers due to it's natural rejection of other radio frequencies such as those originating from the modem or video system as well as it's improved rejection of signals reflected from the ground. U-blox recommends this antenna and features it in their [http://www.u-blox.com/news/sarantel.html reference design]. Frequency and polarization are not dependent upon ground plane geometry so this antenna is sold only in the true GPS frequency of 1575Mhz.
The geometry makes this antenna very inconvenient to mount, especially in an airplane. Some very non-scientific testing has been done with one of these antennas connected to a Tiny with a short length of 50 Ohm coax above a 120mm square of ungrounded aluminum foil and performance was adequate. The helical design should theoretically outperform a patch in the air, but not on the ground, so any organized comparison will be difficult. Possibly the most important aspect of this antenna is it's natural RFI filtering, which should be evaluated further.

* [http://www.sarantel.com/products/geohelix-p2 GeoHelix-P2] Passive GPS Antenna [[http://www.sarantel.com/downloads/specifications/geohelix-p2.pdf datasheet]]

'''Availability'''

* Sarantel @ cost of approx $18 USD each (active versions available for ~$40)

Flight Plan Examples

2010-05-03T13:13:05Z

Nathan: /* Surveying an area */

This page will detail a number of flight plan examples.

== Takeoff ==

The block of code:

<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
</block>

Below is an explanation of the code - left to right, top to bottom.

Not sure what this does - SOMEONE PLEASE UPDATE
key="t"

the name of the block
name="Takeoff"

This shows as the name when you hover your mouse over the button
strip_button="Takeoff"

The name of the icon picture shown in the GCS
strip_icon="takeoff.png"

This turns on the option to change the throttle
<set value="0" var="kill_throttle"/>

This turns on the flight time estimator
<set value="0" var="estimator_flight_time"/>

<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
This says for the aircraft to go from "START" waypoint towards "ER" (end runway) waypoint with a elevator pitch of -10% (to keep the aircraft on the ground) and throttle at 100%. You would also add a deroute option to change to the "CLIMB" waypoint (the waypoint that gets the aircraft up to the correct height) once the aircraft was moving above stall speed. I will add the code for this soon. I am not sure what vmode="throttle" means SOME PLEASE UPDATE.

This code will work in theory, but may not in practice, especially if you only have a narrow runway or your aircraft takes a long time to get up to speed. This is because the autopilot is not exact in its estimation of where it is.

== Surveying an area ==

There are two types of survey, two waypoint survey or Polysurvey. PolySurvey can be called multiple times during a flight plan but I am not sure how to do this (SOMEONE PLEASE UPDATE).

<block name="Initialize Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
</block>

<block name="Run Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

You will notice that there are two blocks of code instead of a single block. This because when you are surveying an area you may want to stop the survey and take a closer look at something (for instance you may wish to circle something of interest). If you want to continue the survey from the point where you stopped to look closer at the thing of interest all you need to do is call the "Run Poly Survey" block.

<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
This initializes the PolySurvey starting with Waypoint S1 and using 5 waypoints (in sequence, eg S1, S2, S3, S4, S5), with a distance between each survey line of 150 meters and an angle of survey of 45 degrees from the initial waypoint.

<call fun="PolygonSurvey()"/>
This calls the PolySurvey, you may want to call this either via a button on the GCS or by calling it in external code for example an automated IR sensor (if you are looking for a person).

== Landing your aircraft ==

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<go from="AF" hmode="route" vmode="glide" wp="TD"/>
</block>

Above is the final Block. This block is used to bring the aircraft towards the end of the runway (or landing area) which is the "AF".

<go from="AF" hmode="route" vmode="glide" wp="TD"/>
Fly from waypoint "AF" to waypoint "TD" and glide between them to maintain the angle between them. You may want these two waypoints to be a significant distance between them if you want the aircraft to come in on a very shallow angle.

<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
"flare" is the deroute condition and it is implemented when the aircraft is 10 meters from the ground.

<block name="flare">
<go approaching_time="0" from="AF" hmode="route" throttle="0.0" vmode="throttle" wp="TD"/>
<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
</block>

You would want the aircraft to flare just before hitting the ground. If your aircraft is not very stable at low speeds you may want to make the distance above ground lower.

<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
I have not idea what the above means other than the throttle part. SOMEONE PLEASE UPDATE.

Flight Plan Examples

2010-05-03T13:01:41Z

Nathan: /* Landing your aircraft */

This page will detail a number of flight plan examples.

== Takeoff ==

The block of code:

<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
</block>

Below is an explanation of the code - left to right, top to bottom.

Not sure what this does - SOMEONE PLEASE UPDATE
key="t"

the name of the block
name="Takeoff"

This shows as the name when you hover your mouse over the button
strip_button="Takeoff"

The name of the icon picture shown in the GCS
strip_icon="takeoff.png"

This turns on the option to change the throttle
<set value="0" var="kill_throttle"/>

This turns on the flight time estimator
<set value="0" var="estimator_flight_time"/>

<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
This says for the aircraft to go from "START" waypoint towards "ER" (end runway) waypoint with a elevator pitch of -10% (to keep the aircraft on the ground) and throttle at 100%. You would also add a deroute option to change to the "CLIMB" waypoint (the waypoint that gets the aircraft up to the correct height) once the aircraft was moving above stall speed. I will add the code for this soon. I am not sure what vmode="throttle" means SOME PLEASE UPDATE.

This code will work in theory, but may not in practice, especially if you only have a narrow runway or your aircraft takes a long time to get up to speed. This is because the autopilot is not exact in its estimation of where it is.

== Surveying an area ==

There are two types of survey, two waypoint survey or Polysurvey. PolySurvey can be called multiple times during a flight plan but I am not sure how to do this (SOMEONE PLEASE UPDATE).

<block name="Initialize Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
</block>

<block name="Run Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

You will notice that there are two blocks of code instead of a single block. This because when you are surveying an area you may want to stop the survey and take a closer look at something (for instance you may wish to circle something of interest). If you want to continue the survey from the point where you stopped to look closer at the thing of interest all you need to do is call the "Run Poly Survey" block.

<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/> - This initializes the PolySurvey starting with Waypoint S1 and using 5 waypoints (in sequence, eg S1, S2, S3, S4, S5), with a distance between each survey line of 150 meters and an angle of survey of 45 degrees from the initial waypoint.

<call fun="PolygonSurvey()"/> - This calls the PolySurvey.

== Landing your aircraft ==

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<go from="AF" hmode="route" vmode="glide" wp="TD"/>
</block>

Above is the final Block. This block is used to bring the aircraft towards the end of the runway (or landing area) which is the "AF".

<go from="AF" hmode="route" vmode="glide" wp="TD"/>
Fly from waypoint "AF" to waypoint "TD" and glide between them to maintain the angle between them. You may want these two waypoints to be a significant distance between them if you want the aircraft to come in on a very shallow angle.

<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
"flare" is the deroute condition and it is implemented when the aircraft is 10 meters from the ground.

<block name="flare">
<go approaching_time="0" from="AF" hmode="route" throttle="0.0" vmode="throttle" wp="TD"/>
<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
</block>

You would want the aircraft to flare just before hitting the ground. If your aircraft is not very stable at low speeds you may want to make the distance above ground lower.

<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
I have not idea what the above means other than the throttle part. SOMEONE PLEASE UPDATE.

Flight Plans

2010-05-03T12:56:43Z

Nathan: /* See also */

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: 

<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 convex and described in a clockwise order. For a sector named <tt>sector</tt> (sector names must not 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. 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>\

== Building Flight Plans ==

'''Waypoint Settings'''

Many of the flight plan examples here and in the Paparazzi software set waypoint locations using x,y coordinates from the lat/lon in the header of the flight plan. When building flight plans on the fly where there is no requirement to stay within lat/lon boundaries, this is acceptable. When you are building flight plans where you are required to stay within or overfly certain GPS coordinates, using x,y from the lat/lon in the header will not work in real life. When simulating your flight plan the aircraft always starts from the lat/lon in the header. In reality your aircraft will probably start from a different spot each time, meaning your lat/lon coordinates will change each time. If you use the x,y coordinates, then each waypoint will move and your GPS points will not longer be correct

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

== See also==
For example flight plans please see [[Flight_Plan_Examples|Flight_Plan_Examples]]

Flight Plans

2010-05-03T12:55:53Z

Nathan:

Flight Plans

2010-05-03T12:54:33Z

Nathan:

Flight Plans

2010-05-03T12:53:36Z

Nathan:

Flight Plan Examples

2010-05-03T12:51:37Z

Nathan: /* Landing your aircraft */

This page will detail a number of flight plan examples.

== Takeoff ==

The block of code:

<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
</block>

Below is an explanation of the code - left to right, top to bottom.

Not sure what this does - SOMEONE PLEASE UPDATE
key="t"

the name of the block
name="Takeoff"

This shows as the name when you hover your mouse over the button
strip_button="Takeoff"

The name of the icon picture shown in the GCS
strip_icon="takeoff.png"

This turns on the option to change the throttle
<set value="0" var="kill_throttle"/>

This turns on the flight time estimator
<set value="0" var="estimator_flight_time"/>

<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
This says for the aircraft to go from "START" waypoint towards "ER" (end runway) waypoint with a elevator pitch of -10% (to keep the aircraft on the ground) and throttle at 100%. You would also add a deroute option to change to the "CLIMB" waypoint (the waypoint that gets the aircraft up to the correct height) once the aircraft was moving above stall speed. I will add the code for this soon. I am not sure what vmode="throttle" means SOME PLEASE UPDATE.

This code will work in theory, but may not in practice, especially if you only have a narrow runway or your aircraft takes a long time to get up to speed. This is because the autopilot is not exact in its estimation of where it is.

== Surveying an area ==

There are two types of survey, two waypoint survey or Polysurvey. PolySurvey can be called multiple times during a flight plan but I am not sure how to do this (SOMEONE PLEASE UPDATE).

<block name="Initialize Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
</block>

<block name="Run Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

You will notice that there are two blocks of code instead of a single block. This because when you are surveying an area you may want to stop the survey and take a closer look at something (for instance you may wish to circle something of interest). If you want to continue the survey from the point where you stopped to look closer at the thing of interest all you need to do is call the "Run Poly Survey" block.

<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/> - This initializes the PolySurvey starting with Waypoint S1 and using 5 waypoints (in sequence, eg S1, S2, S3, S4, S5), with a distance between each survey line of 150 meters and an angle of survey of 45 degrees from the initial waypoint.

<call fun="PolygonSurvey()"/> - This calls the PolySurvey.

== Landing your aircraft ==

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<go from="AF" hmode="route" vmode="glide" wp="TD"/>
</block>

<block name="flare">
<go approaching_time="0" from="AF" hmode="route" throttle="0.0" vmode="throttle" wp="TD"/>
<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
</block>

When you are landing your aircraft automatically, you need to bring it in very gently plus flare just before you land to bring it in cleanly.
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
"flare" is the deroute condition and it is implemented when the aircraft is 10 meters from the ground. You would want the aircraft to flare just before hitting the ground. If your aircraft is not very stable at low speeds you may want to make the distance above ground lower.

<go from="AF" hmode="route" vmode="glide" wp="TD"/>
Fly from waypoint "AF" to waypoint "TD" and glide between them to maintain the angle between them. You may want these two waypoints to be a significant distance between them if you want the aircraft to come in on a very shallow angle.

<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
I have not idea what the above means other than the throttle part. SOMEONE PLEASE UPDATE.

Flight Plan Examples

2010-05-03T12:45:05Z

Nathan: /* Takeoff */

This page will detail a number of flight plan examples.

== Takeoff ==

The block of code:

<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
</block>

Below is an explanation of the code - left to right, top to bottom.

Not sure what this does - SOMEONE PLEASE UPDATE
key="t"

the name of the block
name="Takeoff"

This shows as the name when you hover your mouse over the button
strip_button="Takeoff"

The name of the icon picture shown in the GCS
strip_icon="takeoff.png"

This turns on the option to change the throttle
<set value="0" var="kill_throttle"/>

This turns on the flight time estimator
<set value="0" var="estimator_flight_time"/>

<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
This says for the aircraft to go from "START" waypoint towards "ER" (end runway) waypoint with a elevator pitch of -10% (to keep the aircraft on the ground) and throttle at 100%. You would also add a deroute option to change to the "CLIMB" waypoint (the waypoint that gets the aircraft up to the correct height) once the aircraft was moving above stall speed. I will add the code for this soon. I am not sure what vmode="throttle" means SOME PLEASE UPDATE.

This code will work in theory, but may not in practice, especially if you only have a narrow runway or your aircraft takes a long time to get up to speed. This is because the autopilot is not exact in its estimation of where it is.

== Surveying an area ==

There are two types of survey, two waypoint survey or Polysurvey. PolySurvey can be called multiple times during a flight plan but I am not sure how to do this (SOMEONE PLEASE UPDATE).

<block name="Initialize Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
</block>

<block name="Run Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

You will notice that there are two blocks of code instead of a single block. This because when you are surveying an area you may want to stop the survey and take a closer look at something (for instance you may wish to circle something of interest). If you want to continue the survey from the point where you stopped to look closer at the thing of interest all you need to do is call the "Run Poly Survey" block.

<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/> - This initializes the PolySurvey starting with Waypoint S1 and using 5 waypoints (in sequence, eg S1, S2, S3, S4, S5), with a distance between each survey line of 150 meters and an angle of survey of 45 degrees from the initial waypoint.

<call fun="PolygonSurvey()"/> - This calls the PolySurvey.

== Landing your aircraft ==

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<go from="AF" hmode="route" vmode="glide" wp="TD"/>
</block>

<block name="flare">
<go approaching_time="0" from="AF" hmode="route" throttle="0.0" vmode="throttle" wp="TD"/>
<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
</block>

When you are landing your aircraft automatically, you need to bring it in very gently.

<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/> - "flare" is the deroute condition and it is implemented when the aircraft is 10 meters from the ground. You would want the aircraft to flare just before hitting the ground. If your aircraft is not very stable at low speeds you may want to make the distance above ground lower.

<go from="AF" hmode="route" vmode="glide" wp="TD"/>

<go from="AF" hmode="route" vmode="glide" wp="TD"/>

Flight Plan Examples

2010-05-03T12:23:01Z

Nathan: /* Takeoff */

This page will detail a number of flight plan examples.

== Takeoff ==

<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
</block>

Explanation of the code - left to right, top to bottom.

key="t"
Not sure what this does - SOMEONE PLEASE UPDATE

name="Takeoff"
the name of the block

strip_button="Takeoff"
This shows as the name when you hover your mouse over the button

strip_icon="takeoff.png"
The name of the icon picture shown in the GCS

<set value="0" var="kill_throttle"/>
This turns on the option to change the throttle

<set value="0" var="estimator_flight_time"/>
This turns on the flight time estimator

<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
This says for the aircraft to go from "START" waypoint towards "ER" (end runway) waypoint with a elevator pitch of -10% (to keep the aircraft on the ground) and throttle at 100%. You would also add a deroute option to change to the "CLIMB" waypoint (the waypoint that gets the aircraft up to the correct height) once the aircraft was moving above stall speed. I will add the code for this soon. I am not sure what vmode="throttle" means SOME PLEASE UPDATE.

This code will work in theory, but may not in practice, especially if you only have a narrow runway or your aircraft takes a long time to get up to speed. This is because the autopilot is not exact in its estimation of where it is.

== Surveying an area ==

There are two types of survey, two waypoint survey or Polysurvey. PolySurvey can be called multiple times during a flight plan but I am not sure how to do this (SOMEONE PLEASE UPDATE).

<block name="Initialize Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
</block>

<block name="Run Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

You will notice that there are two blocks of code instead of a single block. This because when you are surveying an area you may want to stop the survey and take a closer look at something (for instance you may wish to circle something of interest). If you want to continue the survey from the point where you stopped to look closer at the thing of interest all you need to do is call the "Run Poly Survey" block.

<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/> - This initializes the PolySurvey starting with Waypoint S1 and using 5 waypoints (in sequence, eg S1, S2, S3, S4, S5), with a distance between each survey line of 150 meters and an angle of survey of 45 degrees from the initial waypoint.

<call fun="PolygonSurvey()"/> - This calls the PolySurvey.

== Landing your aircraft ==

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<go from="AF" hmode="route" vmode="glide" wp="TD"/>
</block>

<block name="flare">
<go approaching_time="0" from="AF" hmode="route" throttle="0.0" vmode="throttle" wp="TD"/>
<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
</block>

When you are landing your aircraft automatically, you need to bring it in very gently.

<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/> - "flare" is the deroute condition and it is implemented when the aircraft is 10 meters from the ground. You would want the aircraft to flare just before hitting the ground. If your aircraft is not very stable at low speeds you may want to make the distance above ground lower.

<go from="AF" hmode="route" vmode="glide" wp="TD"/>

<go from="AF" hmode="route" vmode="glide" wp="TD"/>

Flight Plan Examples

2010-05-03T12:20:38Z

Nathan:

This page will detail a number of flight plan examples.

== Takeoff ==

<code>
<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/>
</block>
</code>

Explanation of the code - left to right, top to bottom.

key="t" - Not sure what this does - SOMEONE PLEASE UPDATE

name="Takeoff" - the name of the block

strip_button="Takeoff" - This shows as the name when you hover your mouse over the button

strip_icon="takeoff.png" - The name of the icon picture shown in the GCS

<set value="0" var="kill_throttle"/> - This turns on the option to change the throttle

<set value="0" var="estimator_flight_time"/> - This turns on the flight time estimator

<go from="START" pitch="-10" throttle="1.0" vmode="throttle" wp="ER"/> - This says for the aircraft to go from "START" waypoint towards "ER" (end runway) waypoint with a elevator pitch of -10% (to keep the aircraft on the ground) and throttle at 100%. You would also add a deroute option to change to the "CLIMB" waypoint (the waypoint that gets the aircraft up to the correct height) once the aircraft was moving above stall speed. I will add the code for this soon.

I am not sure what vmode="throttle" means SOME PLEASE UPDATE.

This code will work in theory, but may not in practice, especially if you only have a narrow runway or your aircraft takes a long time to get up to speed.

== Surveying an area ==

There are two types of survey, two waypoint survey or Polysurvey. PolySurvey can be called multiple times during a flight plan but I am not sure how to do this (SOMEONE PLEASE UPDATE).

<block name="Initialize Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/>
</block>

<block name="Run Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

You will notice that there are two blocks of code instead of a single block. This because when you are surveying an area you may want to stop the survey and take a closer look at something (for instance you may wish to circle something of interest). If you want to continue the survey from the point where you stopped to look closer at the thing of interest all you need to do is call the "Run Poly Survey" block.

<call fun="InitializePolygonSurvey(WP_S1, 5, 150, 45)"/> - This initializes the PolySurvey starting with Waypoint S1 and using 5 waypoints (in sequence, eg S1, S2, S3, S4, S5), with a distance between each survey line of 150 meters and an angle of survey of 45 degrees from the initial waypoint.

<call fun="PolygonSurvey()"/> - This calls the PolySurvey.

== Landing your aircraft ==

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<go from="AF" hmode="route" vmode="glide" wp="TD"/>
</block>

<block name="flare">
<go approaching_time="0" from="AF" hmode="route" throttle="0.0" vmode="throttle" wp="TD"/>
<attitude roll="0.0" throttle="0.0" until="FALSE" vmode="throttle"/>
</block>

When you are landing your aircraft automatically, you need to bring it in very gently.

<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/> - "flare" is the deroute condition and it is implemented when the aircraft is 10 meters from the ground. You would want the aircraft to flare just before hitting the ground. If your aircraft is not very stable at low speeds you may want to make the distance above ground lower.

<go from="AF" hmode="route" vmode="glide" wp="TD"/>

<go from="AF" hmode="route" vmode="glide" wp="TD"/>

Flight Plan Examples

2010-05-03T12:15:08Z

Nathan: /* Structure of the flight plan file */

Flight Plan Examples

2010-05-03T12:02:13Z

Nathan: /* Takeoff */

Flight Plan Examples

2010-05-03T11:44:50Z

Nathan: /* Takeoff */

Flight Plan Examples

2010-05-03T11:40:50Z

Nathan: /* Takeoff */

This page will detail a number of flight plan examples.

== Takeoff ==

<tt>
<block key="t" name="Takeoff" strip_button="Takeoff" strip_icon="takeoff.png">
<set value="0" var="kill_throttle"/>
<set value="0" var="estimator_flight_time"/>
<go from="HOME" pitch="-10" throttle="1.0" vmode="throttle" wp="CLIMB"/>
</block>
</tt>

Explanation of the code - left to right, top to bottom.

key="t" - Not sure what this does - SOMEONE PLEASE UPDATE

name="Takeoff" - the name of the block

strip_button="Takeoff" - This shows as the name when you hover your mouse over the button

strip_icon="takeoff.png" - The name of the icon picture shown in the GCS

<set value="0" var="kill_throttle"/> - This turns on the option to change the throttle

<set value="0" var="estimator_flight_time"/> - This turns on the flight time estimator

<go from="HOME" pitch="-10" throttle="1.0" vmode="throttle" wp="CLIMB"/> - This says for the aircraft to go from "HOME" waypoint towards "CLIMB" waypoint with a pitch of -10 and throttle at 100%. I am not sure what vmode="throttle" means.

== Structure of the flight plan file ==

Flight Plan Examples

2010-05-03T11:39:20Z

Nathan: /* Takeoff */

Flight Plan Examples

2010-05-03T11:36:24Z

Nathan:

Flight Plans

2010-04-26T12:42:43Z

Nathan: /* Building Flight Plans */

GCS

2010-04-26T10:10:17Z

Nathan: /* Altitude graph widget */

{|
|-valign="top"
|__TOC__
|
[[Image:gcs.jpg|frame|right|The Paparazzi Ground Control Station is the heart of the system and the user's primary interaction interface.]]
|}

== Strips ==

Each A/C has an associated strip that displays information about the A/C and provides buttons for common commands. The strip has the following layout:

[[Image:strip.png|Aircraft information strip]]

=== Displayed information ===

* Left: Flight information
* Center: Navigation information
* Right: Navigation control
* Bottom: Custom navigation and setting buttons

=== Actions ===

Every change in the waypoints (position or/and altitude) must be confirmed with the dialog box that appears after the move. A modified waypoint remains animated on the map and the GCS continues to re-send the move request until confirmation is received from the aircraft.
When clicked, the '''Mark''' button places a mark on the map at the A/C position. A snapshot from the video plugin is associated to this mark and can be viewed by moving the mouse over the mark. A click on the mark opens a dialog box allowing to delete the mark.
A click on the colored bar at the top selects the corresponding A/C in the [[#notebook|Notebook]].

== Map ==

[[Image:GCSmap.png|thumb|400px|Sample map showing the various features]]

=== Display ===

The map display contains the following information:
* The A/C track: it can be erased ''via'' the ''Clear track'' option from the A/C menu.
* The A/C label (in clear blue near the A/C) contains the name of the A/C (Plaster), it's altitude (218 m) and it's ground speed (11.99 m/s). This option default is off. It can be activated with the ''A/C label'' option from the A/C menu.
* The carrot (the orange triangle). This is the point the A/C is following during autonomous navigation.
* The waypoints defined in the flight plan (blue diamonds).
* The intended trajectory is shown in green (circling waypoint 2).
* The default background is black. [[#google_tiles|Google tiles]] or [[Maps|user defined maps]] can be loaded to provide navigation reference.
* The camera footprint (the grey polygon) is representative of the swath of land currently seen by the onboard camera. This option default is off. It can be activated with the ''Cam footprint'' option from the A/C menu.
* The WGS84 coordinates of the mouse cursor are displayed at the top right hand corner (43.462019 1.270474).
* A UTM kilometric grid can be added to the background ''via'' the ''UTM grid'' option from the ''Nav'' menu.
* The height Above Ground Level (AGL) displays the ground altitude of the mouse near the geographic position in the top right hand corner. The [http://srtm.usgs.gov/ SRTM] option must be enabled in the ''Nav'' menu. The height information comes from SRTM data files (<tt>.hgt.zip</tt> or <tt>.hgt.bz2</tt>) and must be copied to the <tt>data/srtm/</tt> directory. They can be downloaded from [http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/ http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/]. For example: http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/Eurasia/N47E016.hgt.zip is for 47 deg North latitude and 16 deg East longitude.

=== Navigation ===

You can pan/zoom the map using the following:
* Pan with the blue arrows on the map or use the arrow keys on the keyboard
* zoom in/out with the mouse scroll wheel, the page up/page down buttons or the small up/down buttons at the top right hand corner where the zoom factor is displayed
* fit the map to the window, in order to see all the waypoints and A/C, with the '''f''' key or the ''Fit'' option from the ''Nav'' menu;
* center the map on an A/C with the ''Center A/C'' option from the corresponding A/C menu.

=== Google Tiles ===
The default black background can be automatically filled with calibrated satellite photo tiles from Google. Note: if you download too much map data from Google you may be blocked for downloading further maps for 24 hours.
 
See the [[Maps]] page for more info.

=== Waypoint Editing ===

The properties of any waypoint in the currently loaded flight plan can be modified by two methods:
* Drag and drop the waypoints to a new location (a confirmation dialog will appear).
* A single left click on a waypoint opens a dialog box where you can edit the waypoint's coordinates and altitude.

Waypoint edits are sent to the aircraft immediately upon confirmation in the dialog box. The GCS will re-send the data and the waypoint will animate until the aircraft confirms receipt of the move request. New waypoints cannot be added during flight.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on waypoints.

== Notebook ==

The notebook frame contains one page for each running aircraft. Each aircraft page is itself divided into subpages displaying telemetry data and giving access to the autopilot tuning parameters.

Note that the colored tabs at the top of this section allow the user to select among multiple aircraft.

=== Flight Plan ===

<center>
[[Image:GCSfp.png|Flight plan tree]]
</center>

The full tree of the flight plan is given in this page. The current block and the current stage are highlighted. A double-click on a block allows the operator to immediately switch navigation to this block.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on flight plans.

=== Settings ===
<center>
[[Image:GCSsettings.png|Settings tab]]
</center>
The setting page allows the operator to change variable values during flight. The layout of the page is generated from the <tt>dl_settings</tt> section of the settings.xml file, one tab is associated to every section and sub-section.

On each line is displayed (from left to right), the name of the variable, its current value (periodically sent by the A/C), a slider or radio buttons for user input, and commit/undo buttons.
 
See the [[Telemetry#Settings|Telemetry]] page for more information on settings.
 
The save button of this tab opens the following popup which proposes to the user to save the current values in the airframe file (according to the <tt>param</tt> attribute in the [[Telemetry#Settings|setttings]] configuration file). The values of the checked rows will be saved in the airframe file (or any other file) for further use. Units (e.g. deg or rad) are taken into account. '''It is recommended to backup the airframe file before overwriting it with this utility''' (even if time-stamped copy of the airframe file is actually automatically done).

Symetrically, the Upload button of this dialog button will send all the checked values of the airframe file to the live aircraft.
<center>
[[Image:Save settings.png|Settings tab]]
</center>

=== PFD ===

[[Image:GCSpfd.png|Primary Flight Display]]

The Primary Flight Display contains an artificial horizon and two scales displaying the current ground speed (left side) and the altitude (right side). Minimum and maximum speeds are shown under and above the speed scale. A click on the scale resets these values to the current speed value.

=== GPS, Infrared, Wind ===

The '''GPS''' page gives the list of satellites tracked by the receiver and their respective signal strengths in dB.
(35 is low, 45 is excellent) and if they are used to compute the fix (green: used, red:not used). This page may help to tune the position of the receiver on the aircraft relatively to other components (e.g. datalink and video transmitters).

The '''Infrared''' page is only used for aircraft not equipped with the vertical infrared sensor. This page reports the required pre-flight calibration value as well as the evolution of the in-flight calibration correction factor (from hybridization with the GPS information).

The '''Misc''' page displays the estimated wind velocity computed by the ground station during flight and relayed back to the aircraft. Wind velocity is estimated by vector addition of the GPS-measured ground speed in many different directions during level flight. This computation may soon be performed by the autopilot instead of the ground station.

== Video Plugin ==

The <tt>-mplayer</tt> option of GCS allows the user to display a video stream in this window. The video window can also be exchanged with the map by clicking anywhere inside the frame or from the menu.
Use the following line in your [[Control_panel.xml|control panel]] to enable the video window.
<tt>path_to_ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video -layout appropriate_layout.xml</tt>
Note that a <tt>plugin</tt> widget must be specified in the used layout:
<tt> <widget size="300" name="plugin"/></tt>

The <tt>-plugin</tt> option is another way to use the plugin widget: the X subwindow id is given to the provided command:
<tt>path_to_ground_segment/cockpit/gcs -plugin "mplayer video_stream -wid " -layout appropriate_layout.xml</tt>
<tt>path_to_ground_segment/cockpit/gcs -plugin "cvlc video_stream --drawable-xid=" -layout appropriate_layout.xml</tt>
The <tt>--vout-event=3</tt> option can be used for vlc to disable mouse and keyboard events handling

== Altitude graph widget ==
<center>
[[Image:altgraph.png|400px|The GCS with the altitude graph]]
</center>

An altitude graph can be displayed in the GCS by adding the widget ''altgraph'' in the layout configuration (See the [[GCS_Configuration|GCS configuration]] page). An example is provided in conf/gcs/alt.xml. To use this layout add -layout alt.xml to the /conf/control_panel.xml file. This type of layout is more suited to a multi UAV set up. The Papget ruler is a much less intrusive and better tool when you are only flying a single aircraft.

==Papgets==
Graphical objects can be added to 2D maps: text, rule, gauge, buttons, .... These objects are named ''papgets''. The following snapshot
shows an example with buttons (left side), gauges (lower left corner), text (upper right corner) and ruler (right side). This example
has been produced with a layout file provided in the distribution:

.../gcs -layout papgets.xml

<center>
[[Image:papgets.png|516px|A 2D map augmented with papgets]]
</center>

===Telemetry data report===
The easiest way to create a papget displaying telemetry data is to drag&drop a message field from the Messages window onto the 2D map of the GCS. The default rendering is then a string of text. Clicking on it allows the user to change its type (currently text, ruler or gauge) and some of its attributes (color, size, range for a gauge, format for a text ...). A papget can be moved by simply dragging it.

<center>
[[Image:papget_editor.png|Main characteristics of a papget can be dynamically edited]]
</center>

Papgets can be saved in the layout of the GCS (from the Nav menu). The description is saved in an XML file (in <tt>conf/gcs/</tt> folder) which can be manually edited:

<pre>
<papget type="message_field" display="gauge" x="47" y="414">
<property name="field" value="BAT:voltage"/>
<property name="scale" value="0.1"/>
<property name="min" value="0."/>
<property name="max" value="15."/>
<property name="size" value="50."/>
<property name="text" value="Bat(V)"/>
</papget>
</pre>

The file is used later by giving it to the gcs process:

<pre>
.../gcs -layout my_fancy_papgets.xml
</pre>

===Buttons===
In the same way, user buttons from the strip can be dragged&dropped on the 2D map. However, they currently cannot be directly edited, and
attributes changes have to be done in the XML file. Two types of button are provided to jump to a block or to set a value:

<papget type="goto_block" display="button" x="10" y="300">
<property name="block_name" value="Standby"/>
<property name="icon" value="home.png"/>
</papget>
<papget type="variable_setting" display="button" x="10" y="250">
<property name="variable" value="launch"/>
<property name="value" value="1."/>
<property name="icon" value="launch.png"/>
</papget>

===Video===
A video stream can be rendered in a <tt>video_plugin</tt> papget, using the mplayer player:
<papget type="video_plugin" display="mplayer" x="300" y="250">
<property name="video_feed" value="my video source"/>
<property name="width" VALUE="320"/>
<property name="height" VALUE="240"/>
</papget>
or any video player which takes in option the X window id :
<papget type="video_plugin" display="plugin" x="300" y="250">
<property name="command" value="cvlc video_source --drawable-xid="/>
<property NAME="width" VALUE="320"/>
<property NAME="height" VALUE="240"/>
</papget>

===Development===
Graphical appearence of papgets is defined in <tt>sw/lib/ocaml/papget_renderer.ml</tt>. A renderer must implement the Papget_renderer.t class type interface (<tt>canvas_text</tt> is probably the simpler example) and listed in the <tt>renderers</tt> list to be available
in the edit popup box.

The XML configuration is parsed in <tt>sw/ground_segment/cockpit/papgets.ml</tt>: a new created papget identifier must listed here.

== Alarms ==

The alarm window displays a list of recent errors such as:
* Low battery warning
* Low altitude warning
* Autopilot mode changes (i.e. Manual, Auto2)
* Flight plan block changes

== Configuration Options ==
The GCS is highly configurable and modules can be added, removed, or resized as needed. In addition to this the gcs has many command line options which can be used when launching the GCS
 
See the [[GCS_Configuration|GCS configuration]] page for details.

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

Flight Plans

2010-04-26T01:32:53Z

Nathan: /* Building Flight Plans */

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: 

<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 convex and described in a clockwise order. For a sector named <tt>sector</tt> (sector names must not 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. 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>\

== Building Flight Plans ==

'''Waypoint Settings'''

Many of the flight plan examples here and in the Paparazzi software set waypoint locations using x,y coordinates from the lat/lon in the header of the flight plan. When building flight plans on the fly where there is no requirement to stay within lat/lon boundaries, this is acceptable. When you are building flight plans where you are required to stay within or overfly certain GPS coordinates, using x,y from the lat/lon in the header will not work in real life. When simulating your flight plan the aircraft always starts from the lat/lon in the header. In reality your aircraft will probably start from a different spot each time, meaning your lat/lon coordinates will change each time. If you use the x,y coordinates, then each waypoint will move and your GPS points will not longer be correct.

'''Following the contours of the land'''

To get the land contour information you need to download the SRTM data (note: the SRTM data is not accurate but it will give you a good idea). Once you have this data, you need to setup your waypoints to take advantage of this data. When you want your aircraft to follow the contours of the land you need to use the "height" attribute not the "alt" attribute. The "height" attribute = ground_alt + height, the SRTM data gives ground_alt as the altitude above sea level. If you were to use the "alt" attribute, then each waypoint altitude needs to be set to take into account the SRTM altitude at each waypoint plus the height above ground level.

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

Flight Plans

2010-04-26T01:31:47Z

Nathan: /* Building Flight Plans */

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: 

<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 convex and described in a clockwise order. For a sector named <tt>sector</tt> (sector names must not 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. 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>\

== Building Flight Plans ==

'''Waypoint Settings'''

Many of the flight plan examples here and in the Paparazzi software set waypoint locations using x,y coordinates from the lat/lon in the header of the flight plan. When building flight plans on the fly where there is no requirement to stay within lat/lon boundaries, this is acceptable. When you are building flight plans where you are required to stay within or overfly certain GPS coordinates, using x,y from the lat/lon in the header will not work in real life. When simulating your flight plan the aircraft always starts from the lat/lon in the header. In reality your aircraft will probably start from a different spot each time, meaning your lat/lon coordinates will change each time. If you use the x,y coordinates, then each waypoint will move and your GPS points will not longer be correct.

'''Following the contours of the land'''

To get the land contour information you need to download the SRTM data. Once you have this data, you need to setup your waypoints to take advantage of this data. When you want your aircraft to follow the contours of the land you need to use the "height" attribute not the "alt" attribute. The "height" attribute = ground_alt + height, the SRTM data gives ground_alt as the altitude above sea level. If you were to use the "alt" attribute, then each waypoint altitude needs to be set to take into account the SRTM altitude at each waypoint plus the height above ground level.

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

Flight Plans

2010-04-25T07:44:20Z

Nathan:

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: 

<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 convex and described in a clockwise order. For a sector named <tt>sector</tt> (sector names must not 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. 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>\

== Building Flight Plans ==

Many of the flight plan examples here and in the Paparazzi software set waypoint locations using x,y coordinates from the lat/lon in the header of the flight plan. When building flight plans on the fly where there is no requirement to stay within lat/lon boundaries, this is accepable. When you are building flight plans where you are required to stay within or overfly certain GPS coordinates, using x,y from the lat/lon in the header will not work in real life. When simulating your flight plan the aircraft always starts from the lat/lon in the header. In reality your aircraft will probably start from a different spot each time, meaning your lat/lon coordinates will change each time. If you use the x,y coordinates, then each waypoint will move and your GPS points will not longer be correct.

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

Advanced Navigation Routines

2010-04-24T01:24:43Z

Nathan:

== [http://www.engr.usu.edu/wiki/index.php/OSAM OSAM Team] Navigation Routines ==
=== Flower ===
[[Image:FlowerScreenShot.png|thumb|Screen shot of flower routine]]
The flower navigation routine flies the aircraft in a flower pattern defined by two waypoints. The center waypoint defines the center of the flower and the altitude the plane flies at. The edge waypoint defines the radius of the flower.
To use this navigation routine, you need to include OSAMNav.h in your flight plan and OSAMNav.c to your airframe file. Then you can add flower to your flight plan like so...

<block name="Flower">
<call fun="InitializeFlower(WP_Center,WP_Edge)"/>
<call fun="FlowerNav()"/>
</block>
 

=== Bungee Takeoff ===
The bungee takeoff routine helps to automate takeoff by turning the throttle on after the bungee has been release from the hook. The only waypoint you need for this routine is the position of where the bungee is pegged to the ground. Using this waypoint, a line is drawn from the position of the aircraft to the bungee waypoint. This line is called the launch line and will stop updating once the speed of the plane exceeds the MinSpeed. This allows the user to initialize the routine, move the plane and launch it without having to reinitialize. Once the plane is launched, it will follow the launch line until it crosses the throttle line. The throttle line is a line perpendicular to the launch line at a distance d from the bungee waypoint (see the diagram below). When the plane crosses the throttle line and the speed of the aircraft is greater than MinSpeed, the throttle comes on. After the throttle comes on, the plane keeps going straight until it reaches a specified speed and altitude above the bungee waypoint altitude. When it reaches the takeoff speed and takeoff altitude, the next block in the flight plan is executed. The takeoff speed, takeoff altitude, MinSpeed and the distance d from the bungee waypoint are specified in the airframe file. You will need to add those values to your airframe file like this...

<section name="Takeoff" prefix="Takeoff_">
<define name="Height" value="30" unit="m"/>
<define name="Speed" value="15" unit="m/s"/>
<define name="Distance" value="3" unit="m"/>
<define name="MinSpeed" value="5" unit="m/s"/>
</section>

To use this navigation routine, include OSAMNav.h in your flight plan and OSAMNav.c to your airframe file. Then you can add the bungee takeoff routine to your flight plan like so...

<block name="Takeoff" strip_button="Takeoff (wp CLIMB)" strip_icon="takeoff.png">
<call fun="InitializeBungeeTakeoff(WP_Bungee)"/>
<call fun="BungeeTakeoff()"/>
</block>

To get this routine to work consistantly, you will need to tune the values in the airframe config file. If the prop doesn't automatically turn on when it crosses the throttle line, it could be because the Distance and/or the MinSpeed are too big. If it turns on to early, it could be because the Distance and/or MinSpeed are too small.

 ***Precaution should be taken while tuning the auto takeoff. If the MinSpeed is too low, the prop could turn on while holding the aircraft!***

<gallery>
Image:BungeeTakeoffDiagram.png|Bungee takeoff diagram
Image:BungeeTakeoffInit.png|After bungee takeoff initialization
Image:BungeeTakeoffThrottleOn.png|After crossing the throttle line
</gallery>

=== Polygon Survey ===
==== Explanation ====
With this navigation routine, an aircraft can survey the area of any [http://en.wikipedia.org/wiki/Convex_polygon convex polygon] given an entry point, the number of waypoints which define the polygon, the sweep width and the desired orientation of the sweeps.

The entry point is the first corner of the polygon and the point at which the aircraft will begin surveying the area. When in the entry state, the aircraft will circle around the entry point in order to smoothly transition into the first sweep. The aircraft will also keep circling around the entry point until it gets to the waypoint altitude. After the first sweep is made, the direction of the next sweep is determined by the distance of the entry point to the edges of the polygon. If there is more area above the first sweep, the aircraft will sweep up. If there is more area below the first sweep, the aircraft will sweep down.

The aircraft will keep sweeping back and forth until it reaches the end of the polygon. At this point, the aircraft will sweep back up/down the polygon halfway in between the sweeps previously made by the aircraft (just like the rectangle survey function). The aircraft will keep sweeping up and down the polygon unless the user manually exits the block or unless an exception is used ([[#Exceptions|see below]]).

The orientation of the sweeps can ranges from north south to east west and any where in between (0-90 degrees respectively). The side of the polygon the aircraft starts on (ex. north or south) is determined by the side of the polygon the entry point is located.

<gallery>
Image:PolySurveySweepDef.png|Sweep Definition
Image:PolySurveyEntryPic.png|Entry Point
Image:PolySurveySweepBack.png|Sweeping Back
</gallery>

==== Implementation ====
To use this navigation routine, you need to include OSAMNav.h in your flight plan and OSAMNav.c to your airframe file. Then add this navigation routine in your flight plan like so...

<block name="Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
<call fun="PolygonSurvey()"/>
</block>

The parameters are the entry waypoint, the number of waypoints in the polygon, the sweep width (meters), and the desired orientation of the sweeps (degrees). The maximum number of waypoints a polygon can have is currently ten (can be changed in the code). If the number of waypoints in the polygon exceeds the maximum number, the routine will exit and move to the next block in the flight plan. The routine will also exit if the orientation is not between 0 and 90 degrees.

Here is an example of how you should declare each of the corners of the polygon.

<waypoint alt="1453.0" name="S1" x="-546.2" y="297.4"/>
<waypoint alt="1453.0" name="_S2" x="-129.8" y="744.1"/>
<waypoint alt="1553.0" name="_S3" x="1030.5" y="535.5"/>
<waypoint alt="1453.0" name="_S4" x="523.0" y="-236.7"/>
<waypoint alt="1453.0" name="_S5" x="-285.9" y="-255.7"/>

S1 is the entry waypoint and the first corner. The other corners should be in order clockwise or counter clockwise around the polygon. Even though this group of waypoints must be declared together, where the group appears in the list of waypoints doesn't matter.

If you want the edges of the polygon to show up on the GCS, you can also declare the polygon as a sector. This is not required to run the routine.

<sectors>
<sector name="PolySector">
<corner name="S1"/>
<corner name="_S2"/>
<corner name="_S3"/>
<corner name="_S4"/>
<corner name="_S5"/>
</sector>
</sectors>

<gallery caption="A Range of Different Sweep Orientations">
Image:PolySurvey0DegreeEx.png|0 Degrees
Image:PolySurvey30DegreeEx.png|30 Degrees
Image:PolySurvey65DegreeEx.png|65 Degrees
Image:PolySurvey90DegreeEx.png|90 Degrees
</gallery>

==== Alternative configurations ====
If you are wanting to start and stop the Poly Survey this is possible by splitting the Poly Survey code above into the initialization routine and the execution routine. You might want to do this if you are searching for something inside the Poly Survey, think you have found it and then realized you haven't, so you want to continue the survey (not restart it). Using the example above, but with the initialisation and execution code separate:

<block name="Init Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
</block>

<block name="Execute Poly Survey">
<call fun="PolygonSurvey()"/>
</block>

==== Exceptions ====
There are a couple of built in variables which can be used to exit the routine with an exception. PolySurveySweepNum gives the number of sweeps the aircraft has made and PolySurveySweepBackNum gives the number of times the aircraft has gotten to the bottom of the polygon and swept back. The first example would deroute the aircraft to standby after the aircraft made it's second sweep. The second example would deroute the aircraft to standby before it starts to sweep back up the polygon for the first time.

block name="Poly Survey">
<exception cond="PolySurveySweepNum >= 2" deroute="Standby"/>
<call fun="InitializePolygonSurvey(WP_S1, 5, 200, 45)"/>
<call fun="PolygonSurvey()"/>
</block>

block name="Poly Survey">
<exception cond="PolySurveySweepBackNum >= 1" deroute="Standby"/>
<call fun="InitializePolygonSurvey(WP_S1, 5, 200, 45)"/>
<call fun="PolygonSurvey()"/>
</block>

GCS

2010-04-22T15:04:41Z

Nathan: /* Altitude graph widget */

{|
|-valign="top"
|__TOC__
|
[[Image:gcs.jpg|frame|right|The Paparazzi Ground Control Station is the heart of the system and the user's primary interaction interface.]]
|}

== Strips ==

Each A/C has an associated strip that displays information about the A/C and provides buttons for common commands. The strip has the following layout:

[[Image:strip.png|Aircraft information strip]]

=== Displayed information ===

* Left: Flight information
* Center: Navigation information
* Right: Navigation control
* Bottom: Custom navigation and setting buttons

=== Actions ===

Every change in the waypoints (position or/and altitude) must be confirmed with the dialog box that appears after the move. A modified waypoint remains animated on the map and the GCS continues to re-send the move request until confirmation is received from the aircraft.
When clicked, the '''Mark''' button places a mark on the map at the A/C position. A snapshot from the video plugin is associated to this mark and can be viewed by moving the mouse over the mark. A click on the mark opens a dialog box allowing to delete the mark.
A click on the colored bar at the top selects the corresponding A/C in the [[#notebook|Notebook]].

== Map ==

[[Image:GCSmap.png|thumb|400px|Sample map showing the various features]]

=== Display ===

The map display contains the following information:
* The A/C track: it can be erased ''via'' the ''Clear track'' option from the A/C menu.
* The A/C label (in clear blue near the A/C) contains the name of the A/C (Plaster), it's altitude (218 m) and it's ground speed (11.99 m/s). This option default is off. It can be activated with the ''A/C label'' option from the A/C menu.
* The carrot (the orange triangle). This is the point the A/C is following during autonomous navigation.
* The waypoints defined in the flight plan (blue diamonds).
* The intended trajectory is shown in green (circling waypoint 2).
* The default background is black. [[#google_tiles|Google tiles]] or [[Maps|user defined maps]] can be loaded to provide navigation reference.
* The camera footprint (the grey polygon) is representative of the swath of land currently seen by the onboard camera. This option default is off. It can be activated with the ''Cam footprint'' option from the A/C menu.
* The WGS84 coordinates of the mouse cursor are displayed at the top right hand corner (43.462019 1.270474).
* A UTM kilometric grid can be added to the background ''via'' the ''UTM grid'' option from the ''Nav'' menu.
* The height Above Ground Level (AGL) displays the ground altitude of the mouse near the geographic position in the top right hand corner. The [http://srtm.usgs.gov/ SRTM] option must be enabled in the ''Nav'' menu. The height information comes from SRTM data files (<tt>.hgt.zip</tt> or <tt>.hgt.bz2</tt>) and must be copied to the <tt>data/srtm/</tt> directory. They can be downloaded from [http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/ http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/]. For example: http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/Eurasia/N47E016.hgt.zip is for 47 deg North latitude and 16 deg East longitude.

=== Navigation ===

You can pan/zoom the map using the following:
* Pan with the blue arrows on the map or use the arrow keys on the keyboard
* zoom in/out with the mouse scroll wheel, the page up/page down buttons or the small up/down buttons at the top right hand corner where the zoom factor is displayed
* fit the map to the window, in order to see all the waypoints and A/C, with the '''f''' key or the ''Fit'' option from the ''Nav'' menu;
* center the map on an A/C with the ''Center A/C'' option from the corresponding A/C menu.

=== Google Tiles ===
The default black background can be automatically filled with calibrated satellite photo tiles from Google. Note: if you download too much map data from Google you may be blocked for downloading further maps for 24 hours.
 
See the [[Maps]] page for more info.

=== Waypoint Editing ===

The properties of any waypoint in the currently loaded flight plan can be modified by two methods:
* Drag and drop the waypoints to a new location (a confirmation dialog will appear).
* A single left click on a waypoint opens a dialog box where you can edit the waypoint's coordinates and altitude.

Waypoint edits are sent to the aircraft immediately upon confirmation in the dialog box. The GCS will re-send the data and the waypoint will animate until the aircraft confirms receipt of the move request. New waypoints cannot be added during flight.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on waypoints.

== Notebook ==

The notebook frame contains one page for each running aircraft. Each aircraft page is itself divided into subpages displaying telemetry data and giving access to the autopilot tuning parameters.

Note that the colored tabs at the top of this section allow the user to select among multiple aircraft.

=== Flight Plan ===

<center>
[[Image:GCSfp.png|Flight plan tree]]
</center>

The full tree of the flight plan is given in this page. The current block and the current stage are highlighted. A double-click on a block allows the operator to immediately switch navigation to this block.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on flight plans.

=== Settings ===
<center>
[[Image:GCSsettings.png|Settings tab]]
</center>
The setting page allows the operator to change variable values during flight. The layout of the page is generated from the <tt>dl_settings</tt> section of the settings.xml file, one tab is associated to every section and sub-section.

On each line is displayed (from left to right), the name of the variable, its current value (periodically sent by the A/C), a slider or radio buttons for user input, and commit/undo buttons.
 
See the [[Telemetry#Settings|Telemetry]] page for more information on settings.
 
The save button of this tab opens the following popup which proposes to the user to save the current values in the airframe file (according to the <tt>param</tt> attribute in the [[Telemetry#Settings|setttings]] configuration file). The values of the checked rows will be saved in the airframe file (or any other file) for further use. Units (e.g. deg or rad) are taken into account. '''It is recommended to backup the airframe file before overwriting it with this utility''' (even if time-stamped copy of the airframe file is actually automatically done).

Symetrically, the Upload button of this dialog button will send all the checked values of the airframe file to the live aircraft.
<center>
[[Image:Save settings.png|Settings tab]]
</center>

=== PFD ===

[[Image:GCSpfd.png|Primary Flight Display]]

The Primary Flight Display contains an artificial horizon and two scales displaying the current ground speed (left side) and the altitude (right side). Minimum and maximum speeds are shown under and above the speed scale. A click on the scale resets these values to the current speed value.

=== GPS, Infrared, Wind ===

The '''GPS''' page gives the list of satellites tracked by the receiver and their respective signal strengths in dB.
(35 is low, 45 is excellent) and if they are used to compute the fix (green: used, red:not used). This page may help to tune the position of the receiver on the aircraft relatively to other components (e.g. datalink and video transmitters).

The '''Infrared''' page is only used for aircraft not equipped with the vertical infrared sensor. This page reports the required pre-flight calibration value as well as the evolution of the in-flight calibration correction factor (from hybridization with the GPS information).

The '''Misc''' page displays the estimated wind velocity computed by the ground station during flight and relayed back to the aircraft. Wind velocity is estimated by vector addition of the GPS-measured ground speed in many different directions during level flight. This computation may soon be performed by the autopilot instead of the ground station.

== Video Plugin ==

The <tt>-mplayer</tt> option of GCS allows the user to display a video stream in this window. The video window can also be exchanged with the map by clicking anywhere inside the frame or from the menu.
Use the following line in your [[Control_panel.xml|control panel]] to enable the video window.
<tt>path_to_ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video -layout appropriate_layout.xml</tt>
Note that a <tt>plugin</tt> widget must be specified in the used layout:
<tt> <widget size="300" name="plugin"/></tt>

The <tt>-plugin</tt> option is another way to use the plugin widget: the X subwindow id is given to the provided command:
<tt>path_to_ground_segment/cockpit/gcs -plugin "mplayer video_stream -wid " -layout appropriate_layout.xml</tt>
<tt>path_to_ground_segment/cockpit/gcs -plugin "cvlc video_stream --drawable-xid=" -layout appropriate_layout.xml</tt>
The <tt>--vout-event=3</tt> option can be used for vlc to disable mouse and keyboard events handling

== Altitude graph widget ==
<center>
[[Image:altgraph.png|400px|The GCS with the altitude graph]]
</center>

An altitude graph can be displayed in the GCS by adding the widget ''altgraph'' in the layout configuration (See the [[GCS_Configuration|GCS configuration]] page). An example is provided in conf/gcs/alt.xml (launch GCS with the option -layout alt.xml). This type of layout is more suited to a multi UAV set up. The Papget ruler is a much less intrusive and better tool when you are only flying a single aircraft.

==Papgets==
Graphical objects can be added to 2D maps: text, rule, gauge, buttons, .... These objects are named ''papgets''. The following snapshot
shows an example with buttons (left side), gauges (lower left corner), text (upper right corner) and ruler (right side). This example
has been produced with a layout file provided in the distribution:

.../gcs -layout papgets.xml

<center>
[[Image:papgets.png|516px|A 2D map augmented with papgets]]
</center>

===Telemetry data report===
The easiest way to create a papget displaying telemetry data is to drag&drop a message field from the Messages window onto the 2D map of the GCS. The default rendering is then a string of text. Clicking on it allows the user to change its type (currently text, ruler or gauge) and some of its attributes (color, size, range for a gauge, format for a text ...). A papget can be moved by simply dragging it.

<center>
[[Image:papget_editor.png|Main characteristics of a papget can be dynamically edited]]
</center>

Papgets can be saved in the layout of the GCS (from the Nav menu). The description is saved in an XML file (in <tt>conf/gcs/</tt> folder) which can be manually edited:

<pre>
<papget type="message_field" display="gauge" x="47" y="414">
<property name="field" value="BAT:voltage"/>
<property name="scale" value="0.1"/>
<property name="min" value="0."/>
<property name="max" value="15."/>
<property name="size" value="50."/>
<property name="text" value="Bat(V)"/>
</papget>
</pre>

The file is used later by giving it to the gcs process:

<pre>
.../gcs -layout my_fancy_papgets.xml
</pre>

===Buttons===
In the same way, user buttons from the strip can be dragged&dropped on the 2D map. However, they currently cannot be directly edited, and
attributes changes have to be done in the XML file. Two types of button are provided to jump to a block or to set a value:

<papget type="goto_block" display="button" x="10" y="300">
<property name="block_name" value="Standby"/>
<property name="icon" value="home.png"/>
</papget>
<papget type="variable_setting" display="button" x="10" y="250">
<property name="variable" value="launch"/>
<property name="value" value="1."/>
<property name="icon" value="launch.png"/>
</papget>

===Video===
A video stream can be rendered in a <tt>video_plugin</tt> papget, using the mplayer player:
<papget type="video_plugin" display="mplayer" x="300" y="250">
<property name="video_feed" value="my video source"/>
<property name="width" VALUE="320"/>
<property name="height" VALUE="240"/>
</papget>
or any video player which takes in option the X window id :
<papget type="video_plugin" display="plugin" x="300" y="250">
<property name="command" value="cvlc video_source --drawable-xid="/>
<property NAME="width" VALUE="320"/>
<property NAME="height" VALUE="240"/>
</papget>

===Development===
Graphical appearence of papgets is defined in <tt>sw/lib/ocaml/papget_renderer.ml</tt>. A renderer must implement the Papget_renderer.t class type interface (<tt>canvas_text</tt> is probably the simpler example) and listed in the <tt>renderers</tt> list to be available
in the edit popup box.

The XML configuration is parsed in <tt>sw/ground_segment/cockpit/papgets.ml</tt>: a new created papget identifier must listed here.

== Alarms ==

The alarm window displays a list of recent errors such as:
* Low battery warning
* Low altitude warning
* Autopilot mode changes (i.e. Manual, Auto2)
* Flight plan block changes

== Configuration Options ==
The GCS is highly configurable and modules can be added, removed, or resized as needed. In addition to this the gcs has many command line options which can be used when launching the GCS
 
See the [[GCS_Configuration|GCS configuration]] page for details.

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

GCS

2010-04-22T15:01:53Z

Nathan: /* Google Tiles */

{|
|-valign="top"
|__TOC__
|
[[Image:gcs.jpg|frame|right|The Paparazzi Ground Control Station is the heart of the system and the user's primary interaction interface.]]
|}

== Strips ==

Each A/C has an associated strip that displays information about the A/C and provides buttons for common commands. The strip has the following layout:

[[Image:strip.png|Aircraft information strip]]

=== Displayed information ===

* Left: Flight information
* Center: Navigation information
* Right: Navigation control
* Bottom: Custom navigation and setting buttons

=== Actions ===

Every change in the waypoints (position or/and altitude) must be confirmed with the dialog box that appears after the move. A modified waypoint remains animated on the map and the GCS continues to re-send the move request until confirmation is received from the aircraft.
When clicked, the '''Mark''' button places a mark on the map at the A/C position. A snapshot from the video plugin is associated to this mark and can be viewed by moving the mouse over the mark. A click on the mark opens a dialog box allowing to delete the mark.
A click on the colored bar at the top selects the corresponding A/C in the [[#notebook|Notebook]].

== Map ==

[[Image:GCSmap.png|thumb|400px|Sample map showing the various features]]

=== Display ===

The map display contains the following information:
* The A/C track: it can be erased ''via'' the ''Clear track'' option from the A/C menu.
* The A/C label (in clear blue near the A/C) contains the name of the A/C (Plaster), it's altitude (218 m) and it's ground speed (11.99 m/s). This option default is off. It can be activated with the ''A/C label'' option from the A/C menu.
* The carrot (the orange triangle). This is the point the A/C is following during autonomous navigation.
* The waypoints defined in the flight plan (blue diamonds).
* The intended trajectory is shown in green (circling waypoint 2).
* The default background is black. [[#google_tiles|Google tiles]] or [[Maps|user defined maps]] can be loaded to provide navigation reference.
* The camera footprint (the grey polygon) is representative of the swath of land currently seen by the onboard camera. This option default is off. It can be activated with the ''Cam footprint'' option from the A/C menu.
* The WGS84 coordinates of the mouse cursor are displayed at the top right hand corner (43.462019 1.270474).
* A UTM kilometric grid can be added to the background ''via'' the ''UTM grid'' option from the ''Nav'' menu.
* The height Above Ground Level (AGL) displays the ground altitude of the mouse near the geographic position in the top right hand corner. The [http://srtm.usgs.gov/ SRTM] option must be enabled in the ''Nav'' menu. The height information comes from SRTM data files (<tt>.hgt.zip</tt> or <tt>.hgt.bz2</tt>) and must be copied to the <tt>data/srtm/</tt> directory. They can be downloaded from [http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/ http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/]. For example: http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/Eurasia/N47E016.hgt.zip is for 47 deg North latitude and 16 deg East longitude.

=== Navigation ===

You can pan/zoom the map using the following:
* Pan with the blue arrows on the map or use the arrow keys on the keyboard
* zoom in/out with the mouse scroll wheel, the page up/page down buttons or the small up/down buttons at the top right hand corner where the zoom factor is displayed
* fit the map to the window, in order to see all the waypoints and A/C, with the '''f''' key or the ''Fit'' option from the ''Nav'' menu;
* center the map on an A/C with the ''Center A/C'' option from the corresponding A/C menu.

=== Google Tiles ===
The default black background can be automatically filled with calibrated satellite photo tiles from Google. Note: if you download too much map data from Google you may be blocked for downloading further maps for 24 hours.
 
See the [[Maps]] page for more info.

=== Waypoint Editing ===

The properties of any waypoint in the currently loaded flight plan can be modified by two methods:
* Drag and drop the waypoints to a new location (a confirmation dialog will appear).
* A single left click on a waypoint opens a dialog box where you can edit the waypoint's coordinates and altitude.

Waypoint edits are sent to the aircraft immediately upon confirmation in the dialog box. The GCS will re-send the data and the waypoint will animate until the aircraft confirms receipt of the move request. New waypoints cannot be added during flight.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on waypoints.

== Notebook ==

The notebook frame contains one page for each running aircraft. Each aircraft page is itself divided into subpages displaying telemetry data and giving access to the autopilot tuning parameters.

Note that the colored tabs at the top of this section allow the user to select among multiple aircraft.

=== Flight Plan ===

<center>
[[Image:GCSfp.png|Flight plan tree]]
</center>

The full tree of the flight plan is given in this page. The current block and the current stage are highlighted. A double-click on a block allows the operator to immediately switch navigation to this block.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on flight plans.

=== Settings ===
<center>
[[Image:GCSsettings.png|Settings tab]]
</center>
The setting page allows the operator to change variable values during flight. The layout of the page is generated from the <tt>dl_settings</tt> section of the settings.xml file, one tab is associated to every section and sub-section.

On each line is displayed (from left to right), the name of the variable, its current value (periodically sent by the A/C), a slider or radio buttons for user input, and commit/undo buttons.
 
See the [[Telemetry#Settings|Telemetry]] page for more information on settings.
 
The save button of this tab opens the following popup which proposes to the user to save the current values in the airframe file (according to the <tt>param</tt> attribute in the [[Telemetry#Settings|setttings]] configuration file). The values of the checked rows will be saved in the airframe file (or any other file) for further use. Units (e.g. deg or rad) are taken into account. '''It is recommended to backup the airframe file before overwriting it with this utility''' (even if time-stamped copy of the airframe file is actually automatically done).

Symetrically, the Upload button of this dialog button will send all the checked values of the airframe file to the live aircraft.
<center>
[[Image:Save settings.png|Settings tab]]
</center>

=== PFD ===

[[Image:GCSpfd.png|Primary Flight Display]]

The Primary Flight Display contains an artificial horizon and two scales displaying the current ground speed (left side) and the altitude (right side). Minimum and maximum speeds are shown under and above the speed scale. A click on the scale resets these values to the current speed value.

=== GPS, Infrared, Wind ===

The '''GPS''' page gives the list of satellites tracked by the receiver and their respective signal strengths in dB.
(35 is low, 45 is excellent) and if they are used to compute the fix (green: used, red:not used). This page may help to tune the position of the receiver on the aircraft relatively to other components (e.g. datalink and video transmitters).

The '''Infrared''' page is only used for aircraft not equipped with the vertical infrared sensor. This page reports the required pre-flight calibration value as well as the evolution of the in-flight calibration correction factor (from hybridization with the GPS information).

The '''Misc''' page displays the estimated wind velocity computed by the ground station during flight and relayed back to the aircraft. Wind velocity is estimated by vector addition of the GPS-measured ground speed in many different directions during level flight. This computation may soon be performed by the autopilot instead of the ground station.

== Video Plugin ==

The <tt>-mplayer</tt> option of GCS allows the user to display a video stream in this window. The video window can also be exchanged with the map by clicking anywhere inside the frame or from the menu.
Use the following line in your [[Control_panel.xml|control panel]] to enable the video window.
<tt>path_to_ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video -layout appropriate_layout.xml</tt>
Note that a <tt>plugin</tt> widget must be specified in the used layout:
<tt> <widget size="300" name="plugin"/></tt>

The <tt>-plugin</tt> option is another way to use the plugin widget: the X subwindow id is given to the provided command:
<tt>path_to_ground_segment/cockpit/gcs -plugin "mplayer video_stream -wid " -layout appropriate_layout.xml</tt>
<tt>path_to_ground_segment/cockpit/gcs -plugin "cvlc video_stream --drawable-xid=" -layout appropriate_layout.xml</tt>
The <tt>--vout-event=3</tt> option can be used for vlc to disable mouse and keyboard events handling

== Altitude graph widget ==
<center>
[[Image:altgraph.png|400px|The GCS with the altitude graph]]
</center>

An altitude graph can be displayed in the GCS by adding the widget ''altgraph'' in the layout configuration (See the [[GCS_Configuration|GCS configuration]] page). An example is provided in conf/gcs/alt.xml (launch GCS with the option -layout alt.xml).

==Papgets==
Graphical objects can be added to 2D maps: text, rule, gauge, buttons, .... These objects are named ''papgets''. The following snapshot
shows an example with buttons (left side), gauges (lower left corner), text (upper right corner) and ruler (right side). This example
has been produced with a layout file provided in the distribution:

.../gcs -layout papgets.xml

<center>
[[Image:papgets.png|516px|A 2D map augmented with papgets]]
</center>

===Telemetry data report===
The easiest way to create a papget displaying telemetry data is to drag&drop a message field from the Messages window onto the 2D map of the GCS. The default rendering is then a string of text. Clicking on it allows the user to change its type (currently text, ruler or gauge) and some of its attributes (color, size, range for a gauge, format for a text ...). A papget can be moved by simply dragging it.

<center>
[[Image:papget_editor.png|Main characteristics of a papget can be dynamically edited]]
</center>

Papgets can be saved in the layout of the GCS (from the Nav menu). The description is saved in an XML file (in <tt>conf/gcs/</tt> folder) which can be manually edited:

<pre>
<papget type="message_field" display="gauge" x="47" y="414">
<property name="field" value="BAT:voltage"/>
<property name="scale" value="0.1"/>
<property name="min" value="0."/>
<property name="max" value="15."/>
<property name="size" value="50."/>
<property name="text" value="Bat(V)"/>
</papget>
</pre>

The file is used later by giving it to the gcs process:

<pre>
.../gcs -layout my_fancy_papgets.xml
</pre>

===Buttons===
In the same way, user buttons from the strip can be dragged&dropped on the 2D map. However, they currently cannot be directly edited, and
attributes changes have to be done in the XML file. Two types of button are provided to jump to a block or to set a value:

<papget type="goto_block" display="button" x="10" y="300">
<property name="block_name" value="Standby"/>
<property name="icon" value="home.png"/>
</papget>
<papget type="variable_setting" display="button" x="10" y="250">
<property name="variable" value="launch"/>
<property name="value" value="1."/>
<property name="icon" value="launch.png"/>
</papget>

===Video===
A video stream can be rendered in a <tt>video_plugin</tt> papget, using the mplayer player:
<papget type="video_plugin" display="mplayer" x="300" y="250">
<property name="video_feed" value="my video source"/>
<property name="width" VALUE="320"/>
<property name="height" VALUE="240"/>
</papget>
or any video player which takes in option the X window id :
<papget type="video_plugin" display="plugin" x="300" y="250">
<property name="command" value="cvlc video_source --drawable-xid="/>
<property NAME="width" VALUE="320"/>
<property NAME="height" VALUE="240"/>
</papget>

===Development===
Graphical appearence of papgets is defined in <tt>sw/lib/ocaml/papget_renderer.ml</tt>. A renderer must implement the Papget_renderer.t class type interface (<tt>canvas_text</tt> is probably the simpler example) and listed in the <tt>renderers</tt> list to be available
in the edit popup box.

The XML configuration is parsed in <tt>sw/ground_segment/cockpit/papgets.ml</tt>: a new created papget identifier must listed here.

== Alarms ==

The alarm window displays a list of recent errors such as:
* Low battery warning
* Low altitude warning
* Autopilot mode changes (i.e. Manual, Auto2)
* Flight plan block changes

== Configuration Options ==
The GCS is highly configurable and modules can be added, removed, or resized as needed. In addition to this the gcs has many command line options which can be used when launching the GCS
 
See the [[GCS_Configuration|GCS configuration]] page for details.

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

GCS

2010-04-22T15:00:38Z

Nathan: /* Google Tiles */

{|
|-valign="top"
|__TOC__
|
[[Image:gcs.jpg|frame|right|The Paparazzi Ground Control Station is the heart of the system and the user's primary interaction interface.]]
|}

== Strips ==

Each A/C has an associated strip that displays information about the A/C and provides buttons for common commands. The strip has the following layout:

[[Image:strip.png|Aircraft information strip]]

=== Displayed information ===

* Left: Flight information
* Center: Navigation information
* Right: Navigation control
* Bottom: Custom navigation and setting buttons

=== Actions ===

Every change in the waypoints (position or/and altitude) must be confirmed with the dialog box that appears after the move. A modified waypoint remains animated on the map and the GCS continues to re-send the move request until confirmation is received from the aircraft.
When clicked, the '''Mark''' button places a mark on the map at the A/C position. A snapshot from the video plugin is associated to this mark and can be viewed by moving the mouse over the mark. A click on the mark opens a dialog box allowing to delete the mark.
A click on the colored bar at the top selects the corresponding A/C in the [[#notebook|Notebook]].

== Map ==

[[Image:GCSmap.png|thumb|400px|Sample map showing the various features]]

=== Display ===

The map display contains the following information:
* The A/C track: it can be erased ''via'' the ''Clear track'' option from the A/C menu.
* The A/C label (in clear blue near the A/C) contains the name of the A/C (Plaster), it's altitude (218 m) and it's ground speed (11.99 m/s). This option default is off. It can be activated with the ''A/C label'' option from the A/C menu.
* The carrot (the orange triangle). This is the point the A/C is following during autonomous navigation.
* The waypoints defined in the flight plan (blue diamonds).
* The intended trajectory is shown in green (circling waypoint 2).
* The default background is black. [[#google_tiles|Google tiles]] or [[Maps|user defined maps]] can be loaded to provide navigation reference.
* The camera footprint (the grey polygon) is representative of the swath of land currently seen by the onboard camera. This option default is off. It can be activated with the ''Cam footprint'' option from the A/C menu.
* The WGS84 coordinates of the mouse cursor are displayed at the top right hand corner (43.462019 1.270474).
* A UTM kilometric grid can be added to the background ''via'' the ''UTM grid'' option from the ''Nav'' menu.
* The height Above Ground Level (AGL) displays the ground altitude of the mouse near the geographic position in the top right hand corner. The [http://srtm.usgs.gov/ SRTM] option must be enabled in the ''Nav'' menu. The height information comes from SRTM data files (<tt>.hgt.zip</tt> or <tt>.hgt.bz2</tt>) and must be copied to the <tt>data/srtm/</tt> directory. They can be downloaded from [http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/ http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/]. For example: http://dds.cr.usgs.gov/srtm/version2_1/SRTM3/Eurasia/N47E016.hgt.zip is for 47 deg North latitude and 16 deg East longitude.

=== Navigation ===

You can pan/zoom the map using the following:
* Pan with the blue arrows on the map or use the arrow keys on the keyboard
* zoom in/out with the mouse scroll wheel, the page up/page down buttons or the small up/down buttons at the top right hand corner where the zoom factor is displayed
* fit the map to the window, in order to see all the waypoints and A/C, with the '''f''' key or the ''Fit'' option from the ''Nav'' menu;
* center the map on an A/C with the ''Center A/C'' option from the corresponding A/C menu.

=== Google Tiles ===

The default black background can be automatically filled with calibrated satellite photo tiles from Google. If you download too much map data from Google you may be blocked for downloading further maps for 24 hours.
 
See the [[Maps]] page for more info.

=== Waypoint Editing ===

The properties of any waypoint in the currently loaded flight plan can be modified by two methods:
* Drag and drop the waypoints to a new location (a confirmation dialog will appear).
* A single left click on a waypoint opens a dialog box where you can edit the waypoint's coordinates and altitude.

Waypoint edits are sent to the aircraft immediately upon confirmation in the dialog box. The GCS will re-send the data and the waypoint will animate until the aircraft confirms receipt of the move request. New waypoints cannot be added during flight.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on waypoints.

== Notebook ==

The notebook frame contains one page for each running aircraft. Each aircraft page is itself divided into subpages displaying telemetry data and giving access to the autopilot tuning parameters.

Note that the colored tabs at the top of this section allow the user to select among multiple aircraft.

=== Flight Plan ===

<center>
[[Image:GCSfp.png|Flight plan tree]]
</center>

The full tree of the flight plan is given in this page. The current block and the current stage are highlighted. A double-click on a block allows the operator to immediately switch navigation to this block.
 
See the [[Flight_Plans|Flight plans]] and [[Flight_Plan_Editor|Flight Plan Editor]] pages for more information on flight plans.

=== Settings ===
<center>
[[Image:GCSsettings.png|Settings tab]]
</center>
The setting page allows the operator to change variable values during flight. The layout of the page is generated from the <tt>dl_settings</tt> section of the settings.xml file, one tab is associated to every section and sub-section.

On each line is displayed (from left to right), the name of the variable, its current value (periodically sent by the A/C), a slider or radio buttons for user input, and commit/undo buttons.
 
See the [[Telemetry#Settings|Telemetry]] page for more information on settings.
 
The save button of this tab opens the following popup which proposes to the user to save the current values in the airframe file (according to the <tt>param</tt> attribute in the [[Telemetry#Settings|setttings]] configuration file). The values of the checked rows will be saved in the airframe file (or any other file) for further use. Units (e.g. deg or rad) are taken into account. '''It is recommended to backup the airframe file before overwriting it with this utility''' (even if time-stamped copy of the airframe file is actually automatically done).

Symetrically, the Upload button of this dialog button will send all the checked values of the airframe file to the live aircraft.
<center>
[[Image:Save settings.png|Settings tab]]
</center>

=== PFD ===

[[Image:GCSpfd.png|Primary Flight Display]]

The Primary Flight Display contains an artificial horizon and two scales displaying the current ground speed (left side) and the altitude (right side). Minimum and maximum speeds are shown under and above the speed scale. A click on the scale resets these values to the current speed value.

=== GPS, Infrared, Wind ===

The '''GPS''' page gives the list of satellites tracked by the receiver and their respective signal strengths in dB.
(35 is low, 45 is excellent) and if they are used to compute the fix (green: used, red:not used). This page may help to tune the position of the receiver on the aircraft relatively to other components (e.g. datalink and video transmitters).

The '''Infrared''' page is only used for aircraft not equipped with the vertical infrared sensor. This page reports the required pre-flight calibration value as well as the evolution of the in-flight calibration correction factor (from hybridization with the GPS information).

The '''Misc''' page displays the estimated wind velocity computed by the ground station during flight and relayed back to the aircraft. Wind velocity is estimated by vector addition of the GPS-measured ground speed in many different directions during level flight. This computation may soon be performed by the autopilot instead of the ground station.

== Video Plugin ==

The <tt>-mplayer</tt> option of GCS allows the user to display a video stream in this window. The video window can also be exchanged with the map by clicking anywhere inside the frame or from the menu.
Use the following line in your [[Control_panel.xml|control panel]] to enable the video window.
<tt>path_to_ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video -layout appropriate_layout.xml</tt>
Note that a <tt>plugin</tt> widget must be specified in the used layout:
<tt> <widget size="300" name="plugin"/></tt>

The <tt>-plugin</tt> option is another way to use the plugin widget: the X subwindow id is given to the provided command:
<tt>path_to_ground_segment/cockpit/gcs -plugin "mplayer video_stream -wid " -layout appropriate_layout.xml</tt>
<tt>path_to_ground_segment/cockpit/gcs -plugin "cvlc video_stream --drawable-xid=" -layout appropriate_layout.xml</tt>
The <tt>--vout-event=3</tt> option can be used for vlc to disable mouse and keyboard events handling

== Altitude graph widget ==
<center>
[[Image:altgraph.png|400px|The GCS with the altitude graph]]
</center>

An altitude graph can be displayed in the GCS by adding the widget ''altgraph'' in the layout configuration (See the [[GCS_Configuration|GCS configuration]] page). An example is provided in conf/gcs/alt.xml (launch GCS with the option -layout alt.xml).

==Papgets==
Graphical objects can be added to 2D maps: text, rule, gauge, buttons, .... These objects are named ''papgets''. The following snapshot
shows an example with buttons (left side), gauges (lower left corner), text (upper right corner) and ruler (right side). This example
has been produced with a layout file provided in the distribution:

.../gcs -layout papgets.xml

<center>
[[Image:papgets.png|516px|A 2D map augmented with papgets]]
</center>

===Telemetry data report===
The easiest way to create a papget displaying telemetry data is to drag&drop a message field from the Messages window onto the 2D map of the GCS. The default rendering is then a string of text. Clicking on it allows the user to change its type (currently text, ruler or gauge) and some of its attributes (color, size, range for a gauge, format for a text ...). A papget can be moved by simply dragging it.

<center>
[[Image:papget_editor.png|Main characteristics of a papget can be dynamically edited]]
</center>

Papgets can be saved in the layout of the GCS (from the Nav menu). The description is saved in an XML file (in <tt>conf/gcs/</tt> folder) which can be manually edited:

<pre>
<papget type="message_field" display="gauge" x="47" y="414">
<property name="field" value="BAT:voltage"/>
<property name="scale" value="0.1"/>
<property name="min" value="0."/>
<property name="max" value="15."/>
<property name="size" value="50."/>
<property name="text" value="Bat(V)"/>
</papget>
</pre>

The file is used later by giving it to the gcs process:

<pre>
.../gcs -layout my_fancy_papgets.xml
</pre>

===Buttons===
In the same way, user buttons from the strip can be dragged&dropped on the 2D map. However, they currently cannot be directly edited, and
attributes changes have to be done in the XML file. Two types of button are provided to jump to a block or to set a value:

<papget type="goto_block" display="button" x="10" y="300">
<property name="block_name" value="Standby"/>
<property name="icon" value="home.png"/>
</papget>
<papget type="variable_setting" display="button" x="10" y="250">
<property name="variable" value="launch"/>
<property name="value" value="1."/>
<property name="icon" value="launch.png"/>
</papget>

===Video===
A video stream can be rendered in a <tt>video_plugin</tt> papget, using the mplayer player:
<papget type="video_plugin" display="mplayer" x="300" y="250">
<property name="video_feed" value="my video source"/>
<property name="width" VALUE="320"/>
<property name="height" VALUE="240"/>
</papget>
or any video player which takes in option the X window id :
<papget type="video_plugin" display="plugin" x="300" y="250">
<property name="command" value="cvlc video_source --drawable-xid="/>
<property NAME="width" VALUE="320"/>
<property NAME="height" VALUE="240"/>
</papget>

===Development===
Graphical appearence of papgets is defined in <tt>sw/lib/ocaml/papget_renderer.ml</tt>. A renderer must implement the Papget_renderer.t class type interface (<tt>canvas_text</tt> is probably the simpler example) and listed in the <tt>renderers</tt> list to be available
in the edit popup box.

The XML configuration is parsed in <tt>sw/ground_segment/cockpit/papgets.ml</tt>: a new created papget identifier must listed here.

== Alarms ==

The alarm window displays a list of recent errors such as:
* Low battery warning
* Low altitude warning
* Autopilot mode changes (i.e. Manual, Auto2)
* Flight plan block changes

== Configuration Options ==
The GCS is highly configurable and modules can be added, removed, or resized as needed. In addition to this the gcs has many command line options which can be used when launching the GCS
 
See the [[GCS_Configuration|GCS configuration]] page for details.

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

Flight Plans

2010-04-20T15:46:17Z

Nathan:

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: 

<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 convex and described in a clockwise order. For a sector named <tt>sector</tt> (sector names must not 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. 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.