PaparazziUAV - User contributions [en]

Load Screenshots from FlightGear

2018-11-08T13:09:16Z

Lethargi: Removed the "work in progress" tag

__TOC__

This page describes the steps required to obtain screenshots from FlightGear into the memory of PaparazziUAV. First the required functions are presented and described. Than the exact details about running the applications are mentioned. This has been tested with PaparazziUAV v5.10 and FlightGear 2017.1.2.

== Required functions and libraries ==

FlightGear can be run with an HTTP server which can be used to obtain screenshots of the current scenery in FlightGear. There is a limit to the rate at which these screenshots (I only tested this with approximately 1 fps) can be obtained thus it cannot be used to simulate high frame rate vision. One requires the libcurl library to download the image from the HTTP server into memory. Following this, the jpeg image data needs to be decompressed to obtain the pixel values using libjpeg. All of this code have been obtained from the reference material of the corresponding libraries and required modifications made for the specific implementation. Note that in order to indicate to the compiler that libcurl and libjpeg

Before doing anything a module needs to be added to PaparazziUAV ([[Modules#Make_your_own|create a module]]). By using the 3 functions below (WriteMemoryCallback, curl2mem, get_bmp) one can download the screenshot from the FlightGear HTTP server and convert the jpeg image into bitmap data. The WriteMemoryCallback is a function that is used by the libcurl function ''curl_easy_setopt'' to write the downloaded data into the memory. The function curl2mem takes the pointer to a MemoryStruct structure as input. This structure contains two elements namely a pointer to memory and the size of the memory. curl2mem basically writes the information from http://localhost:1234/screenshot (this is where FlightGear will have its screenshot) to a predefined memory location.

<source lang="c">
struct MemoryStruct
{
char *memory;
size_t size;
};

static size_t WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
{
/* Helper function for curl2mem. Handles the writing of the data from
* the source HTTP into the memory. Needs to follow format provided by
* libcurl.
*/
size_t realsize = size * nmemb;
struct MemoryStruct *mem = (struct MemoryStruct *)userp;

mem->memory = realloc(mem->memory, mem->size + realsize + 1);
if(mem->memory == NULL) {
/* out of memory! */
printf("not enough memory (realloc returned NULL)\n");
return 0;
}

memcpy(&(mem->memory[mem->size]), contents, realsize);
mem->size += realsize;
mem->memory[mem->size] = 0;

return realsize;
}

void curl2mem(struct MemoryStruct *chunk)
{
/* Uses libcurl functions to load the screenshot from the FlightGear HTTP
* server into the programs memory
*/
CURL *curl_handle;
CURLcode res;

curl_global_init(CURL_GLOBAL_ALL);

/* init the curl session */
curl_handle = curl_easy_init();

/* specify URL to get */
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost:1234/screenshot");

/* send all data to this function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);

/* we pass our 'chunk' struct to the callback function */
// curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)chunk);

/* some servers don't like requests that are made without a user-agent
field, so we provide one */
curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0");

/* get it! */
res = curl_easy_perform(curl_handle);

/* check for errors */
if(res != CURLE_OK) {
fprintf(stderr, "curl_easy_perform() failed: %s\n",
curl_easy_strerror(res));
}

/* cleanup curl stuff */
curl_easy_cleanup(curl_handle);

/* we're done with libcurl, so clean it up */
curl_global_cleanup();
}
</source>

After obtaining the jpeg screenshot, it is decompressed to obtain the pixel data. This is done by the get_bmp function which takes 3 input parameters. The first input is a pointer to the chunk of memory containing the jpeg data. The second one is the total length of the memory chunk (i.e. the jpeg data) in bytes. The last input is a pointer to a structure which contains the decompressed pixel data from the jpeg file.

<source lang="c">
struct BmpStruct
{
unsigned char *buffer;
unsigned long size;
uint16_t width;
uint16_t height;
uint8_t pixel_size;
uint16_t row_stride;
};

uint8_t get_bmp(unsigned char *jpg_buffer, unsigned long jpg_size, struct BmpStruct *bmp)
{
// // INTIALIZE
uint8_t rc;
// Variables for the decompressor itself
struct jpeg_decompress_struct cinfo;
struct jpeg_error_mgr jerr;

// Variables for the output buffer, and how long each row is
unsigned long bmp_size;
unsigned char *bmp_buffer;
uint16_t row_stride, width, height, pixel_size;

// holds the output bmp and its metadata

// // SETUP AND CHECK
cinfo.err = jpeg_std_error(&jerr);
jpeg_create_decompress(&cinfo);

jpeg_mem_src(&cinfo, jpg_buffer, jpg_size);

// skipping error check for now. file should be JPEG
rc = jpeg_read_header(&cinfo, TRUE);
if (rc != 1) {
printf("File to get_bmp() not JPEG");
return 1;
}

jpeg_start_decompress(&cinfo);

width = cinfo.output_width;
height = cinfo.output_height;
pixel_size = cinfo.output_components;

bmp_size = width * height * pixel_size;
bmp_buffer = (unsigned char*) malloc(bmp_size);

// The row_stride is the total number of bytes it takes to store an
// entire scanline (row).
row_stride = width * pixel_size;

// // READ THE LINES
while (cinfo.output_scanline < cinfo.output_height) {
unsigned char *buffer_array[1];
buffer_array[0] = bmp_buffer + (cinfo.output_scanline) * row_stride;

jpeg_read_scanlines(&cinfo, buffer_array, 1);

}

bmp->buffer = bmp_buffer;
bmp->size = bmp_size;
bmp->width = width;
bmp->height = height;
bmp->pixel_size = pixel_size;

jpeg_finish_decompress(&cinfo);
jpeg_destroy_decompress(&cinfo);

return 0;
}
</source>

The sum_blues function below is an example of a function that uses the obtained pixel data from the FlightGear screenshot to sum up all the blue pixels. It iterates over all the bytes in the decompressed image which are for the blue channel of each pixel and sums them.

<source lang="c">
uint8_t sum_blues(void)
{
struct MemoryStruct chunk; // structure holding download data
chunk.memory = malloc(1);
chunk.size = 0;

struct BmpStruct bmp; // structure holding decompressed image

// download the jpeg into internal memory
curl2mem(&chunk);

// decompress the image and store it in preallocated structure
get_bmp((unsigned char*)chunk.memory, chunk.size, &bmp);

// free up memory of downloaded jpeg
free(chunk.memory);

uint32_t bluesum = 0;
unsigned long curinc = 2;
unsigned char *curby;
while (curinc <= bmp.size) {
curby = bmp.buffer + curinc;
bluesum += *curby;
curinc = curinc + 3;
}
printf("BlueSum: %d\n",bluesum);

// free up memory of the bmp
free(bmp.buffer);

return 0;
}
</source>

The user needs to make required implementation and plumbing to call these functions. They can be called by the users modules or through blocks in the flight plans.

== Running the application ==

After creating the required modules and functions, one must start FlightGear and the PaparazziUAV with settings that allow them to communicate with each other. I obtained the information for how to do this from [http://lists.paparazziuav.org/Paparazzi-and-Flightgear-td17704.html this] page.

First, FlightGear should be started with the following command:

<source>
fgfs --fdm=null --native-gui=socket,in,30,,5501,udp
</source>

There are many other options for FlightGear; refer to [http://wiki.flightgear.org/Command_line_options this] page for details. One may want to include their own 3D models into the environment when trying to simulate computer vision functionalities. The way to do this has been described in this [http://wiki.flightgear.org/Howto:Place_3D_objects_with_the_UFO page] of the FlightGear wiki.

Second, an extra flag needs to be included when running the simulator of PaparazziUAV.
<source>
--fg_host 127.0.0.1
</source>

This should be typed in the text box running the simulator in the [https://wiki.paparazziuav.org/wiki/Paparazzi_Center Paparazzi center]. Note that in order to speed up or pause the simulation one has to run it from the terminal as described [https://wiki.paparazziuav.org/wiki/NPS#Pausing_or_running_the_sim_at_a_different_speed here].

Load Screenshots from FlightGear

2018-11-08T13:08:13Z

Lethargi: Filled the "running the application" section of the page

'''WORK IN PROGRESS'''

__TOC__

This page describes the steps required to obtain screenshots from FlightGear into the memory of PaparazziUAV. First the required functions are presented and described. Than the exact details about running the applications are mentioned. This has been tested with PaparazziUAV v5.10 and FlightGear 2017.1.2.

== Required functions and libraries ==

FlightGear can be run with an HTTP server which can be used to obtain screenshots of the current scenery in FlightGear. There is a limit to the rate at which these screenshots (I only tested this with approximately 1 fps) can be obtained thus it cannot be used to simulate high frame rate vision. One requires the libcurl library to download the image from the HTTP server into memory. Following this, the jpeg image data needs to be decompressed to obtain the pixel values using libjpeg. All of this code have been obtained from the reference material of the corresponding libraries and required modifications made for the specific implementation. Note that in order to indicate to the compiler that libcurl and libjpeg

Before doing anything a module needs to be added to PaparazziUAV ([[Modules#Make_your_own|create a module]]). By using the 3 functions below (WriteMemoryCallback, curl2mem, get_bmp) one can download the screenshot from the FlightGear HTTP server and convert the jpeg image into bitmap data. The WriteMemoryCallback is a function that is used by the libcurl function ''curl_easy_setopt'' to write the downloaded data into the memory. The function curl2mem takes the pointer to a MemoryStruct structure as input. This structure contains two elements namely a pointer to memory and the size of the memory. curl2mem basically writes the information from http://localhost:1234/screenshot (this is where FlightGear will have its screenshot) to a predefined memory location.

<source lang="c">
struct MemoryStruct
{
char *memory;
size_t size;
};

static size_t WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
{
/* Helper function for curl2mem. Handles the writing of the data from
* the source HTTP into the memory. Needs to follow format provided by
* libcurl.
*/
size_t realsize = size * nmemb;
struct MemoryStruct *mem = (struct MemoryStruct *)userp;

mem->memory = realloc(mem->memory, mem->size + realsize + 1);
if(mem->memory == NULL) {
/* out of memory! */
printf("not enough memory (realloc returned NULL)\n");
return 0;
}

memcpy(&(mem->memory[mem->size]), contents, realsize);
mem->size += realsize;
mem->memory[mem->size] = 0;

return realsize;
}

void curl2mem(struct MemoryStruct *chunk)
{
/* Uses libcurl functions to load the screenshot from the FlightGear HTTP
* server into the programs memory
*/
CURL *curl_handle;
CURLcode res;

curl_global_init(CURL_GLOBAL_ALL);

/* init the curl session */
curl_handle = curl_easy_init();

/* specify URL to get */
curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost:1234/screenshot");

/* send all data to this function */
curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);

/* we pass our 'chunk' struct to the callback function */
// curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk);
curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)chunk);

/* some servers don't like requests that are made without a user-agent
field, so we provide one */
curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0");

/* get it! */
res = curl_easy_perform(curl_handle);

/* check for errors */
if(res != CURLE_OK) {
fprintf(stderr, "curl_easy_perform() failed: %s\n",
curl_easy_strerror(res));
}

/* cleanup curl stuff */
curl_easy_cleanup(curl_handle);

/* we're done with libcurl, so clean it up */
curl_global_cleanup();
}
</source>

After obtaining the jpeg screenshot, it is decompressed to obtain the pixel data. This is done by the get_bmp function which takes 3 input parameters. The first input is a pointer to the chunk of memory containing the jpeg data. The second one is the total length of the memory chunk (i.e. the jpeg data) in bytes. The last input is a pointer to a structure which contains the decompressed pixel data from the jpeg file.

<source lang="c">
struct BmpStruct
{
unsigned char *buffer;
unsigned long size;
uint16_t width;
uint16_t height;
uint8_t pixel_size;
uint16_t row_stride;
};

uint8_t get_bmp(unsigned char *jpg_buffer, unsigned long jpg_size, struct BmpStruct *bmp)
{
// // INTIALIZE
uint8_t rc;
// Variables for the decompressor itself
struct jpeg_decompress_struct cinfo;
struct jpeg_error_mgr jerr;

// Variables for the output buffer, and how long each row is
unsigned long bmp_size;
unsigned char *bmp_buffer;
uint16_t row_stride, width, height, pixel_size;

// holds the output bmp and its metadata

// // SETUP AND CHECK
cinfo.err = jpeg_std_error(&jerr);
jpeg_create_decompress(&cinfo);

jpeg_mem_src(&cinfo, jpg_buffer, jpg_size);

// skipping error check for now. file should be JPEG
rc = jpeg_read_header(&cinfo, TRUE);
if (rc != 1) {
printf("File to get_bmp() not JPEG");
return 1;
}

jpeg_start_decompress(&cinfo);

width = cinfo.output_width;
height = cinfo.output_height;
pixel_size = cinfo.output_components;

bmp_size = width * height * pixel_size;
bmp_buffer = (unsigned char*) malloc(bmp_size);

// The row_stride is the total number of bytes it takes to store an
// entire scanline (row).
row_stride = width * pixel_size;

// // READ THE LINES
while (cinfo.output_scanline < cinfo.output_height) {
unsigned char *buffer_array[1];
buffer_array[0] = bmp_buffer + (cinfo.output_scanline) * row_stride;

jpeg_read_scanlines(&cinfo, buffer_array, 1);

}

bmp->buffer = bmp_buffer;
bmp->size = bmp_size;
bmp->width = width;
bmp->height = height;
bmp->pixel_size = pixel_size;

jpeg_finish_decompress(&cinfo);
jpeg_destroy_decompress(&cinfo);

return 0;
}
</source>

The sum_blues function below is an example of a function that uses the obtained pixel data from the FlightGear screenshot to sum up all the blue pixels. It iterates over all the bytes in the decompressed image which are for the blue channel of each pixel and sums them.

<source lang="c">
uint8_t sum_blues(void)
{
struct MemoryStruct chunk; // structure holding download data
chunk.memory = malloc(1);
chunk.size = 0;

struct BmpStruct bmp; // structure holding decompressed image

// download the jpeg into internal memory
curl2mem(&chunk);

// decompress the image and store it in preallocated structure
get_bmp((unsigned char*)chunk.memory, chunk.size, &bmp);

// free up memory of downloaded jpeg
free(chunk.memory);

uint32_t bluesum = 0;
unsigned long curinc = 2;
unsigned char *curby;
while (curinc <= bmp.size) {
curby = bmp.buffer + curinc;
bluesum += *curby;
curinc = curinc + 3;
}
printf("BlueSum: %d\n",bluesum);

// free up memory of the bmp
free(bmp.buffer);

return 0;
}
</source>

The user needs to make required implementation and plumbing to call these functions. They can be called by the users modules or through blocks in the flight plans.

== Running the application ==

After creating the required modules and functions, one must start FlightGear and the PaparazziUAV with settings that allow them to communicate with each other. I obtained the information for how to do this from [http://lists.paparazziuav.org/Paparazzi-and-Flightgear-td17704.html this] page.

First, FlightGear should be started with the following command:

<source>
fgfs --fdm=null --native-gui=socket,in,30,,5501,udp
</source>

There are many other options for FlightGear; refer to [http://wiki.flightgear.org/Command_line_options this] page for details. One may want to include their own 3D models into the environment when trying to simulate computer vision functionalities. The way to do this has been described in this [http://wiki.flightgear.org/Howto:Place_3D_objects_with_the_UFO page] of the FlightGear wiki.

Second, an extra flag needs to be included when running the simulator of PaparazziUAV.
<source>
--fg_host 127.0.0.1
</source>

This should be typed in the text box running the simulator in the [https://wiki.paparazziuav.org/wiki/Paparazzi_Center Paparazzi center]. Note that in order to speed up or pause the simulation one has to run it from the terminal as described [https://wiki.paparazziuav.org/wiki/NPS#Pausing_or_running_the_sim_at_a_different_speed here].

Load Screenshots from FlightGear

2018-11-08T12:32:33Z

Lethargi: Adding final information on how the functions should be called

Telemetry

2017-09-15T09:19:50Z

Lethargi: /* Step 1 */ changed "conf/messages.xml" to "sw/ext/pprzlink/message_definitions/v1.0/messages.xml"

== Messages ==

Telemetry messages (sent from the aircraft to the ground) are defined in the telemetry class of [https://github.com/paparazzi/paparazzi/blob/master/conf/messages.xml conf/messages.xml].
See also the generated documentation: http://docs.paparazziuav.org/latest/paparazzi_messages.html

== Sending periodic messages ==
The set of periodic messages sent over the downlink channel by an aircraft to the ground station is configurable
with the help of one XML file, located in the <tt>conf/telemetry</tt> directory. This file is referenced by <tt>conf/conf.xml</tt> and must follow the
<tt>telemetry.dtd</tt> syntax. The <tt>fixedwing_default.xml</tt> and <tt>rotorcraft_default.xml</tt> are provided as an example and should be suitable for most users.
{{Box Code|default.xml|
<source lang="xml"><!DOCTYPE telemetry SYSTEM "telemetry.dtd">
<telemetry>
<process name="Ap">
<mode name="default">
<message name="ATTITUDE" period="0.5"/>
<message name="PPRZ_MODE" period="5"/>
<message name="SOME_MODULE_MSG" period="2" module="module_name"/>
...
</mode>
<mode name="fast attitude">
<message name="ATTITUDE" period="0.1"/>
</mode>
</process>
<process name="Fbw">
<mode name="default">
<message name="COMMANDS" period="1"/>
...
</mode>
<mode name="debug">
<message name="PPM" period="0.5"/>
</mode>
</process>
</telemetry></source>
}}

If a [[Modules|module]] attribute is specified for a message, it will be included in the telemetry only if the corresponding module is loaded.

It is even possible to create your own telemetry XML definition. By the time you need that, it is highly likely you are already an advanced paparazzi user and know why you would and how you will.

===Add Messages===

This section provides instructions of an example case of how one would add a new message to Paparazzi and send the data to the ground station. The example is a little old and considers the addition of the AIRSPEED message, which is already present in newer versions of paparazzi. The user will have to implement her own message objects instead of the AIRSPEED message.

==== Step 1 ====

In sw/ext/pprzlink/message_definitions/v1.0/messages.xml add an airspeed message:
{{Box Code|sw/ext/pprzlink/message_definitions/v1.0/messages.xml|
<source lang="xml">
<message name="AIRSPEED" id="54">
<field name="adc_airspeed" type="uint16"/>
<field name="estimator_airspeed" type="float" unit="m/s"/>
<field name="airspeed_setpoint" type="float" unit="m/s"/>
<field name="airspeed_controlled" type="float" unit="m/s"/>
<field name="groundspeed_setpoint" type="float" unit="m/s"/>
</message>
</source>}}
Where id="54" has to be unique. To find an new ID to use there is a script file located at ${PAPARAZZI_HOME}/sw/tools/find_free_msg_id.out (yes it is really a script).

Type: ${PAPARAZZI_SRC}/sw/tools/find_free_msg_id.out

NOTE: Be sure your Paparazzi source and home environment variables are set correctly in your shell [[Installation#Launching_the_Software]])

Every field in the output is a variable from Paparazzi. The type must be the type of a variable in your code (ie. look in your code). Add your message along with the frequency to be sent over the messaging bus (AKA telemetry messages).

After making the modifications to the messages.xml file, make your paparazzi again (i.e. cd ${PAPARAZZI_HOME} && make) so that your changes to the messages.xml file are reflected in the paparazzi/var/include/messages.h file. This will create a DOWNLINK_SEND_AIRSPEED macro (in ${PAPARAZZI_HOME}/var/include/messages.h). If you do not make paparazzi, this macro will not be created.

==== Step 2 ====

Add a message to your telemetry file (for example conf/telemetry/default_fixedwing.xml). The message name in telemetry file usually match the message name in messages.xml file, but can be different or even group several messages.
{{Box Code|conf/telemetry/default.xml|
<source lang="xml">
<telemetry>
<process name="Ap">
<mode name="default">
<message name="ALIVE" period="5"/>
<message name="GPS" period="0.25"/>
<message name="AIRSPEED" period="1"/>
....
</source>
}}

The result is a generated file in ${PAPARAZZI_HOME}/var/aircrafts/<AC>/generated/periodic_telemetry.h which consist in a (static) scheduler to that calls specific functions.

==== Step 3 ====

Create a function in your C source file that will send your message(s) (using the generated DOWNLINK_SEND_* macros) and register it to the telemetry system so that it will be send automatically for you. You also need to include the header <tt>subsystems/datalink/telemetry.h</tt>:
{{Box Code|firmware/fixedwing/autopilot.c|

<source lang="c">
...
#include "subsystems/datalink/telemetry.h"

static void send_airspeed(struct transport_tx *trans, struct link_device *dev)
{
pprz_msg_send_AIRSPEED(trans, dev, AC_ID,
&airspeed, &v_ctl_auto_airspeed_setpoint,
&v_ctl_auto_airspeed_controlled, &v_ctl_auto_groundspeed_setpoint);
}

...
void autopilot_init(void) {
...
register_periodic_telemetry(DefaultPeriodic, PPRZ_MSG_ID_AIRSPEED, send_airspeed);
...
}
</source>
}}
where the second parameter in the register function is the id of the message (use the define <tt>PPRZ_MSG_ID_<MESSAGE_NAME></tt>).

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
Prior to '''v5.0''':
<div class="mw-collapsible-content">Past Reference for Paparazzi v5.0 or older:
Create a PERIODIC_SEND_AIRSPEED with the following code in the firmware specific telemetry header file (In ap_downlink.h/fbw_downlink.h for fixedwing or telemetry.h for rotorcraft) :
{{Box Code|conf/telemetry/default.xml|
<source lang="c">
#ifdef USE_AIRSPEED
#define PERIODIC_SEND_AIRSPEED(_chan) DOWNLINK_SEND_AIRSPEED (_chan, _dev &adc_airspeed_val,&estimator_airspeed,&v_ctl_auto_airspeed_setpoint,&v_ctl_auto_airspeed_controlled,&v_ctl_auto_groundspeed_setpoint)
#else
#define PERIODIC_SEND_AIRSPEED(_chan) {}
#endif
</source>
</div></div>

===Configuring the Downlink Data Rate===

The limited throughput of our RF modems results in a need to carefully choose which data to send, as well as the frequency at which to send it. A sophisticated set of files and parameters have been developed in order to tailor the data downlink behavior automatically, manually, temporarily, or permanently according to any desired parameter. This allows the user to create an almost unlimited possibility of downlink configurations. For example:
* Tailor the data rate to work with very slow modems (9600 baud or slower)
* Reduce the data rate of some messages so that others can be increased:
*: Automatically send GPS data at a very high rate by sacrificing navigation data when not flying (to help GPS/RFI troubleshooting) then automatically reduce the GPS data rate and send normal navigation data when the launch is initiated.
*: Automatically switch to sending only position data upon landing to conserve power and increase the chance of the operator receiving a position packet when recovering a distant aircraft.
*: Manually send selected sensor data at very high speeds (60Hz) for real time tuning.
* Maintain independent telemetry configurations for aircraft with different modems, sensors, or mission profiles.

Any number of configuration files can be created in the <tt>conf/telemetry</tt> directory and selected from the <tt>conf/conf.xml</tt> file. The telemetry downlink is divided into two processes, '''Ap''' and '''Fbw''' each with a possible <tt>mode</tt> option. Any number of modes could be created, the default is the first in the sequence. A mode contains the list of messages to be sent as well as the period of each message in seconds. In this example, the '''ATTITUDE''' message will be sent by the '''Ap''' process at 2Hz in the default mode and at 10Hz in the '''fast attitude''' mode. The maximum allowed frequency is 60Hz (0.017s) and the maximum period is 1092s.

The mode can be chosen in the airframe file by setting the '''TELEMETRY_MODE_FBW''' constant:
<source lang="xml"><define name="TELEMETRY_MODE_FBW" value="1"/></source>
where the (default) first mode is numbered '''0'''.

This mode can also be changed dynamically with a datalink [[#Settings|setting]] or with a [[Flight_Plans#set|set]] stage in the flight plan.

Note that an (undocumented!) subset of the messages is required to be able to use ground station properly. So it is not advisable to completely remove messages for the '''Ap''' process listed in the default mode.

==Specific Messages==

===GPS_SOL===
Specification in telemetry file
<source lang="xml">
<message name="GPS_SOL" period="2.0"/>
</source>
Example from logfile(.data):
6.742 1 GPS_SOL 232 43 198 8

Meaning of tokens:
Timestamp, Aircraft-Number, GPS_SOL, Pacc, Sacc, PDOP, numSV

*Pacc = Position accuracy (units: CM)
*Sacc = Speed accuracy (units: CM/sec ?)
*PDOP = Position [http://en.wikipedia.org/wiki/Dilution_of_precision_%28GPS%29 Dilution_of_precision_(GPS)] , if this value is high the value of position will be less accurate
*numSV = number of Space Vehicles (Satellites) used in Nav Solution

===PPRZ_MODE===
Specification in telemetry file
<source lang="xml">
<message name="PPRZ_MODE" period="5."/>
</source>
Example from logfile(.data):
20.433 2 PPRZ_MODE 0 1 2 0 0 1

Meaning of tokens:
Timestamp, Aircraft-Number, PPRZ_MODE, ap_mode, ap_gaz, ap_horizontal, if_calib_mode, mcul_status
*ap_mode = (0 = MANUAL, 1 = AUTO1, 2 = AUTO2, 3 = HOME mode (Circle Home waypoint), 4 = NO_GPS (GPS not working), 5 = NB (?)
*ap_gaz = ?
*ap_horizontal = ?
*if_calib_mode = ?
*mcul_status = ?

== Audio-based downlink ==

The audio-based downlink has been removed from current hardware designs however using the old designs it is possible to implement. With the current low prices of a simple video transmitter, data over audio may come in as a welcomed addition. Feel free to experiment and revive this classical feature.

[[Category:Software]] [[Category:User_Documentation]] [[Category:Telemetry]]

Telemetry

2017-09-15T08:55:57Z

Lethargi: /* Step 1 */ changed "find_msg_id.out" to "find_free_msg_id.out"

== Messages ==

Telemetry messages (sent from the aircraft to the ground) are defined in the telemetry class of [https://github.com/paparazzi/paparazzi/blob/master/conf/messages.xml conf/messages.xml].
See also the generated documentation: http://docs.paparazziuav.org/latest/paparazzi_messages.html

== Sending periodic messages ==
The set of periodic messages sent over the downlink channel by an aircraft to the ground station is configurable
with the help of one XML file, located in the <tt>conf/telemetry</tt> directory. This file is referenced by <tt>conf/conf.xml</tt> and must follow the
<tt>telemetry.dtd</tt> syntax. The <tt>fixedwing_default.xml</tt> and <tt>rotorcraft_default.xml</tt> are provided as an example and should be suitable for most users.
{{Box Code|default.xml|
<source lang="xml"><!DOCTYPE telemetry SYSTEM "telemetry.dtd">
<telemetry>
<process name="Ap">
<mode name="default">
<message name="ATTITUDE" period="0.5"/>
<message name="PPRZ_MODE" period="5"/>
<message name="SOME_MODULE_MSG" period="2" module="module_name"/>
...
</mode>
<mode name="fast attitude">
<message name="ATTITUDE" period="0.1"/>
</mode>
</process>
<process name="Fbw">
<mode name="default">
<message name="COMMANDS" period="1"/>
...
</mode>
<mode name="debug">
<message name="PPM" period="0.5"/>
</mode>
</process>
</telemetry></source>
}}

If a [[Modules|module]] attribute is specified for a message, it will be included in the telemetry only if the corresponding module is loaded.

It is even possible to create your own telemetry XML definition. By the time you need that, it is highly likely you are already an advanced paparazzi user and know why you would and how you will.

===Add Messages===

This section provides instructions of an example case of how one would add a new message to Paparazzi and send the data to the ground station. The example is a little old and considers the addition of the AIRSPEED message, which is already present in newer versions of paparazzi. The user will have to implement her own message objects instead of the AIRSPEED message.

==== Step 1 ====

In conf/messages.xml add an airspeed message:
{{Box Code|conf/messages.xml|
<source lang="xml">
<message name="AIRSPEED" id="54">
<field name="adc_airspeed" type="uint16"/>
<field name="estimator_airspeed" type="float" unit="m/s"/>
<field name="airspeed_setpoint" type="float" unit="m/s"/>
<field name="airspeed_controlled" type="float" unit="m/s"/>
<field name="groundspeed_setpoint" type="float" unit="m/s"/>
</message>
</source>}}
Where id="54" has to be unique. To find an new ID to use there is a script file located at ${PAPARAZZI_HOME}/sw/tools/find_free_msg_id.out (yes it is really a script).

Type: ${PAPARAZZI_SRC}/sw/tools/find_free_msg_id.out

NOTE: Be sure your Paparazzi source and home environment variables are set correctly in your shell [[Installation#Launching_the_Software]])

Every field in the output is a variable from Paparazzi. The type must be the type of a variable in your code (ie. look in your code). Add your message along with the frequency to be sent over the messaging bus (AKA telemetry messages).

After making the modifications to the messages.xml file, make your paparazzi again (i.e. cd ${PAPARAZZI_HOME} && make) so that your changes to the messages.xml file are reflected in the paparazzi/var/include/messages.h file. This will create a DOWNLINK_SEND_AIRSPEED macro (in ${PAPARAZZI_HOME}/var/include/messages.h). If you do not make paparazzi, this macro will not be created.

==== Step 2 ====

Add a message to your telemetry file (for example conf/telemetry/default_fixedwing.xml). The message name in telemetry file usually match the message name in messages.xml file, but can be different or even group several messages.
{{Box Code|conf/telemetry/default.xml|
<source lang="xml">
<telemetry>
<process name="Ap">
<mode name="default">
<message name="ALIVE" period="5"/>
<message name="GPS" period="0.25"/>
<message name="AIRSPEED" period="1"/>
....
</source>
}}

The result is a generated file in ${PAPARAZZI_HOME}/var/aircrafts/<AC>/generated/periodic_telemetry.h which consist in a (static) scheduler to that calls specific functions.

==== Step 3 ====

Create a function in your C source file that will send your message(s) (using the generated DOWNLINK_SEND_* macros) and register it to the telemetry system so that it will be send automatically for you. You also need to include the header <tt>subsystems/datalink/telemetry.h</tt>:
{{Box Code|firmware/fixedwing/autopilot.c|

<source lang="c">
...
#include "subsystems/datalink/telemetry.h"

static void send_airspeed(struct transport_tx *trans, struct link_device *dev)
{
pprz_msg_send_AIRSPEED(trans, dev, AC_ID,
&airspeed, &v_ctl_auto_airspeed_setpoint,
&v_ctl_auto_airspeed_controlled, &v_ctl_auto_groundspeed_setpoint);
}

...
void autopilot_init(void) {
...
register_periodic_telemetry(DefaultPeriodic, PPRZ_MSG_ID_AIRSPEED, send_airspeed);
...
}
</source>
}}
where the second parameter in the register function is the id of the message (use the define <tt>PPRZ_MSG_ID_<MESSAGE_NAME></tt>).

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
Prior to '''v5.0''':
<div class="mw-collapsible-content">Past Reference for Paparazzi v5.0 or older:
Create a PERIODIC_SEND_AIRSPEED with the following code in the firmware specific telemetry header file (In ap_downlink.h/fbw_downlink.h for fixedwing or telemetry.h for rotorcraft) :
{{Box Code|conf/telemetry/default.xml|
<source lang="c">
#ifdef USE_AIRSPEED
#define PERIODIC_SEND_AIRSPEED(_chan) DOWNLINK_SEND_AIRSPEED (_chan, _dev &adc_airspeed_val,&estimator_airspeed,&v_ctl_auto_airspeed_setpoint,&v_ctl_auto_airspeed_controlled,&v_ctl_auto_groundspeed_setpoint)
#else
#define PERIODIC_SEND_AIRSPEED(_chan) {}
#endif
</source>
</div></div>

===Configuring the Downlink Data Rate===

The limited throughput of our RF modems results in a need to carefully choose which data to send, as well as the frequency at which to send it. A sophisticated set of files and parameters have been developed in order to tailor the data downlink behavior automatically, manually, temporarily, or permanently according to any desired parameter. This allows the user to create an almost unlimited possibility of downlink configurations. For example:
* Tailor the data rate to work with very slow modems (9600 baud or slower)
* Reduce the data rate of some messages so that others can be increased:
*: Automatically send GPS data at a very high rate by sacrificing navigation data when not flying (to help GPS/RFI troubleshooting) then automatically reduce the GPS data rate and send normal navigation data when the launch is initiated.
*: Automatically switch to sending only position data upon landing to conserve power and increase the chance of the operator receiving a position packet when recovering a distant aircraft.
*: Manually send selected sensor data at very high speeds (60Hz) for real time tuning.
* Maintain independent telemetry configurations for aircraft with different modems, sensors, or mission profiles.

Any number of configuration files can be created in the <tt>conf/telemetry</tt> directory and selected from the <tt>conf/conf.xml</tt> file. The telemetry downlink is divided into two processes, '''Ap''' and '''Fbw''' each with a possible <tt>mode</tt> option. Any number of modes could be created, the default is the first in the sequence. A mode contains the list of messages to be sent as well as the period of each message in seconds. In this example, the '''ATTITUDE''' message will be sent by the '''Ap''' process at 2Hz in the default mode and at 10Hz in the '''fast attitude''' mode. The maximum allowed frequency is 60Hz (0.017s) and the maximum period is 1092s.

The mode can be chosen in the airframe file by setting the '''TELEMETRY_MODE_FBW''' constant:
<source lang="xml"><define name="TELEMETRY_MODE_FBW" value="1"/></source>
where the (default) first mode is numbered '''0'''.

This mode can also be changed dynamically with a datalink [[#Settings|setting]] or with a [[Flight_Plans#set|set]] stage in the flight plan.

Note that an (undocumented!) subset of the messages is required to be able to use ground station properly. So it is not advisable to completely remove messages for the '''Ap''' process listed in the default mode.

==Specific Messages==

===GPS_SOL===
Specification in telemetry file
<source lang="xml">
<message name="GPS_SOL" period="2.0"/>
</source>
Example from logfile(.data):
6.742 1 GPS_SOL 232 43 198 8

Meaning of tokens:
Timestamp, Aircraft-Number, GPS_SOL, Pacc, Sacc, PDOP, numSV

*Pacc = Position accuracy (units: CM)
*Sacc = Speed accuracy (units: CM/sec ?)
*PDOP = Position [http://en.wikipedia.org/wiki/Dilution_of_precision_%28GPS%29 Dilution_of_precision_(GPS)] , if this value is high the value of position will be less accurate
*numSV = number of Space Vehicles (Satellites) used in Nav Solution

===PPRZ_MODE===
Specification in telemetry file
<source lang="xml">
<message name="PPRZ_MODE" period="5."/>
</source>
Example from logfile(.data):
20.433 2 PPRZ_MODE 0 1 2 0 0 1

Meaning of tokens:
Timestamp, Aircraft-Number, PPRZ_MODE, ap_mode, ap_gaz, ap_horizontal, if_calib_mode, mcul_status
*ap_mode = (0 = MANUAL, 1 = AUTO1, 2 = AUTO2, 3 = HOME mode (Circle Home waypoint), 4 = NO_GPS (GPS not working), 5 = NB (?)
*ap_gaz = ?
*ap_horizontal = ?
*if_calib_mode = ?
*mcul_status = ?

== Audio-based downlink ==

The audio-based downlink has been removed from current hardware designs however using the old designs it is possible to implement. With the current low prices of a simple video transmitter, data over audio may come in as a welcomed addition. Feel free to experiment and revive this classical feature.

[[Category:Software]] [[Category:User_Documentation]] [[Category:Telemetry]]

Load Screenshots from FlightGear

2017-07-24T15:08:59Z

Lethargi: included more of the stuff that it needs; more is on the way

Load Screenshots from FlightGear

2017-07-24T09:56:41Z

Lethargi: A page describing how to obtain screenshots from FlightGear into the memory of PaparazziUAV for simple computer vision tasks

Simulation

2017-07-24T09:21:36Z

Lethargi: /* View the simulation in Flight Gear */ added a subsection to link to a page which has instructions on how to obtain screenshots from FlightGear

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Simulation</categorytree>
__TOC__

This page describes the steps needed to run a simulated flight with an UAS.

== Available Simulators ==

Paparazzi currently has two different simulator targets with different degrees of realism and intended purpose:

# '''sim''': The basic fixedwing simulator written in OCaml without IMU simulation or any sensor models (noise, bias, etc) and mainly intended to test [[Flight_Plans|flight plan]] logic.
# '''nps''': [[NPS]] is a more advanced rotorcraft and fixedwing simulator with sensor models and commonly uses [[JSBSim]] as FDM ('''F'''light '''D'''ynamic '''M'''odel). Other FDM's can be integrated easily. At the moment CRRCSIM, YASIM and JSBSIM are tried as FDM backend.

A FDM is a set of mathematical equations used to calculate the physical forces acting on a simulated aircraft, such as thrust, lift, and drag.

== Compiling and starting ==

'''This describes the basic fixedwing sim, for rotorcraft or advanced fixedwing simulation, see [[NPS]].'''

From the [[Paparazzi_Center|Paparazzi Center]] select the Microjet aircraft (from the '''A/C''' combo box) which is configured with the <tt>basic.xml</tt> flight plan. From the '''Target''' combo box, select <tt>sim</tt> and click the '''Build''' button to compile the airbone code to be run on your Linux box. From the '''Session''' combo box, select <tt>Simulation</tt> entry and click '''Execute''' to start the simulation. It will start
three processes which are listed in the window below:
* '''Microjet''' is the interface of a simulator program. It runs the same code as the one for the autopilot processor plus a rudimentary flight dynamic model. it allows you to test the interactions with the UAV and the flight plan execution.
* '''GCS''' ([[GCS|Ground Control Station]]) is the main window. It displays the track of the aircraft, as well as informations about the execution of its flight plans. This program provide menus for the datalink functions and is able to edit a flight plan.
* '''Server''' is a hidden process which won't be described here (see [[Overview|the architecture of the system]])

== Start the Simulation ==

The aircraft has automatically been booted, as if the autopilot board had been powered. Its position and its flight parameters are displayed in the GCS window. If you omit the -boot option of the sim the aircraft is not automatically booted and you can first place the aircraft where you want it to start from and then boot.

If the --norc option is ommited, a window for a virtual remote control (including on/off switch and a mode-switch) is started, see: [https://wiki.paparazziuav.org/wiki/Joystick#Virtual_Joystick_.28only_for_SIM_targets.29 Virtual Joystick]

In the GCS the map widget is able to use many map formats and display them according to many projections. To make things simple, we start by using images from [http://maps.google.com Google]. From the toolbar in the top right corner of the GCS, click the Google Earth icon ('''Google maps fill'''). The program attempts to download the required satellite images from the Google servers. If it succeeds, you should now see the nice countryside of Muret (a city close to Toulouse, France). Navigation and other features of the map are described on the [[GCS#map|GCS]] page.

The lower part of the GCS displays the flight plan in a tree view. You see that the current flight plan is composed of several ''blocks'':
* '''wait GPS''' and '''geo init''' which are instructions to run this flight plan anywhere in the world, by translating the waypoints around the current location of aircraft as soon as it is reported by the GPS.
* '''Holding point''' (it should be the current active block) which instructs the autopilot to wait for launch.
* '''Takeoff''' which will instruct the aircraft to climb full throttle to a security altitude
* '''Standby''' which is a simple circle around the '''STDBY''' waypoint.

Switch to the '''Takeoff''' block by a double click on the line or using the corresponding button (an icon figuring an airway) on the left side of the strip.

== Fly ==

In the Simulator ('''Microjet''' window), press the '''Launch''' button to simulate a hand launch or click the launch button in the GCS (the green aircraft icon). The autopilot detects the launch by monitoring the groundspeed. The flight time (in the aircraft label on the GCS) then starts to count.

Position of the aircraft is displayed on the map: the aircraft goes to the '''CLIMB''' waypoint (to the norht-west) and then around the '''STDBY''' waypoint. Current block also changes accordingly in the flight plan display.

The orange triangle (the carrot) on the map is the point that the aircraft is navigating toward.

== Line ==

Jump to this block with double-click on the <tt>Line 1-2</tt> line in the flight plan or using the corresponding button in the strip (figuring a blue line between two white points). The aircraft will try to follow a line joining the waypoints '''1''' and '''2''', doing nice U-turns at both ends.

=== Move waypoints ===

While the aircraft is flying (or here while the simulator is integrating differential equations), you can move the waypoints on the GCS interface by cliking and dragging (with the left button). When the mouse button is released, a popup window allows you to change the altitude of the waypoint. After validation, the waypoint changes are sent to the autopilot and the followed track is changed accordingly.

=== Coming back around ===

Select the '''Standby''' block (the ''home'' blue icon) to instruct the aircraft to fly around the '''STDBY''' waypoint.

== Fly too far ==

If you unzoom the map (using the PageDown key or he mouse wheel), you will see a large circle around the waypoints. This circle show the allowed flying zone that the autopilot must not leave or it will enter an emergency navigation mode and circles the '''HOME''' waypoint until the further direction is received.

Move the waypoint '''2''' out of this circle (close to the circle in the north-east corner) and switch back to the 'Line 1-2''' block to force the plane to get out of this safety zone.

The aircraft flies to the '''2''' waypoint, cross the protection enveloppe and switches to ''home'' mode: the AP mode in the aircraft strip switches from '''AUTO2''' to '''HOME'''.

To get out of this mode and switch back to the default '''AUTO2''', click on the '''AUTO2''' button in the aircraft strip. The aircraft then flies again towards '''too far''' and again swithes to '''HOME''' mode.

== Change the environment ==

Launch the '''Environment Simulator''' from the '''Tools' menu in the '''Paparazzi Center'''.

[[file:PPRZ_Environment_settings_Gaia_GUI_up.png]]

This interface, also known as '''Gaia''', allows the user to change:

* The time-scale: This make the simulation of the flight speed up time, good if you have a extensive flightpland and you do not want to wait the real time it would taketo fly the aircraft in a real life flight. It is best not use a times-cale higher than 2x for a first tryout.
* The Wind speed: Set the wind speed while simulating. Try to set it to e.g. 5m/s and observe the trajectory and the speed evolution in the aircraft strip and in the '''PFD''' page of the notebook
* The Wind direction: Set the direction the wind comse from. For fun try to take of with stong wind from the side.
* Wind up: Simulates updraft (e.g. by thermals) or downdraft wind (beside thunderstorms or in mountains), which could e.g. shift the UAS higher than permitted, which can be counteracted by exceptions in the flightplan.
* A GPS failure: Simulate GPS loss on the aircraft ('''GPS OFF''') and observe the resulting mode ('''NO_GPS''') and trajectory. In this mode, the autopilot can for example use a the failsafe roll, pitch and throttle settings defined in the airframe file. Note that in a real flight, an aircraft without GPS won't be able to send it's position ... The simulation is cheating here! It must, otherwise not possible to show the path in the simulator ofcourse.

Environment Simulator, Gaia can also be started with initial values set by command line option.

-b Bus Default is 127.255.255.255:2010
-t Set time scale (default: 1.0)
-w Set wind speed (0-30m/s)
-d Set wind direction 0-359 deg
-g Turn off GPS
-help Display this list of options
--help Display this list of options

If you are in the testfield and forgot the parameters, just use the "help"

$ ./gaia --help

This make testing more convienient since on can save a session with this parameters and on restart imidately have the same settings again.

=== Example ===

Starting gaia with the following parameters on the command line:

$ sw/simulator/gaia -t 3 -d 340 -w 11

This sets a 3x speedup of the time with wind coming from 340 degrees with a windspeed of 11m/s

== Other navigation patterns ==

Using the buttons in the strip, you can play with other navigation patterns: figure of eights, oval, survey of a rectangle (with a north-south sweeping), ''Circle around here'' (which sets a waypoint to the current location of the plane and flies a circle around).

== Landing ==

To automatically land the aircraft:
* Set the '''TD''' (Touch Down) waypoint where you want to land. Be sure that the waypoint is on the ground (185m in Muret)
* Set the '''AF''' (Approach Fix) waypoint where you want to start the final descent (the ''glide''). If you have set some wind with Gaia, you probably want to fly '''AF-TD''' upwind (an estimation of the wind experienced by the aircraft is displayed in the left-upper corner of the map).
* Switch to the '''Land right''' or the '''Land left''' block (icons in the strip) according to the direction of the last turn you want to do (for example, if '''AF''' is on the east side of '''TD''' and you want to maneuvre from the north, choose a '''Land right''')

== Multiple UAV Simulation ==

To simulate multiple aircrafts, you just have to launch a second simulator (tools->simulator, then -a yourairframe) and the server and the GCS should take care of the rest.

== View the simulation in Flight Gear ==

To view the simulation in [[FlightGear]], do the following:
* [[FlightGear|install Flight Gear]]
* In Paparazzi Center, add the option <tt>--fg_host 127.0.0.1</tt> (replace the IP address if FG is running on another host as appropriate) to the Simulator line and restart it, e.g.:
<path_to_paparazzi>/sw/simulator/pprzsim-launch --aircraft <your_ac_name> -t sim --boot --norc --fg_host 127.0.0.1
<div class="toccolours mw-collapsible mw-collapsed">
Prior to '''v5.0''' launchsitl was used instead of pprzsim-launch. Click expand to see the details.
<div class="mw-collapsible-content">
<path_to_paparazzi>/sw/simulator/launchsitl -a <your_ac_name> -boot -norc -fg 127.0.0.1
</div></div>
* Launch Flight Gear with the following command:
fgfs --fdm=null --native-gui=socket,in,30,,5501,udp

=== Old version ===
For Flight Gear visualization, version 2.12 or greater with rembrand visualisation options switched on is the nicest. If you wish to use a very old version, Flightgear v2.4 or lower, you must add the following to the firmware section of your airframe file:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="fixedwing or rotorcraft">
...
<define name="FG_2_4" value="1"/>
...
</firmware>
</source>
}}

=== Obtain Screenshots from FlightGear into PaparazziUAV ===

One can write a relatively simple module in order to obtain screenshots of the FlightGear world into the PaparazziUAV software. This can be useful to simulate low fidelity computer vision tasks with UAVs. The module requires libcurl and libpng to make the screenshot data available to PaparazziUAV. Detailed instructions are available in [[Load Screenshots from FlightGear]].

[[Category:Simulation]] [[Category:Software]] [[Category:User_Documentation]]

Flight Plans

2017-04-05T16:25:29Z

Lethargi: /* Loops */ Put in a suggested maximum range for for loops

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

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

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

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

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

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

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.
* A waypoints index/reference pointer is derived by prefixing the waypoint name with "WP_". Useful when a [[#Call |call function]] uses the waypoints reference index vs. it's name.

== Sectors ==

=== Static sectors (default) ===

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

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

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

=== Dynamic sectors ===

With the latest version (v5.5-devel-628), it is possible to create dynamic sectors. The procedure to create the sector is the same than for the static version with an extra attribute '''type="dynamic"''':
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red" type="dynamic">
<corner name="C1"/>
<corner name="C2"/>
<corner name="C3"/>
<corner name="C4"/>
</sector>
</sectors>
</source>

It is also recommended to avoid using hidden waypoints (no _ prefix), so you can move the corner of your sector from the GCS. The polygon is updated on the 2D map to reflect the new waypoints positions.
Beside the possibility to change the shape of the area in flight, one of the main benefit is that the algorithm behind allows concave hulls. The only restriction is that the edges of the polygon should not cross each other.

The generated function is the same than the static version and can be used the same way.

== Variables ==

'''Available since v5.9'''

It is possible to declare a list of variables that will be automatically created during the flight plan generation and available for the rest of the system from the generated flight plan header and of course inside the flight plan itself. With appropriate attributes, it is also possible to make the variables accessible from the telemetry as a [[Settings|setting]].

The following code will produce a '''float''' variable initialized to 0:
<source lang="xml">
<variables>
<variable var="my_var"/>
</variables>
</source>

The type and the initial value can be changed with the '''type''' and '''init''' attributes:
<source lang="xml">
<variables>
<variable var="my_var" init="10" type="int"/>
</variables>
</source>

To produce an automatic setting for a variable, at least '''min''', '''max''' and '''step''' attributes need to be specified:
<source lang="xml">
<variables>
<variable var="my_var" min="0." max="10." step="0.1"/>
</variables>
</source>
They will appear under the '''Flight Plan''' settings tab in the GCS. So more attributes can be specified: '''shortname''', '''unit''', '''alt_unit''', '''alt_unit_coef''', '''values'''. See [[Settings]] page for more information about these options.

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

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

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

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

==== 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 [[Flight_Plans#Internal_Variables_in_Flight_Plans|internal variables section]] below and other examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learning to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== 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:
<source lang="xml"><exception cond="..." deroute="..."></source>
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:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

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

=== Deroute ===

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

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

=== Return ===

The <tt>return</tt> is also a ''goto'' directive that brings you back to the last block (and last stage). It has no argument.
<source lang="xml"><return/></source>

=== Loops ===

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:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, letting the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
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:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at an altitude above ground of 50m (1x50), 10 seconds at an altitude of 100m (2x50), ... until 250m (5x50).

Note: Two bounded loops using the same control variable are not allowed in the same block. Further, I tested a specific implementation installation of PaparazziUAV v5.10 and I found the maximum range of the looping variable to be -128 to 126.

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point 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:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

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

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

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

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

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

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

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

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

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

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
'''Works only for Fixed-wing!''' Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Survey rectangle ===
Fly a survey rectangle defined by two waypoints. The distance between the legs of the grid (in meter) and the orientation of the grid (NS or WE) can be set by the operator. The plane will turn outside of the border of the rectangle before starting a new leg.
<source lang="xml"> <survey_rectangle wp1="1" wp2="2" grid="200" orientation="NS"/> </source>

=== Follow ===

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.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>

=== Stay ===

The <tt>stay</tt> Here the UAS with try to stay at the waypoint as best as it can. For an aircraft capable of hovering it will just hang above the waypoint. For a fixedwing type UAV,<tt>stay</tt> will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.
<source lang="xml"><stay wp="HOME" alt="10"/></source>

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

=== 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):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
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:
<source lang="xml">
<call fun="nav_line_setup()"/>
<call fun="nav_line_run(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_setup()</tt> returns FALSE and <tt>nav_line_run()</tt> always returns TRUE (this stage never ends). '''Note''' that a waypoints index is derived/denoted by prefixing the waypoint name with <tt>WP_</tt>(i.e.: 1 --> WP_1, 2 --> WP_2)
<br />

To call ''any'' function exactly once regardless of the return value (e.g. call a void function), add <tt>loop="FALSE"</tt>
<source lang="xml">
<call fun="viewvideo_take_shot(TRUE)" loop="FALSE"/>
</source>
or use the <tt>call_once</tt> alias:
<source lang="xml">
<call_once fun="viewvideo_take_shot(TRUE)"/>
</source>

Such extra navigation functions are usually written as a [[Modules|Module]] and the header files are included automatically.

If you want to call functions that are not part of a module, you need to include the header file which contains the function declaration:or supplementary C file which must be specified in the
<source lang="xml">
<header>
#include "path/to/header.h"
</header>
</source>
where the path is relative to the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continuously on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

=== Pre Call ===

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

=== Post Call ===

<source lang="xml">
<block name="traj" pre_call="formation_pre_call()" post_call="formation_flight()"> 
</source>

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

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

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

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

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

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

== Internal Variables in Flight Plans ==

The flight plan can use several internal variables, macros and functions coming from the rest of the system or the flight plan API itself. The following list present some of the most commonly used variables, but much more are actually available:

* '''autopilot_flight_time''': time in seconds since autopilot was booted (integer)
* '''datalink_time''': time in seconds since last connection of telemetry to ground control station (including ''subsystems/datalink/datallink.h'' in the '''header''' section is required) (integer)
* '''GetPosAlt()''': returns the current altitude above ground level in meter (float)
* '''GetPosX()''': returns x (easting) of current position relative to reference in meter (float)
* '''GetPosY()''': returns y (northing) of current position relative to reference in meter (float)
* <s>'''ground_alt''': altitude above ground level in meter (float)</s> (v5.8 and higher - use '''GetAltRef()''' instead)
* '''GetAltRef()''': returns reference altitude, usually ground_alt
* '''NavSetGroundReferenceHere()''': reset position and altitude reference point to current position
* '''NavSetAltitudeReferenceHere()''': reset altitude reference to current alt but keep previous horizontal position reference
* '''NavSetWaypointHere(_wp)''': set position of a waypoint given as argument to the current position
* '''WaypointX(_wp)''': returns x (easting) of waypoint position relative to reference in meter (float)
* '''WaypointY(_wp)''': returns y (northing) of waypoint position relative to reference in meter (float)
* '''WaypointAlt(_wp)''': returns waypoint altitude in meter (float)
* '''nav_radius''': free variable usually used to set circle radius in flight plan
* '''NavKillThrottle()''': function to switch off throttle
* '''PowerVoltage()''': returns current voltage of the battery
* all functions from the [http://docs.paparazziuav.org/latest/group__state__interface.html state interface API]
* all functions from the [http://docs.paparazziuav.org/latest/subsystems_2navigation_2waypoints_8h.html waypoint API]
* all variables declared in [[modules]] headers

== Advanced Examples ==

Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

Below you find some random examples of the posibilities. This is only the tip of the iceberg, use your imagination and go wild with new creative ideas for your flightplan

=== Gains on the fly ===

It is very well possible to set specific gain for an airframe if it reaches e.g a certain block.

=== Dynacmically adjustable maximum speed ===

<source lang="xml">
<call_once fun="gh_set_max_speed(2.0)"/>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the h_ctl_disabled flag:

<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

=== V5.8+ ===
* If you don't like the '''No SRTM data found to check altitude''' warning, either in your flight plan editor or in GCS itself click on the '''Nav->display SRTM'''. It will ask you whether you want to download SRTM data. Say yes, and it will save the data in ''data/srtm'' directory, so you don't get the warning any more and check the ground altitude even without GPS.

[[Category:Software]] [[Category:User_Documentation]]

NPS

2017-04-04T18:04:59Z

Lethargi: /* Running the Simulation */ Added a line linking about setting up environment variables before trying to run from terminal

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Simulation</categorytree>
__TOC__

== Introduction ==

NPS ('''N'''ew '''P'''aparazzi '''S'''imulator) is a more advanced simulator with sensor models and can use different FDM backends. By default [[JSBSim]] is used as FDM (FlightDynamicModel) backend, this allow fairly complex airframes.
JSBSim can be replaced by the FDM of your choice, e.g. YASim or a interconnection with MATLAB simulink

NPS is capable of simulating rotorcraft and fixedwing airframes, with the possibility to add more complex aircrafts/hybrids if a proper model is built using one of the FDM backends.

== Usage ==

See [[Installation|installation of Paparazzi]], [[JSBSim]] and optionally [[FlightGear]] (for visualization).

=== Configuration/Build ===
Add the '''nps''' target to your [[Airframe_Configuration|airframe]] with the fdm you want to use:
{{Box Code|conf/airframes/myaircraft.xml|
<source lang="xml">
<firmware name="rotorcraft or fixedwing">
<target name="nps" board="pc">
<subsystem name="fdm" type="jsbsim"/>
</target>
...
</firmware>
</source>
}}
then depending on the aircraft you want to simulate add a NPS simulator section which defines the model, actuators and sensor parameters used:

E.g for a simple quadrotor:
{{Box Code|conf/airframes/myaircraft.xml|
<source lang="xml">
<section name="SIMULATOR" prefix="NPS_">
<define name="ACTUATOR_NAMES" value="front_motor, right_motor, back_motor, left_motor" type="string[]"/>
<define name="JSBSIM_MODEL" value="simple_quad" type="string"/>
<define name="SENSORS_PARAMS" value="nps_sensors_params_default.h" type="string"/>
</section>
</source>
}}
You can also take a look at the example airframe [https://github.com/paparazzi/paparazzi/blob/master/conf/airframes/examples/quadrotor_lisa_m_2_pwm_spektrum.xml conf/airframes/examples/quadrotor_lisa_m_2_pwm_spektrum.xml] or use it for your first tests.

E.g for a fixedwing like a Bixler,Easystar, etc:
{{Box Code|conf/airframes/myaircraft.xml|
<source lang="xml">
<section name="SIMULATOR" prefix="NPS_">
<define name="JSBSIM_LAUNCHSPEED" value="15"/>
<define name="JSBSIM_MODEL" value="easystar" type="string"/>
<define name="SENSORS_PARAMS" value="nps_sensors_params_default.h" type="string"/>
</section>
</source>
}}

* NPS_ACTUATOR_NAMES: mapping of the motors defined in the [[Rotorcraft_Configuration#Motor_Mixing|MOTOR_MIXING section]] to the actuators in the JSBSim model (the order is important, also make sure that your motors in JSBSim spin in the same direction as your real ones)
* NPS_SENSORS_PARAMS: the parameter file for the sensor simulation (noise/delay) under ''conf/simulator/nps/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/nps/nps_sensors_params_default.h nps_sensors_params_default.h])
* NPS_JSBSIM_MODEL: name of the JSBSim model in ''conf/simulator/jsbsim/aircraft/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/jsbsim/aircraft/simple_quad.xml simple_quad]), if not defined it defaults to AIRCRAFT_NAME
* NPS_JSBSIM_INIT: the xml file containing the initial conditions (location, attitude, wind) for JSBSim in ''conf/simulator/jsbsim/aircraft/'' (e.g. [https://github.com/paparazzi/paparazzi/blob/master/conf/simulator/jsbsim/aircraft/reset00.xml reset00])<br>This define is optional and if not specified the initial position of the aircraft will be set to the flight plan location. Prior to v5.1 this was called INITIAL_CONDITITONS.
* NPS_JSBSIM_LAUNCHSPEED: if defined this sets an initial launchspeed in m/s for fixedwings, available since v5.1.0_testing-54-g2ac094f
* NPS_JS_*: Joystick mappings, see [http://docs.paparazziuav.org/latest/nps__radio__control__joystick_8c.html]
Then build the nps target...

== Running the Simulation ==

The most convenient way to start the simulation is via the ''Simulation'' session from the [[Paparazzi Center]].
Just select e.g. the Quad_LisaM_2 example airframe and start the ''Simulation'' session with the simulator, GCS and server.

If you have added PAPARAZZI_HOME AND PAPARAZZI_SRC to the environmental variables of your terminal (See [[Installation#Environment_Variables|Setting up environment variables]]), you can also start it via the generic simulation launcher:
<source lang="bash">sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps</source>

<div class="toccolours mw-collapsible mw-collapsed">
Prior to '''v5.0''' pprzsim-launch was not available. Click expand to see the details.
<div class="mw-collapsible-content">
In earlier versions, start your tools (e.g. [[GCS]], [[server]] and messages) separately, then launch the nps simulator for your aircraft directly:
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl</source>
</div></div>

=== Options ===
Start the simulator with the ''--help'' option to list them all.

* ''--ivy_bus'': Set ivy bus broadcast address to use (default 127.255.255.255, 224.255.255.255 on OSX)
* ''--rc_script'': Execute script with specified number to emulate RC input.
* ''--js_dev'': Use joystick for radio control (specify index, normally 0), also see [[NPS#Use_a_Joystick]].
* ''--spektrum_dev'': Spektrum device to use for radio control (e.g. /dev/ttyUSB0)
* ''--fg_host'': Host for FlightGear visualization (e.g. 127.0.0.1)
* ''--fg_port'': Port on FlightGear host to connect to (Default: 5501)
* ''--fg_time_offset'': FlightGear time offset in seconds (e.g. 21600 for 6h), this is useful if it is currently night at the location you are flying and you want to add an offset to fly in daylight. (Since ''v4.9_devel_413-g9d55d6f)

=== Typical Simulation ===
In general you go through the same steps as with the real aircraft:
* It should start on the ground and you have to wait a few seconds until the AHRS is aligned.
* If you have a (simulated) RC, you can now arm the motors and fly around in manual.
* To fly autonomously, make sure your ''AUTO2'' mode is ''NAV'', you can change it in the GCS->settings->system->auto2.
** Switch to it if you are using an RC, otherwise you should already be in this mode.
** Arm your motors: either via the resurrect button or by going to the ''Start Motors'' block of the [[Flight Plans|Flight Plan]].
** Takeoff: via the takeoff button or the corresponding flight plan block.
* Do your stuff... :-)

=== Pausing or running the sim at a different speed ===
If you start the simulation from a terminal, hit ''CTRL-z'' to pause it. You can then enter a different time factor (default 1.0) to make the simulation run slower or faster than real-time. Hit enter to resume the simulation or ''CTRL-z'' again to suspend it like any normal Unix process (use the ''fg'' (foreground) command to un-suspend it again).

This simulation speed parameter ?can be edited? in a configuration file : FIXME

=== Use a Joystick ===
You can use a [[joystick]] (or connect your RC transmitter as a joystick) to control the quad in the simulator.
<source lang="bash">sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps --js_dev 0</source>
or directly calling the nps simsitl binary:
<source lang="bash">./var/Quad_LisaM_2/nps/simsitl --js_dev 0</source>

Joystick support uses the Simple DirectMedia Layer (SDL) library. Rather than specifying an input device name as one normally does on Linux, you just supply an index value (0, 1, 2,...) of the device you wish to use. Typically, the order of devices is the order in which you plugged them into your computer. The sim will display the name of the device being used to double check. If the <tt>-j</tt> option is used with no argument, the sim defaults to using device on index 0 (which is usually correct if you have only one joystick attached).

Also see [[Joystick#Calibration]].

=== Visualization in [[FlightGear]] ===
[[FlightGear#Installation|Install]] and [[FlightGear#Using_FlightGear_for_Visualization|start flightgear]], e.g. with a quadrotor model:
<source lang="bash">fgfs --fdm=null --native-gui=socket,in,30,,5501,udp --prop:/sim/model/path=Models/Aircraft/paparazzi/mikrokopter.xml</source>
restart your simulator with the ''--fg_host'' option:
<source lang="bash">sw/simulator/pprzsim-launch --aircraft Quad_LisaM_2 --type nps --fg_host 127.0.0.1</source>

=== Troubleshooting ===
* If you get an error like "JSBSim failed to open the configuration file: (null)/conf/simulator/jsbsim/aircraft/BOOZ2_A1.xml", you need to set your $PAPARAZZI_SRC and $PAPARAZZI_HOME environment variables. Add the following to your .bashrc, change paths according to where you put Paparazzi. Open a new terminal and launch the sim again.
export PAPARAZZI_SRC=~/paparazzi
export PAPARAZZI_HOME=~/paparazzi

* If you did not install the jsbsim package your JSBSim installation under /opt/jsbsim will be used and you will have to set your library path (either in your shell startup file or when running the sim on the command line), e.g.:
LD_LIBRARY_PATH=/opt/jsbsim/lib ./var/Quad_LisaM_2/nps/simsitl --fg_host 127.0.0.1

* If you get an error like "fatal error: gsl/gsl_rng.h: No such file or directory", you need to install the GNU Scientific Library and corresponding development packages (libgsl).

* If you get an error like "undefined reference to `pcre_compile'", edit file conf/Makefile.nps, look for the line that begins with LDFLAGS and add -lpcre, e.g.:
LDFLAGS += $($(TARGET).LDFLAGS) -lpcre

==== Simulating Multiple Aircraft ====
When simulating multiple aircraft, the ''-udp_broadcast'' argument needs to be specified as part of the datalink invocation:
$PAPARAZZI_HOME/sw/ground_segment/tmtc/link -udp -udp_broadcast

In the case of Mac OS X, the IP ADDR must also be specified:
$PAPARAZZI_HOME/sw/ground_segment/tmtc/link -udp -udp_broadcast -udp_broadcast_addr <your_network_broadcast_ip_addr>

You can determine the IP ADDR for your network using '''ifconfig''' command:
<pre>
$ ifconfig
...
en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
ether 60:03:08:8e:14:9e
inet6 fe80::6203:8ff:fe8e:149e%en0 prefixlen 64 scopeid 0x4
inet 192.168.1.59 netmask 0xffffff00 broadcast 192.168.1.255
nd6 options=1<PERFORMNUD>
media: autoselect
status: active
...
</pre>

Based on the above sample output, the invocation would look like the following:
$PAPARAZZI_HOME/sw/ground_segment/tmtc/link -udp -udp_broadcast -udp_broadcast_addr 192.168.1.255

== Usage Examples ==

=== Plot the value of a message field ===
Start the [[RTPlotter|real-time plotter]] tool menu of [[Paparazzi Center]] or with
<source lang="bash">./sw/logalizer/plotter</source>
for example drag the label 'int32 phi' from the ROTORCRAFT_FP message to the drawing area of the plotter

* Use the datalink to change the telemetry mode
start 'settings' ( from the tool menu of paparazzi center) or with
./sw/ground_segment/tmtc/settings -ac Quad_LisaM_2
start 'server' to dispatch datalink messages ( from the tool menu of paparazzi center) or with
./sw/ground_segment/tmtc/server
change the field "telemetry" on the first page to "Att loop" and send by pressing the green check button. The label on the left or the drop box should change to "Att loop" confirming your message has been received. "message" should now show that the message "STAB_ATTITUDE_INT" is received

=== Tuning the attitude control loop ===
Here we are going to use the simulator to demonstrate a way of tuning the attitude control loop for a multicopter (rotorcraft firmware only).

* Restart your previous session
* Set telemetry mode to "attitude_loop"
* Display two real time plotter windows

In the first one, plot the field "m_phi" from the "STAB_ATTITUDE_int" message. This is our estimation of roll angle.
On top of that, plot the field "phi" from the "STAB_ATTITUDE_REF_INT" message. This is our reference roll angle, that is, the roll value we are trying to achieve.

In the second plotter, plot the fields "delta_a_fb" and "delta_a_ff". Those are respectively the feedback and feedforward part of our roll command. The sum of those two terms is what is used as roll command.The feedforward part is the part used to follow our trajectory and the feedback part is the part used to reject perturbations.

* In "Settings", go to the "Att Loop" tab
We notice that the vehicle doesn't follow the step trajectory we are trying to make him do accurately.

Start by setting the value of the proportional gain ('pgain_phi') to 1000 instead of 400. The vehicle now follows the trajectory faster but overshoots. To prevent that, increase the value of the derivative gain ('dgain p') from 300 to 700.

If you look at the plotter where you're plotting the commands, you'll notice that during steps, the feedback command has to work hard. This means that our feedforward command is badly tuned, and namely not working hard enough. Increase the value of the feedforward gain ('ddgain p') from 300 to 540. You'll notice that now the feedback command has become marginal during the steps. This is the right value for the gain. Anything bigger will make the feedback command fight against the feedforward command during steps, anything smaller will make the feedback command have to complement the feedforward command.

[[Category:Simulation]] [[Category:Software]] [[Category:User_Documentation]]

GCS Configuration

2017-03-31T18:25:35Z

Lethargi: /* Video plugin */ Made some grammatical changes near the ending. changed the last line to direct people to the discussion if all else fails

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>GCS</categorytree>
__TOC__

== Paparazzi Center ==
The paparazzi center is launched with the following command:
<tt>./sw/supervision/paparazzicenter</tt>
and is used to launch individual portions of the GCS (''Programs'') or the entire GCS (''Sessions'') with the modem and map settings defined in <tt><b>/conf/control_panel.xml</b></tt>

===Configuration Options===

Here all the commandline parameter to set specific option(s) while launching the GCS. To use these edit the file conf/control_panel.xml in the line that says <program name="GCS" command="sw/ground_segment/cockpit/gcs"> add the options, for example: <br>
<program name="GCS" command="sw/ground_segment/cockpit/gcs -fullscreen"><br>

'''-auto_ortho''', IGN tiles path
'''-b''', <ivy bus> Default is 127.255.255.255:2010
'''-center''', Initial map center (e.g. 'WGS84 43.605 1.443')
'''-center_ac''', Centers the map on any new A/C
'''-edit''', Flight plan editor
'''-fullscreen''', Fullscreen window
'''-maps_fill''', Automatically start loading background maps
'''-maps_zoom''', Background maps zoomlevel (default: 18, max: 22)
'''-ign''', IGN tiles path
'''-lambertIIe''', Switch to LambertIIe projection
'''-layout''', <XML layout specification> GUI layout. Default: horizontal.xml
'''-m''', Map XML description file
'''-maximize''', Maximize window
'''-mercator''', Switch to (Google Maps) Mercator projection, default
'''-mplayer''', Launch mplayer with the given argument as X plugin
'''-no_alarm''', Disables alarm page
'''-no_confirm_kill''', Disable the additional kill conformation dialog
'''-maps_no_http''', Switch off downloading of maps, always use cached maps
'''-ortho''', IGN tiles path
'''-osm''', Use OpenStreetMap database (default is Google)
'''-ms''', Use Microsoft maps database (default is Google)
'''-particules''', Display particules
'''-plugin''', External X application (launched with the id of the plugin window as argument)
'''-ref ''',Geographic ref (e.g. 'WGS84 43.605 1.443')
'''-speech''', Enable vocal messages
'''-srtm''', Enable SRTM elevation display
'''-track_size''', Default track length (500)
'''-utm''', Switch to UTM local projection
'''-wid''', <window id> Id of an existing window to be attached to
'''-zoom''', Initial zoom
'''-auto_hide_fp''', Automatically hide flight plans of unselected aircraft
'''-help''', Display a list of options

=== Video plugin ===

The <tt>-mplayer</tt> option of GCS allows to the user to display a video stream in a window of the GCS. The video window can also be exchanged with the map by clicking anywhere inside the frame.
Use the following line in your <tt>/conf/control_panel.xml</tt> to enable the video window.
<tt>path_to_ground_segment/cockpit/gcs -mplayer rtsp://localhost:7070/video</tt>
A useful example follows:
If you have an Avermedia DVB-T usb tuner like the Aver-Tv Hybrid Volar HX (Avermedia finally released Ubuntu Linux drivers)
then in order to use the usb tuner as video input to the GCS you have to complete the following steps:

First download and install the drivers and check that the Usb tuner works well by opening a console window
and typing:

'''mplayer tv:// -tv driver=v4l2:width=320:height=240:norm=NTSC:input=1:device=/dev/video1:noaudio'''

Of course you must connect a video signal to the composite input first.
Then close the console and remove the Usb tuner.
Now it is time to configure the control_panel.xml file by editing the GCS command line.
Locate the line in the "control_panel.xml" usually located in /Your Paparazzi directory/conf/ (mine is in "/paparazzi/conf/")
that looks similar to the below line:
<source lang="xml">
<program name="GCS" command="sw/ground_segment/cockpit/gcs -layout horizontal.xml">
</source>

Then edit it so it looks like this:

<source lang="xml">
<program name="GCS" command="sw/ground_segment/cockpit/gcs -layout horizontal.xml -mplayer 'tv:// -tv driver=v4l2:width=320:height=240:norm=NTSC:input=1:device=/dev/video1:alsa:adevice=hw.2,0:amode=1:audiorate=48000:forceaudio:volume=100:immediatemode=0'">
<arg flag="-b" variable="ivy_bus"/>
</program>
</source>

The above line is one complete and uninterrupted line but it is just too long to show it in one line here.
(There is a space after the"-tv" like this "-mplayer 'tv:// -tv driver=v4l2:...." but nowhere else after that).
This will load the mplayer, select the composite video input of the tuner and enable the sound input.
Please remember to change the "NTSC" with "PAL" if you do not use the NTSC video system (if your airborne camera is PAL for example).
Read the mplayer documentation so you can tweak the resolution etc. later to suit your particular setup.
The resolution above is set to 320x240 here but you can set it to 640x480 by replacing the numbers in the command line above.
If You forget to set the arg parameter, then GCS will not meet through window handlers with mplayer and the video will not appear! This time you see an mplayer <defunct> on the process list.

Finally you have to add the plugin widget to your GCS layout configuration file.
If you noticed the GCS command line in the "control_panel.xml" file, a part of it reads "-layout horizontal.xml"
so our configuration file is the "horizontal.xml" which is located always in "/Your Paparazzi directory/conf/gcs/".
Open the file and add or uncomment the line below (in "horizontal.xml" the plugin widget is there but commented out):

<source lang="xml">
<widget NAME="plugin" SIZE="300"/>
</source>

Now the file should look like this:

<source lang="xml">
<rows>
<widget size="500" name="map2d"/>
<columns>
<rows size="375">
<widget size="200" name="strips"/>
</rows>
<widget size="400" name="aircraft"/>
<widget name="alarms"/>
<widget NAME="plugin" SIZE="300"/>
</columns>
</rows>
</source>

All the above works fine in Ubuntu 10.04 LTS. It should work fine on different versions of Ubuntu too. If it does not, look for solution in other wiki pages and the PaparazziUAV documentations. If all else fails discuss your issue in the [https://gitter.im/paparazzi/discuss PaparazziUAV Gitter discussion].

== Layout ==
The layout of the different components (map, strips, ...) of the gcs is configurable through a ''style'' XML file located in <tt>conf/gcs/</tt>. The specification is done via a combination of rows and columns. The default layout is given in the <tt>horizontal.xml</tt> file:

<source lang="xml">
<!DOCTYPE layout SYSTEM "layout.dtd">
<layout width="1024" height="768">
<rows>
<widget size="500" name="map2d"/>
<columns>
<rows size="350">
<widget size="120" name="strips"/>
<widget name="alarms"/>
</rows>
<widget size="400" name="aircraft"/>
<widget size="00" name="plugin"/>
</columns>
</rows>
</layout>
</source>

Default size ('''1024x768''') of the whole window is specified in the root of the tree. The window is then divided in two rows:
* the <tt>map2d</tt> with a requested height of '''500'''
* a set of columns containing
** a set of rows of width '''350''' divided into
**: the '''strips''' frame of height '''120'''
**: the '''alarms''' frame
** the notebook frame ('''aircraft''') of width '''400'''
** the video plugin frame

This second example (<tt>left_col.xml</tt>) sets the map and the notebook on the right and the other frames in a left column:

<source lang="xml">
<!DOCTYPE layout SYSTEM "layout.dtd">
<layout width="1024" height="768">
<columns>
<rows size="360">
<widget size="120" name="strips"/>
<widget size="300" name="plugin"/>
<widget name="alarms"/>
</rows>
<rows>
<widget name="map2d"/>
<widget name="aircraft"/>
</rows>
</columns>
</layout>
</source>

This layout file is chosen with the <tt>-layout</tt> option:
<tt>path_to_ground_segment/cockpit/gcs -layout left_col.xml</tt>

[[Category:GCS]] [[Category:User_Documentation]]

Flight Plans

2017-03-29T19:37:18Z

Lethargi: /* Loops */ fixed some typos and grammar at the last bit

A '''flight plan''' is a XML document which one can create and store aboard an autopilot. The flight plan will describe how you want your aircraft to travel if released into into the wild blue yonder.

== DTD and Structure ==

The formal description of the flight plan file is given in the [http://en.wikipedia.org/wiki/Document_Type_Definition '''DTD'''] (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML document using the following line:<br>

<source lang="xml"><!DOCTYPE flight_plan SYSTEM "flight_plan.dtd"></source>

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

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

'''A flight plan is composed of two mandatory elements: [[#waypoints|waypoints]] and [[#blocks|blocks]]'''

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt>'''<flight_plan name lat0 lon0 ground_alt security_height home_mode_height qfu alt max_dist_from_home>'''</tt>
; <tt>'''name'''</tt>: The name of the mission (a text string)
; <tt>'''lat0, lon0'''</tt>: Defines the latitude and longitude coordinates of the reference point {0,0} in WGS84 degree coordinates
; <tt>'''ground_alt'''</tt>: The ground altitude (in meters), Above Sea Level where you are flying. It defines the <tt>GROUND_ALT</tt> constant value which can be used in combination with a waypoint <height> parameter to define a waypoint height
; <tt>'''security_height'''</tt>: The height (over <tt>'''ground_alt'''</tt>) used by the circle-home failsafe procedure and in other flight procedures such as formation flight and anti-collision avoidance. Warnings are produced if you place a waypoint lower than <tt>'''security_height'''</tt> (usually the case for the landing point)
; <tt>'''home_mode_height'''</tt> (optional): This optional attribute available since v4.2 allows to override <tt>'''security_height'''</tt> as failsafe height in home mode. If <tt>'''home_mode_height'''</tt> Is set lower than <tt>'''security_height'''</tt>, the later is used. This attribute is useful if you need to return home at a high altitude rather than a low altitude.
; <tt>'''qfu'''</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft. So if you want to take off and climb to the West you would use qfu=270.
; <tt>'''alt'''</tt>: The default altitude of waypoints ([[Altitude_definitions|Above Sea Level]]). So if your ground altitude is 400 then alt needs to be a value greater than ground altitude and above any obstructions in the flight plan.
; <tt>'''max_dist_from_home'''</tt>: A radius representing the maximum allowed distance (in meters) from the HOME waypoint. Exceeding this value (ie flying outside the circle with this radius) will trigger an exception. It is up to you to define the block to be executed (ie what to do) for the exception.

''Here is an '''example''' of such a line in the top of a flight plan:''

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

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

In English the above flight plan says the name is Example Muret. The reference coordinates for the 0,0 point is: 43.46223 (lat) and 1.27289 (long). The flying site 0,0 location is 185m above sea level. The security height is 25m above 0,0 point or 210m above sea level. The default (ie if not defined in a waypoint this alt is used) altitude is 250m (above sea level). The home mode block altitude is defined to be 150m above sea level. Also, for security, a circle is defined with a radius that's 300m from 0,0 position. This is the max_dist_from_home value. Fly 301m from 0,0 and an exception is triggered. A useful block is to trigger/go to the home mode block and return to home when the aircraft flies outside the safety circle. Example flight plans are helpful for study before you build your own from scratch.

== Waypoints ==

The waypoints are the geographic locations used to specify the trajectories. A waypoint is specified by it's name and coordinates:
<tt>''' <waypoint name wpx wpy [alt] [height]/> '''</tt>
where wpx and wpy are real positional coordinates ( <tt>'''lat/lon'''</tt> ) '''or''' UTM coordinates ( <tt>'''utm_x0/utm_y0'''</tt> ) '''or''' relative coordinates ( <tt>'''x/y'''</tt> ) in meters from your reference point {0,0} . <tt>alt</tt> is an optional parameter and can be used to assign an altitude to a particular waypoint that is different from the globally defined <tt>alt</tt> parameter of the flightplan. The <tt>height</tt> attribute can be used to set the waypoint height relative to the [[Altitude_definitions|ground altitude]] (<tt>ground_alt</tt>) of the flight plan for this waypoint.

An example:
<source lang="xml">
<waypoints>
<waypoint name="HOME" x="0.0" y="30.0"/>
<waypoint name="BRIDGEOVERRIVER" x="-100.0" y="60.0" alt="270."/>
<waypoint name="MyBarn" x="-130.0" y="217.5" alt="3000."/>
<waypoint name="3" x="-30.0" y="50" height="50."/>
<waypoint name="4" x="-30.0" y="50." alt="ground_alt + 50"/>
<waypoint name="_MYHELPERSPOT" x="-30.0" y="60" height="50."/>
<waypoint name="_MYOTHERHELPERSPOT" x="-70.0" y="90" height="70."/>
<waypoint name="TOWER" lat="48.858249" lon="2.294494" height="324."/>
<waypoint name="MountainCAFE" utm_x0="360284.8" utm_y0="4813595.5" alt="1965."/>
</waypoints>
</source>

'''Tips'''
* Waypoints are easily adjusted with the [[Flight_Plan_Editor|flight plan editor]].
* If a waypoint name starts with an underscore ( _ ), the waypoint is '''not displayed''' in the GCS, except in editor mode.
* The maximum number of waypoints is 254.
* A waypoint named <tt>HOME</tt> is required if the failsafe HOME mode procedure is used.
* A waypoints index/reference pointer is derived by prefixing the waypoint name with "WP_". Useful when a [[#Call |call function]] uses the waypoints reference index vs. it's name.

== Sectors ==

=== Static sectors (default) ===

Flat ''Sectors'' can be described as an area defined by list of waypoint corners. Such an area will be displayed in the Ground Control Station (GCS) by colored lines connecting the cornerpoints.
A function is generated to check if a point, usually the aircraft itself, is ''inside'' this sector. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>MyBigGarden</tt> the generated function for the example here would be <tt>bool_t InsideMyBigGarden(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS. It would be great if one would help improving that part of the source code. Note that sector names are not allowed to contain spaces.

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

It is then possible to add an exception clause to your flightplan. For example if the aircraft for some reason flies outside this, defined by us, sector the airframe will fly to a standby waypoint. The exclamation mark (!) means the boolean operator <tt>NOT</tt> in this example. In regular language one would describe "If my airframe is NOT inside the MyBigGarden sector anymore then deroute it to the standby waypoint. In Flightplan "Speak" this is written like:
<source lang="xml">
<exception cond="! InsideMyBigGarden(GetPosX(), GetPosY())" deroute="standby"/>
</source>

NOTE: editing of the waypoints of the sector during the flight will not dynamically update the inside function. It will always check if the position is inside the original sector.

'''Tips'''
* A nice option in the corner notation is that one can add an underscore ( _ ) in front of the name; a corner or waypoint name that starts with an underscore is not displayed in the GCS. Only in editor mode it is visible. It is visible in editor mode, because if you the could not see it, it also would be not possible to edit or drag the corner or waypoint to another position.
* The color indicating the sector borders is not fixed but can be defined by oneself if wished for via the color attribute.

=== Dynamic sectors ===

With the latest version (v5.5-devel-628), it is possible to create dynamic sectors. The procedure to create the sector is the same than for the static version with an extra attribute '''type="dynamic"''':
<source lang="xml">
<sectors>
<sector name="MyBigGarden" color="red" type="dynamic">
<corner name="C1"/>
<corner name="C2"/>
<corner name="C3"/>
<corner name="C4"/>
</sector>
</sectors>
</source>

It is also recommended to avoid using hidden waypoints (no _ prefix), so you can move the corner of your sector from the GCS. The polygon is updated on the 2D map to reflect the new waypoints positions.
Beside the possibility to change the shape of the area in flight, one of the main benefit is that the algorithm behind allows concave hulls. The only restriction is that the edges of the polygon should not cross each other.

The generated function is the same than the static version and can be used the same way.

== Variables ==

'''Available since v5.9'''

It is possible to declare a list of variables that will be automatically created during the flight plan generation and available for the rest of the system from the generated flight plan header and of course inside the flight plan itself. With appropriate attributes, it is also possible to make the variables accessible from the telemetry as a [[Settings|setting]].

The following code will produce a '''float''' variable initialized to 0:
<source lang="xml">
<variables>
<variable var="my_var"/>
</variables>
</source>

The type and the initial value can be changed with the '''type''' and '''init''' attributes:
<source lang="xml">
<variables>
<variable var="my_var" init="10" type="int"/>
</variables>
</source>

To produce an automatic setting for a variable, at least '''min''', '''max''' and '''step''' attributes need to be specified:
<source lang="xml">
<variables>
<variable var="my_var" min="0." max="10." step="0.1"/>
</variables>
</source>
They will appear under the '''Flight Plan''' settings tab in the GCS. So more attributes can be specified: '''shortname''', '''unit''', '''alt_unit''', '''alt_unit_coef''', '''values'''. See [[Settings]] page for more information about these options.

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

== Blocks ==

Block elements are the main part of a flight plan: they describe each unit of the mission.
They are made of various primitives, called stages and exceptions, you can put one after the other. When a
stage (or a block) is finished, the autopilot goes to the next one. The behaviour after the last stage of the last block is undefined.

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<source lang="xml">
<!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|call|circle|deroute|stay|follow|survey_rectangle|for|return|eight|oval|home|path)*>
</source>

Example:
<source lang="xml">
<block name="circlehome">
<circle radius="75" wp="HOME"/>
</block>
</source>

You can add a button in the [[GCS#Strips|strip of the aircraft]] with the attribute <tt>strip_button</tt>:
<source lang="xml">
<block name="descent" strip_button="Descent">
<circle wp="HOME" throttle="0.0" pitch="-15" vmode="throttle"/>
</block>
</source>
This button will activate the block. If the attribute <tt>group</tt> is specified, all strip buttons of the same group will be placed vertically on top of each other.

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

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

==== 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 [[Flight_Plans#Internal_Variables_in_Flight_Plans|internal variables section]] below and other examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

Some examples of usable expressions are given in the next sections.
=== Initialization Blocks ===
Most flight plans will have three blocks of flight plan initialization blocks. It is good practice to follow this example below if you first start learning to create flightplans

The first block waits until the GPS fix has been established, as shown below.
<source lang="xml">
<blocks>
<block name="Wait GPS">
<set value="1" var="kill_throttle"/>
<while cond="!GpsFixValid()"/>
</block>
</source>
The second block updates the local waypoints with respect to the UAV.
<source lang="xml">
<block name="Geo init">
<while cond="LessThan(NavBlockTime(), 10)"/>
<call fun="NavSetGroundReferenceHere()"/>
</block>
</source>
This next block prevents the UAV from starting the engine and taking off.
<source lang="xml">
<block name="Holding point">

<set value="1" var="kill_throttle"/>
<attitude roll="0" throttle="0" vmode="throttle"/>
</block>
</source>

=== 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:
<source lang="xml"><exception cond="..." deroute="..."></source>
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:
<source lang="xml">
<exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > GetPosAlt())" deroute="go_up"/>
<exception cond="(autopilot_flight_time > 840)" deroute="quick_land"/>
</source>

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

=== Deroute ===

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

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

=== Return ===

The <tt>return</tt> is also a ''goto'' directive that brings you back to the last block (and last stage). It has no argument.
<source lang="xml"><return/></source>

=== Loops ===

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:
<source lang="xml">
<while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while>
</source>
In this example, we run an infinite loop, letting the aircraft try to go via waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<source lang="xml">
<for var="i" from="0" to="3">
...
</for>
</source>
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:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for>
</source>

In this example, the aircraft will circle around waypoint '''HOME''' for 10 seconds at an altitude above ground of 50m (1x50), 10 seconds at an altitude of 100m (2x50), ... until 250m (5x50).

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

=== Navigation modes ===

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* path : list of waypoints linked by ''go''
* circle : circle around a waypoint;
* oval : two half circles with a straight between two nav points
* eight : fly a figure of eight through a waypoint and around another
* stay : hold the position (hard to realize for a fixed-wing aircraft);
* follow : follow another aircraft;
* xyz : circle around a point 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:
<source lang="xml"><attitude roll="0" vmode="throttle", throttle="0.5"/></source>

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

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

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

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

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

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

=== Path ===

The <tt>path</tt> primitive is just a shorthand expression for a set of <tt>go</tt> primitives. A list of waypoints defined with the <tt>wpts</tt> attribute is pre-processed into a set of <tt>go</tt> primitives with the <tt>hmode</tt> attribute. For example:
<source lang="xml"><path wpts="wp1, wp2, wp3"/></source>

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

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

=== Oval ===
The oval consists of two half circles that are connected with two straight lines. This flight path is usefull when a IMU is used because the straights allow for level flight.
<source lang="xml"> <oval p1="1" p2="2" radius="nav_radius"/> </source>

=== Eight ===
'''Works only for Fixed-wing!''' Fly a figure of eight that consists of two straight legs that pass though the center and the center of the half circle at the end of the two legs is in the turn around waypoint. The altitude of the center waypoint is used for the entire figure. The turn around waypoint is moved to match radius given.
<source lang="xml"> <eight center="1" radius="nav_radius" turn_around="2"/> </source>

=== Survey rectangle ===
Fly a survey rectangle defined by two waypoints. The distance between the legs of the grid (in meter) and the orientation of the grid (NS or WE) can be set by the operator. The plane will turn outside of the border of the rectangle before starting a new leg.
<source lang="xml"> <survey_rectangle wp1="1" wp2="2" grid="200" orientation="NS"/> </source>

=== Follow ===

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.
<source lang="xml"><follow ac_id="4" distance="50" height="20"/></source>

=== Stay ===

The <tt>stay</tt> Here the UAS with try to stay at the waypoint as best as it can. For an aircraft capable of hovering it will just hang above the waypoint. For a fixedwing type UAV,<tt>stay</tt> will mean the aircraft will constantly fly straight through the waypoint in a flower like pattern with the smallest turn radius it can manage.
<source lang="xml"><stay wp="HOME" alt="10"/></source>

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

=== 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):
<source lang="xml"><set var="ground_alt" value="ground_alt+50"/></source>
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:
<source lang="xml">
<call fun="nav_line_setup()"/>
<call fun="nav_line_run(WP_1, WP_2, nav_radius)"/>
</source>
where <tt>nav_line_setup()</tt> returns FALSE and <tt>nav_line_run()</tt> always returns TRUE (this stage never ends). '''Note''' that a waypoints index is derived/denoted by prefixing the waypoint name with <tt>WP_</tt>(i.e.: 1 --> WP_1, 2 --> WP_2)
<br />

To call ''any'' function exactly once regardless of the return value (e.g. call a void function), add <tt>loop="FALSE"</tt>
<source lang="xml">
<call fun="viewvideo_take_shot(TRUE)" loop="FALSE"/>
</source>
or use the <tt>call_once</tt> alias:
<source lang="xml">
<call_once fun="viewvideo_take_shot(TRUE)"/>
</source>

Such extra navigation functions are usually written as a [[Modules|Module]] and the header files are included automatically.

If you want to call functions that are not part of a module, you need to include the header file which contains the function declaration:or supplementary C file which must be specified in the
<source lang="xml">
<header>
#include "path/to/header.h"
</header>
</source>
where the path is relative to the <tt>sw/airborne</tt> directory.

You can also call functions before or after each execution of the block (this means continuously on each iteration of each stage of the block, not just when entering o exiting the block).
<source lang="xml">
<block name="circlehome" pre_call="function_to_call_before_circle()" post_call="function_to_call_after_circle()">
<circle wp="HOME"/>
</block>
</source>

=== Pre Call ===

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

=== Post Call ===

<source lang="xml">
<block name="traj" pre_call="formation_pre_call()" post_call="formation_flight()"> 
</source>

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

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

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

Here is the corresponding procedure '''landing.xml''':
<source lang="xml">
<!DOCTYPE procedure SYSTEM "flight_plan.dtd">
<procedure>
<waypoints>
<waypoint name="AF" x="177.4" y="45.1" alt="30"/>
<waypoint name="TD" x="28.8" y="57.0" alt="0"/>
<waypoint name="_BASELEG" x="168.8" y="-13.8"/>
</waypoints>
<blocks>
...
<block name="land">
<call fun="nav_compute_baseleg(WP_AF, WP_TD, WP__BASELEG, nav_radius)"/>
<circle radius="nav_radius" until="NavCircleCount() > 0.5" wp="_BASELEG"/>
<circle radius="nav_radius" until="And(NavQdrCloseTo(DegOfRad(baseleg_out_qdr)-10), 10 > fabs(GetPosAlt()- WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>
...
</blocks>
</procedure>
</source>

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

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

== Internal Variables in Flight Plans ==

The flight plan can use several internal variables, macros and functions coming from the rest of the system or the flight plan API itself. The following list present some of the most commonly used variables, but much more are actually available:

* '''autopilot_flight_time''': time in seconds since autopilot was booted (integer)
* '''datalink_time''': time in seconds since last connection of telemetry to ground control station (including ''subsystems/datalink/datallink.h'' in the '''header''' section is required) (integer)
* '''GetPosAlt()''': returns the current altitude above ground level in meter (float)
* '''GetPosX()''': returns x (easting) of current position relative to reference in meter (float)
* '''GetPosY()''': returns y (northing) of current position relative to reference in meter (float)
* <s>'''ground_alt''': altitude above ground level in meter (float)</s> (v5.8 and higher - use '''GetAltRef()''' instead)
* '''GetAltRef()''': returns reference altitude, usually ground_alt
* '''NavSetGroundReferenceHere()''': reset position and altitude reference point to current position
* '''NavSetAltitudeReferenceHere()''': reset altitude reference to current alt but keep previous horizontal position reference
* '''NavSetWaypointHere(_wp)''': set position of a waypoint given as argument to the current position
* '''WaypointX(_wp)''': returns x (easting) of waypoint position relative to reference in meter (float)
* '''WaypointY(_wp)''': returns y (northing) of waypoint position relative to reference in meter (float)
* '''WaypointAlt(_wp)''': returns waypoint altitude in meter (float)
* '''nav_radius''': free variable usually used to set circle radius in flight plan
* '''NavKillThrottle()''': function to switch off throttle
* '''PowerVoltage()''': returns current voltage of the battery
* all functions from the [http://docs.paparazziuav.org/latest/group__state__interface.html state interface API]
* all functions from the [http://docs.paparazziuav.org/latest/subsystems_2navigation_2waypoints_8h.html waypoint API]
* all variables declared in [[modules]] headers

== Advanced Examples ==

Parameters used in a flight plan can be computed expressions. In this example, the plane is asked to perform 5 circles at progressively increasing altitudes for exactly one minute at each altitude:
<source lang="xml">
<for var="i" from="1" to="5">
<circle wp="HOME" radius="75"
alt="ground_alt + 50*$i"
until="stage_time > 60" />
</for>
</source>

Below you find some random examples of the posibilities. This is only the tip of the iceberg, use your imagination and go wild with new creative ideas for your flightplan

=== Gains on the fly ===

It is very well possible to set specific gain for an airframe if it reaches e.g a certain block.

=== Dynacmically adjustable maximum speed ===

<source lang="xml">
<call_once fun="gh_set_max_speed(2.0)"/>
</source>

=== Immobilize Actuators ===

h_ctl setpoints variable are set by the h_ctl_attitude_loop() (from fw_h_ctl.c) loop) which can be disabled with the h_ctl_disabled flag:

<source lang="xml">
<set var="h_ctl_disabled" value="TRUE"/>
<set var="h_ctl_aileron_setpoint" value="0"/>
<set var="h_ctl_elevator_setpoint" value="MAX_PPRZ/2"/>
.... waiting for a condition ...
<set var="h_ctl_disabled" value="FALSE"/>
</source>

== Tips and Tricks ==

There are many ways to skin a cat just as there are many ways to craft your flight plan. Following the best practices tips can save you from a lot of frustration and mishap.

* Simulate your flight plan before taking it to the sky. Flight plans should always be carefully tested prior to flight, take a look at the [[Simulation|simulation]] page for details on how to simulate your plan.
* Make an subdirectory in the Flight_plan directory with your own name and add your flight plans there. Make sure that the location of the DTD is correct, e.g by using relative directory double dots as in <tt><!DOCTYPE flight_plan SYSTEM "../flight_plan.dtd"></tt>

* Take a good look at other flight plans included with Paparazzi. To learn from example flight plans please visit the [[Flight_Plan_Examples|flight plan examples]] page
* There are several option to build failsafe features into you flightplan, [[Failsafe|for some examples visit the Failsafe page]].
* Some flight plan examples define waypoint locations using relative coordinates. These are relative positions from the fixed lat and lon in the header of the flight plan. When simulating your flight plan the aircraft always use the lat/lon as defined in the flight plan since a regular simulation has no notion of you current position of you local PC where you simulate on. This is something to keep in mind if you test your flight plan in real flights.

=== V5.8+ ===
* If you don't like the '''No SRTM data found to check altitude''' warning, either in your flight plan editor or in GCS itself click on the '''Nav->display SRTM'''. It will ask you whether you want to download SRTM data. Say yes, and it will save the data in ''data/srtm'' directory, so you don't get the warning any more and check the ground altitude even without GPS.

[[Category:Software]] [[Category:User_Documentation]]

Advanced Navigation Routines

2017-03-29T13:56:26Z

Lethargi: /* Navigation Routines (Prev.OSAM) */ : added the new path

= Introduction =

The flight plan standard navigation functions are very flexible. However sometimes one needs to perform a very specific task, and the basic functions are not enough to accomplish a special mission. In that case you can use additional modules functions in the flight plan. By adding a navigation capability to your airframe. The flight plan now has extra functionality that can be used.

= Available navigation modules =

== Navigation Routines (Prev.OSAM) ==

Thanks to Team OSAM's contribution these navigation capabilities have been added.

To use these navigation routines, you need to change the navigation subsystem type to extra in your airframe file. The navigation extra subsystem includes extra navigation routines like OSAMnav, spiral, poly_survey_advanced, nav_cube, etc.

<source lang="xml">
<subsystem name="navigation" type="extra"/>
</source>

Also include OSAMNav.h in your flight plan:

<source lang="xml">
#include "subsystems/navigation/OSAMNav.h"
</source>

'''NOTE''' The latest version of PaparazziUAV (v5.10 is the one I am using at the moment) does not have the OSAM navigation contributions as a subsystem but a module. It can be found in the link mentioned below. Not sure from which version the changes apply, but if you cannot find the header file in the subsystems folder, it is most probably in the modules folder.

sw/airborne/modules/nav

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

In our example the waypoints are called "Center" and "Edge":

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<waypoint name="Center" x="-20.0" y="-160.0"/>
<waypoint name="Edge" x="-10.0" y="-60.0"/>
</source>
}}

Then you can add flower to your flight plan:

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Flower">
<call fun="InitializeFlower(WP_Center,WP_Edge)"/>
<call fun="FlowerNav()"/>
</block>
</source>
}}

Note that in the function InitializeFlower the waypoints need the prefix "WP_".

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

{{Box Code|conf/airframes/myAircraft.xml|
<source lang="xml">
<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>
</source>
}}

You can add the bungee takeoff routine to your flight plan like so...

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Takeoff" strip_button="Takeoff (wp CLIMB)" strip_icon="takeoff.png">
<call fun="InitializeBungeeTakeoff(WP_Bungee)"/>
<call fun="BungeeTakeoff()"/>
</block>
</source>
}}

To get this routine to work consistently, 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.

<span style="color:#ff0000"> ***Precaution should be taken while tuning the auto takeoff with electrical plane. If the MinSpeed is too low, the prop could turn on while holding the aircraft!***</span>

<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 (-90 <-> 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 ====

You can add this navigation routine in your flight plan like so...

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
<call fun="PolygonSurvey()"/>
</block>
</source>
}}

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 -90 and 90 degrees.

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<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"/>
</source>
}}

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.

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<sectors>
<sector name="PolySector">
<corner name="S1"/>
<corner name="S2"/>
<corner name="S3"/>
<corner name="S4"/>
<corner name="S5"/>
</sector>
</sectors>
</source>
}}

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Init Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
</block>

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

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<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>
</source>
}}

=== Flight Line ===
The Flight Line Routine allows the user to map/follow one dimensional areas of interest like roads and rivers. Given two waypoints, the routine will automatically transition into the flight line to ensure full coverage between the waypoints. In addition, distances before and after the flight line can be used to add extra security to the coverage.

[[Image:OSAMFlightLineDiagram.png|Flight Line Diagram]]

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Map River">
<call fun="FlightLine(WP_R1,WP_R2,nav_radius,distance_before,distance_after)"/>
</block>
</source>
}}

Multiple flight lines can be daisy chained by reusing waypoints as shown below...

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Map River">
<call fun="FlightLine(WP_R1,WP_R2,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R2,WP_R3,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R3,WP_R4,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R5,WP_R6,nav_radius,100,100)"/>
<deroute block="Standby"/>
</block>
</source>
}}

However, the previous block can also be implemented using the FlightLineBlock function. The FlightLineBlock function works the same as the FlightLine function except it automatically steps through the waypoints between the given waypoints. Make sure the waypoints are declared in order or else it won't work!

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Map River">
<call fun="FlightLineBlock(WP_R1,WP_R6,nav_radius,100,100)"/>
<deroute block="Standby"/>
</block>
</source>
}}

<gallery>
Image:OSAMFlightLineExample.jpg |Multiple Flight Line Example
</gallery>

== misc ==

=== Border line ===

border_line is a nav-routine pretty similar to the nav-line-routine. You can use this nav-routine whenever you want to take care your plane stays on a defined site of a border.
For example you can use this routine to fly along a mountain and always turn away from the mountain ridge wall. Or use it fly along a border road without penetrating the other side of the border.

Use "extra" navigation subsystem with:
<source lang="xml">
<subsystem name="navigation" type="extra"/>
</source>

If you want to use waypoint 1 and 2 you can add border_line in your flight plan like this:
* Include header in "header" section at the beginning
#include "subsystems/navigation/border_line.h"
* Add function in a flight plan block:

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block group="extra_pattern" name="border line">
<call fun="border_line_init()"/>
<call fun="border_line(WP_1, WP_2, -nav_radius)"/>
</block>
</source>
}}

<gallery caption="example">
Image:border_line.png|Screen shot of border_line
Image:border_line2.png|Screen shot of border_line2
Image:border_line3.png|Screen shot of border_line3
</gallery>

=== GLS ===

GLS or '''G'''lobal Navigation Satellite System (GNSS) '''L'''anding '''S'''ystem adds advanced landing functions to your flightplan

It add the following capabilities:

# Fly via defined glide path angle
# In flight changeable landing direction without loosing the glide path angle!
# Smooth intercept, independent of approach angle or wind
# Separation of '''a'''pproach '''f'''ix, '''s'''tart '''d'''ecent and '''t'''op '''o'''f '''d'''ecent
# With fixed target speed (in airspeed mode only)

====GLS related abbreviations====

* GLS = '''G'''lobal Navigation Satellite System (GNSS) '''L'''anding '''S'''ystem
* TOD = '''t'''op '''o'''f '''d'''ecent
* AF = '''A'''pproach '''Fix'''
* SD = '''S'''tart '''D'''ecend
* TD = '''T'''ouch '''D'''own point, The spot where the plane should touch the ground for landing

====Configure====

What to add to your airframe.

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<section name="GLS_APPROACH" prefix="APP_">
<define name="ANGLE" value="5" unit="deg"/>
<define name="INTERCEPT_RATE" value="0.624" unit="m/s/s"/>
<define name="DISTANCE_AF_SD" value="20" unit="m"/>
<define name="TARGET_SPEED" value="14" unit="m/s"/>
</section>
</source>
}}

ANGLE - angle from TOD to TD

DISTANCE_AF_SD - minimum distance (meter) between AF and SD to allow the plane to self stabilize before the intercept starts (e.g. for speed reduction)

You can set the landing direction by moving the approach fix (AF) in relation to the touch down point (TD).
If you try to set the AF close to the TD you will see how the top of decent (TOD) and start decent (SD) is calculated and if necessary the AF is moved backwards.
(please try in simulation)

TARGET_SPEED - desired airspeed from AF to TD

INTERCEPT_RATE -

e.g. no wind: TARGET_SPEED = 14m/s and ANGLE = 10 --> desired decent rate 2.5 m/s (speed * tan(ANGLE))

with an INTERCEPT_RATE of 0.624 m/s/s it will take 4s to intercept the final approach path (desired decent rate / intercept_rate)

the idea is that the INTERCEPT_RATE is unique to each plane and will not change with different approach angles

to find an appropriate value you can start with a lower (to match 8s for example) and increase it until the intercept will be made from above

in general: bigger plane - smaller value!

how to setup your flightplan.xml:

<source lang="xml">
<waypoints>
<waypoint height="150" name="AF" x="-260.6" y="-344.6"/>
<waypoint name="SD" x="-1600." y="-36."/>
<waypoint name="TOD" x="-1600." y="-36."/>
<waypoint height="0.0" name="TD" x="-27.2" y="-243.5"/>
<waypoint height="266.0" name="_BASELEG" x="-1652.1" y="-113.5"/>
</waypoints>

<block name="land">
<call fun="gls_init(WP_AF,WP_SD, WP_TOD, WP_TD)"/>
<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)-(nav_radius/fabs(nav_radius))*10),
10 > fabs(GetPosAlt() - WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<call fun="gls(WP_AF,WP_SD, WP_TOD, WP_TD)"/>
</block>
</source>

those pictures match the old gls routine! anyway - the new one is not much different... (POS I = SD)
<gallery caption="theory">
Image:gls1.png|side view
Image:gls2.png|from above
Image:gls3.png|screen shot of flight test
</gallery>

== Multi-UAV ==
For TCAS (Traffic Collision Avoidance System) see the [[MultiUAV]] page.

[[Category:Software]] [[Category:Navigation]] [[Category:User_Documentation]]

= Create a navigation module =

Creating a navigation module is not to complex. Have said that, it is not very likely to need to create one module oneself. The already available functions are very flexible and powerful. Before you set of to create and additional navigation module, make sure you understand all current modules and their capabilities. After you investigated current modules and came to the conclusion, there is no way to solve you flightplan mission by creating a new module, go ahead and plz share your work with the community. The more people test the new module, the faster it will reach a stable state.

Advanced Navigation Routines

2017-03-29T13:52:40Z

Lethargi: /* Navigation Routines (Prev.OSAM) */ : put a note mentioning that the newer versions of PaparazziUAV does not OSAM as a subsystem but a module

= Introduction =

The flight plan standard navigation functions are very flexible. However sometimes one needs to perform a very specific task, and the basic functions are not enough to accomplish a special mission. In that case you can use additional modules functions in the flight plan. By adding a navigation capability to your airframe. The flight plan now has extra functionality that can be used.

= Available navigation modules =

== Navigation Routines (Prev.OSAM) ==

Thanks to Team OSAM's contribution these navigation capabilities have been added.

To use these navigation routines, you need to change the navigation subsystem type to extra in your airframe file. The navigation extra subsystem includes extra navigation routines like OSAMnav, spiral, poly_survey_advanced, nav_cube, etc.

<source lang="xml">
<subsystem name="navigation" type="extra"/>
</source>

Also include OSAMNav.h in your flight plan:

<source lang="xml">
#include "subsystems/navigation/OSAMNav.h"
</source>

'''NOTE''' The latest version of PaparazziUAV (v5.10 is the one I am using at the moment) does not have the OSAM navigation contributions as a subsystem but a module. Not sure from which version the changes apply, but if you cannot find the header file in the subsystems folder, it is most probably in the modules folder.

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

In our example the waypoints are called "Center" and "Edge":

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<waypoint name="Center" x="-20.0" y="-160.0"/>
<waypoint name="Edge" x="-10.0" y="-60.0"/>
</source>
}}

Then you can add flower to your flight plan:

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Flower">
<call fun="InitializeFlower(WP_Center,WP_Edge)"/>
<call fun="FlowerNav()"/>
</block>
</source>
}}

Note that in the function InitializeFlower the waypoints need the prefix "WP_".

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

{{Box Code|conf/airframes/myAircraft.xml|
<source lang="xml">
<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>
</source>
}}

You can add the bungee takeoff routine to your flight plan like so...

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Takeoff" strip_button="Takeoff (wp CLIMB)" strip_icon="takeoff.png">
<call fun="InitializeBungeeTakeoff(WP_Bungee)"/>
<call fun="BungeeTakeoff()"/>
</block>
</source>
}}

To get this routine to work consistently, 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.

<span style="color:#ff0000"> ***Precaution should be taken while tuning the auto takeoff with electrical plane. If the MinSpeed is too low, the prop could turn on while holding the aircraft!***</span>

<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 (-90 <-> 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 ====

You can add this navigation routine in your flight plan like so...

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
<call fun="PolygonSurvey()"/>
</block>
</source>
}}

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 -90 and 90 degrees.

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<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"/>
</source>
}}

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.

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<sectors>
<sector name="PolySector">
<corner name="S1"/>
<corner name="S2"/>
<corner name="S3"/>
<corner name="S4"/>
<corner name="S5"/>
</sector>
</sectors>
</source>
}}

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Init Poly Survey">
<call fun="InitializePolygonSurvey(WP_S1, NumOfCorners, SweepWidth, Orientation)"/>
</block>

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

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<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>
</source>
}}

=== Flight Line ===
The Flight Line Routine allows the user to map/follow one dimensional areas of interest like roads and rivers. Given two waypoints, the routine will automatically transition into the flight line to ensure full coverage between the waypoints. In addition, distances before and after the flight line can be used to add extra security to the coverage.

[[Image:OSAMFlightLineDiagram.png|Flight Line Diagram]]

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

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Map River">
<call fun="FlightLine(WP_R1,WP_R2,nav_radius,distance_before,distance_after)"/>
</block>
</source>
}}

Multiple flight lines can be daisy chained by reusing waypoints as shown below...

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Map River">
<call fun="FlightLine(WP_R1,WP_R2,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R2,WP_R3,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R3,WP_R4,nav_radius,100,100)"/>
<call fun="FlightLine(WP_R5,WP_R6,nav_radius,100,100)"/>
<deroute block="Standby"/>
</block>
</source>
}}

However, the previous block can also be implemented using the FlightLineBlock function. The FlightLineBlock function works the same as the FlightLine function except it automatically steps through the waypoints between the given waypoints. Make sure the waypoints are declared in order or else it won't work!

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block name="Map River">
<call fun="FlightLineBlock(WP_R1,WP_R6,nav_radius,100,100)"/>
<deroute block="Standby"/>
</block>
</source>
}}

<gallery>
Image:OSAMFlightLineExample.jpg |Multiple Flight Line Example
</gallery>

== misc ==

=== Border line ===

border_line is a nav-routine pretty similar to the nav-line-routine. You can use this nav-routine whenever you want to take care your plane stays on a defined site of a border.
For example you can use this routine to fly along a mountain and always turn away from the mountain ridge wall. Or use it fly along a border road without penetrating the other side of the border.

Use "extra" navigation subsystem with:
<source lang="xml">
<subsystem name="navigation" type="extra"/>
</source>

If you want to use waypoint 1 and 2 you can add border_line in your flight plan like this:
* Include header in "header" section at the beginning
#include "subsystems/navigation/border_line.h"
* Add function in a flight plan block:

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<block group="extra_pattern" name="border line">
<call fun="border_line_init()"/>
<call fun="border_line(WP_1, WP_2, -nav_radius)"/>
</block>
</source>
}}

<gallery caption="example">
Image:border_line.png|Screen shot of border_line
Image:border_line2.png|Screen shot of border_line2
Image:border_line3.png|Screen shot of border_line3
</gallery>

=== GLS ===

GLS or '''G'''lobal Navigation Satellite System (GNSS) '''L'''anding '''S'''ystem adds advanced landing functions to your flightplan

It add the following capabilities:

# Fly via defined glide path angle
# In flight changeable landing direction without loosing the glide path angle!
# Smooth intercept, independent of approach angle or wind
# Separation of '''a'''pproach '''f'''ix, '''s'''tart '''d'''ecent and '''t'''op '''o'''f '''d'''ecent
# With fixed target speed (in airspeed mode only)

====GLS related abbreviations====

* GLS = '''G'''lobal Navigation Satellite System (GNSS) '''L'''anding '''S'''ystem
* TOD = '''t'''op '''o'''f '''d'''ecent
* AF = '''A'''pproach '''Fix'''
* SD = '''S'''tart '''D'''ecend
* TD = '''T'''ouch '''D'''own point, The spot where the plane should touch the ground for landing

====Configure====

What to add to your airframe.

{{Box Code|conf/flight_plans/myflightplan.xml|
<source lang="xml">
<section name="GLS_APPROACH" prefix="APP_">
<define name="ANGLE" value="5" unit="deg"/>
<define name="INTERCEPT_RATE" value="0.624" unit="m/s/s"/>
<define name="DISTANCE_AF_SD" value="20" unit="m"/>
<define name="TARGET_SPEED" value="14" unit="m/s"/>
</section>
</source>
}}

ANGLE - angle from TOD to TD

DISTANCE_AF_SD - minimum distance (meter) between AF and SD to allow the plane to self stabilize before the intercept starts (e.g. for speed reduction)

You can set the landing direction by moving the approach fix (AF) in relation to the touch down point (TD).
If you try to set the AF close to the TD you will see how the top of decent (TOD) and start decent (SD) is calculated and if necessary the AF is moved backwards.
(please try in simulation)

TARGET_SPEED - desired airspeed from AF to TD

INTERCEPT_RATE -

e.g. no wind: TARGET_SPEED = 14m/s and ANGLE = 10 --> desired decent rate 2.5 m/s (speed * tan(ANGLE))

with an INTERCEPT_RATE of 0.624 m/s/s it will take 4s to intercept the final approach path (desired decent rate / intercept_rate)

the idea is that the INTERCEPT_RATE is unique to each plane and will not change with different approach angles

to find an appropriate value you can start with a lower (to match 8s for example) and increase it until the intercept will be made from above

in general: bigger plane - smaller value!

how to setup your flightplan.xml:

<source lang="xml">
<waypoints>
<waypoint height="150" name="AF" x="-260.6" y="-344.6"/>
<waypoint name="SD" x="-1600." y="-36."/>
<waypoint name="TOD" x="-1600." y="-36."/>
<waypoint height="0.0" name="TD" x="-27.2" y="-243.5"/>
<waypoint height="266.0" name="_BASELEG" x="-1652.1" y="-113.5"/>
</waypoints>

<block name="land">
<call fun="gls_init(WP_AF,WP_SD, WP_TOD, WP_TD)"/>
<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)-(nav_radius/fabs(nav_radius))*10),
10 > fabs(GetPosAlt() - WaypointAlt(WP__BASELEG)))" wp="_BASELEG"/>
</block>

<block name="final">
<exception cond="ground_alt + 10 > estimator_z" deroute="flare"/>
<call fun="gls(WP_AF,WP_SD, WP_TOD, WP_TD)"/>
</block>
</source>

those pictures match the old gls routine! anyway - the new one is not much different... (POS I = SD)
<gallery caption="theory">
Image:gls1.png|side view
Image:gls2.png|from above
Image:gls3.png|screen shot of flight test
</gallery>

== Multi-UAV ==
For TCAS (Traffic Collision Avoidance System) see the [[MultiUAV]] page.

[[Category:Software]] [[Category:Navigation]] [[Category:User_Documentation]]

= Create a navigation module =

Creating a navigation module is not to complex. Have said that, it is not very likely to need to create one module oneself. The already available functions are very flexible and powerful. Before you set of to create and additional navigation module, make sure you understand all current modules and their capabilities. After you investigated current modules and came to the conclusion, there is no way to solve you flightplan mission by creating a new module, go ahead and plz share your work with the community. The more people test the new module, the faster it will reach a stable state.

Talk:Telemetry

2016-03-15T17:25:48Z

Lethargi:

The add messages section seems to be out dated for version 5.8. The AIRSPEED messages are already implemented. I tried to get this working for a module I made following the instructions but it did not work. I think they need to be updated. Also the "find_free_msg_id.out" was replaced by *.ml script which I could not use. --[[User:Lethargi|Lethargi]]

Telemetry

2016-03-15T17:24:41Z

Lethargi: /* Add Messages */; changed the section introduction and included the information about making paparazzi again before the changes from messages.xml take effect.

== Messages ==

Telemetry messages (sent from the aircraft to the ground) are defined in the telemetry class of [https://github.com/paparazzi/paparazzi/blob/master/conf/messages.xml conf/messages.xml].
See also the generated documentation: http://docs.paparazziuav.org/latest/paparazzi_messages.html

== Sending periodic messages ==
The set of periodic messages sent over the downlink channel by an aircraft to the ground station is configurable
with the help of one XML file, located in the <tt>conf/telemetry</tt> directory. This file is referenced by <tt>conf/conf.xml</tt> and must follow the
<tt>telemetry.dtd</tt> syntax. The <tt>fixedwing_default.xml</tt> and <tt>rotorcraft_default.xml</tt> are provided as an example and should be suitable for most users.
{{Box Code|default.xml|
<source lang="xml"><!DOCTYPE telemetry SYSTEM "telemetry.dtd">
<telemetry>
<process name="Ap">
<mode name="default">
<message name="ATTITUDE" period="0.5"/>
<message name="PPRZ_MODE" period="5"/>
<message name="SOME_MODULE_MSG" period="2" module="module_name"/>
...
</mode>
<mode name="fast attitude">
<message name="ATTITUDE" period="0.1"/>
</mode>
</process>
<process name="Fbw">
<mode name="default">
<message name="COMMANDS" period="1"/>
...
</mode>
<mode name="debug">
<message name="PPM" period="0.5"/>
</mode>
</process>
</telemetry></source>
}}

If a [[Modules|module]] attribute is specified for a message, it will be include in the telemetry only if the corresponding module is loaded.

It is even possible to create your own telemetry XML definition. By the time you need that, it is highly likely you are already an advanced paparazzi user and know why you would and how you will.

===Add Messages===

This section provides instructions of an example case of how one would add a new message to Paparazzi and send the data to the ground station. The example is a little old and considers the addition of the AIRSPEED message, which is already present in newer versions of paparazzi. The user will have to implement her own message objects instead of the AIRSPEED message.

==== Step 1 ====

In conf/messages.xml add an airspeed message:
{{Box Code|conf/messages.xml|
<source lang="xml">
<message name="AIRSPEED" id="54">
<field name="adc_airspeed" type="uint16"/>
<field name="estimator_airspeed" type="float" unit="m/s"/>
<field name="airspeed_setpoint" type="float" unit="m/s"/>
<field name="airspeed_controlled" type="float" unit="m/s"/>
<field name="groundspeed_setpoint" type="float" unit="m/s"/>
</message>
</source>}}
Where id="54" has to be unique. To find an new ID to use there is a script file located at ${PAPARAZZI_HOME}/sw/tools/find_free_msg_id.out (yes it is really a script).

Type: ${PAPARAZZI_SRC}/sw/tools/find_msg_id.out

NOTE: Be sure your Paparazzi source and home environment variables are set correctly in your shell [[Installation#Launching_the_Software]])

Every field in the output is a variable from Paparazzi. The type must be the type of a variable in your code (ie. look in your code). Add your message along with the frequency to be sent over the messaging bus (AKA telemetry messages).

After making the modifications to the messages.xml file, make your paparazzi again (i.e. cd ${PAPARAZZI_HOME} && make) so that your changes to the messages.xml file are reflected in the paparazzi/var/include/messages.h file. This will create a DOWNLINK_SEND_AIRSPEED macro (in ${PAPARAZZI_HOME}/var/include/messages.h). If you do not make paparazzi, this macro will not be created.

==== Step 2 ====

Add a message to your telemetry file (for example conf/telemetry/default_fixedwing.xml). The message name in telemetry file usually match the message name in messages.xml file, but can be different or even group several messages.
{{Box Code|conf/telemetry/default.xml|
<source lang="xml">
<telemetry>
<process name="Ap">
<mode name="default">
<message name="ALIVE" period="5"/>
<message name="GPS" period="0.25"/>
<message name="AIRSPEED" period="1"/>
....
</source>
}}

The result is a generated file in ${PAPARAZZI_HOME}/var/aircrafts/<AC>/generated/periodic_telemetry.h which consist in a (static) scheduler to that calls specific functions.

==== Step 3 ====

Create a function in your C source file that will send your message(s) (using the generated DOWNLINK_SEND_* macros) and register it to the telemetry system so that it will be send automatically for you. You also need to include the header <tt>subsystems/datalink/telemetry.h</tt>:
{{Box Code|firmware/fixedwing/autopilot.c|

<source lang="c">
...
#include "subsystems/datalink/telemetry.h"

static void send_airspeed(struct transport_tx *trans, struct link_device *dev)
{
pprz_msg_send_AIRSPEED(trans, dev, AC_ID,
&airspeed, &v_ctl_auto_airspeed_setpoint,
&v_ctl_auto_airspeed_controlled, &v_ctl_auto_groundspeed_setpoint);
}

...
void autopilot_init(void) {
...
register_periodic_telemetry(DefaultPeriodic, PPRZ_MSG_ID_AIRSPEED, send_airspeed);
...
}
</source>
}}
where the second parameter in the register function is the id of the message (use the define <tt>PPRZ_MSG_ID_<MESSAGE_NAME></tt>).

<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
Prior to '''v5.0''':
<div class="mw-collapsible-content">Past Reference for Paparazzi v5.0 or older:
Create a PERIODIC_SEND_AIRSPEED with the following code in the firmware specific telemetry header file (In ap_downlink.h/fbw_downlink.h for fixedwing or telemetry.h for rotorcraft) :
{{Box Code|conf/telemetry/default.xml|
<source lang="c">
#ifdef USE_AIRSPEED
#define PERIODIC_SEND_AIRSPEED(_chan) DOWNLINK_SEND_AIRSPEED (_chan, _dev &adc_airspeed_val,&estimator_airspeed,&v_ctl_auto_airspeed_setpoint,&v_ctl_auto_airspeed_controlled,&v_ctl_auto_groundspeed_setpoint)
#else
#define PERIODIC_SEND_AIRSPEED(_chan) {}
#endif
</source>
</div></div>

===Configuring the Downlink Data Rate===

The limited throughput of our RF modems results in a need to carefully choose which data to send, as well as the frequency at which to send it. A sophisticated set of files and parameters have been developed in order to tailor the data downlink behavior automatically, manually, temporarily, or permanently according to any desired parameter. This allows the user to create an almost unlimited possibility of downlink configurations. For example:
* Tailor the data rate to work with very slow modems (9600 baud or slower)
* Reduce the data rate of some messages so that others can be increased:
*: Automatically send GPS data at a very high rate by sacrificing navigation data when not flying (to help GPS/RFI troubleshooting) then automatically reduce the GPS data rate and send normal navigation data when the launch is initiated.
*: Automatically switch to sending only position data upon landing to conserve power and increase the chance of the operator receiving a position packet when recovering a distant aircraft.
*: Manually send selected sensor data at very high speeds (60Hz) for real time tuning.
* Maintain independent telemetry configurations for aircraft with different modems, sensors, or mission profiles.

Any number of configuration files can be created in the <tt>conf/telemetry</tt> directory and selected from the <tt>conf/conf.xml</tt> file. The telemetry downlink is divided into two processes, '''Ap''' and '''Fbw''' each with a possible <tt>mode</tt> option. Any number of modes could be created, the default is the first in the sequence. A mode contains the list of messages to be sent as well as the period of each message in seconds. In this example, the '''ATTITUDE''' message will be sent by the '''Ap''' process at 2Hz in the default mode and at 10Hz in the '''fast attitude''' mode. The maximum allowed frequency is 60Hz (0.017s) and the maximum period is 1092s.

The mode can be chosen in the airframe file by setting the '''TELEMETRY_MODE_FBW''' constant:
<source lang="xml"><define name="TELEMETRY_MODE_FBW" value="1"/></source>
where the (default) first mode is numbered '''0'''.

This mode can also be changed dynamically with a datalink [[#Settings|setting]] or with a [[Flight_Plans#set|set]] stage in the flight plan.

Note that an (undocumented!) subset of the messages is required to be able to use ground station properly. So it is not advisable to completely remove messages for the '''Ap''' process listed in the default mode.

==Specific Messages==

===GPS_SOL===
Specification in telemetry file
<source lang="xml">
<message name="GPS_SOL" period="2.0"/>
</source>
Example from logfile(.data):
6.742 1 GPS_SOL 232 43 198 8

Meaning of tokens:
Timestamp, Aircraft-Number, GPS_SOL, Pacc, Sacc, PDOP, numSV

*Pacc = Position accuracy (units: CM)
*Sacc = Speed accuracy (units: CM/sec ?)
*PDOP = Position [http://en.wikipedia.org/wiki/Dilution_of_precision_%28GPS%29 Dilution_of_precision_(GPS)] , if this value is high the value of position will be less accurate
*numSV = number of Space Vehicles (Satellites) used in Nav Solution

===PPRZ_MODE===
Specification in telemetry file
<source lang="xml">
<message name="PPRZ_MODE" period="5."/>
</source>
Example from logfile(.data):
20.433 2 PPRZ_MODE 0 1 2 0 0 1

Meaning of tokens:
Timestamp, Aircraft-Number, PPRZ_MODE, ap_mode, ap_gaz, ap_horizontal, if_calib_mode, mcul_status
*ap_mode = (0 = MANUAL, 1 = AUTO1, 2 = AUTO2, 3 = HOME mode (Circle Home waypoint), 4 = NO_GPS (GPS not working), 5 = NB (?)
*ap_gaz = ?
*ap_horizontal = ?
*if_calib_mode = ?
*mcul_status = ?

== Audio-based downlink ==

The audio-based downlink has been removed from current hardware designs however using the old designs it is possible to implement. With the current low prices of a simple video transmitter, data over audio may come in as a welcomed addition. Feel free to experiment and revive this classical feature.

[[Category:Software]] [[Category:User_Documentation]] [[Category:Telemetry]]

Talk:Telemetry

2016-03-15T10:19:37Z

Lethargi:

Talk:Telemetry

2016-03-15T10:17:36Z

Lethargi: Created page with "The add messages section seems to be out dated for version 5.8. The AIRSPEED messages are already implemented. I tried to get this working for a module I made following the in..."