PaparazziUAV - User contributions [en]

Airframe Configuration

2008-10-23T00:16:07Z

Ben P: /* GPS */

The airframe configuration file is located in <tt>conf/airframes</tt> and contains
all the hardware and software settings for an aircraft. This is an [http://en.wikipedia.org/wiki/Xml XML] document containing some [http://en.wikipedia.org/wiki/Makefile Makefile] code at the bottom. All gains, trims, and behavior settings are defined with standard XML elements. The hardware definitions such as processor type, modem protocol, servo driver, etc. are contained in the makefile raw section.

== Selecting the Airframe File ==
Each airframe file must be assigned a name, unique ID, flight plan, etc. in [[Conf.xml|<tt>conf/conf.xml</tt>]] as follows:
<?xml version="1.0"?>
<conf>
<aircraft
name="Twin1"
ac_id="1"
airframe="airframes/twinstar1.xml"
radio="radios/mc3030.xml"
flight_plan="flight_plans/mav05_cw.xml"
telemetry="telemetry/default.xml"
gui_color="blue"
/>
<aircraft
name="Plaster"
ac_id="2"
airframe="airframes/plaster1.xml"
radio="radios/cockpitMM.xml"
telemetry="telemetry/default.xml"
flight_plan="flight_plans/dummy.xml"
/>
.
.
.
</conf>
Then, to compile and flash the airframe settings and associated flight plan to your autopilot, simply select the appropriate A/C and target in the [[Paparazzi_Center|Paparazzi Center]] or specify your airframe name in the flash command typed from the prompt:
make AIRCRAFT=<b>Twin1</b> ap.upload
More information can be found on the [[Conf.xml|conf.xml]] page

== XML Parameters ==
=== Commands ===

The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. In our example, we have only three:
<tt>
<commands>
<axis name="THROTTLE" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="PITCH" failsafe_value="0"/>
</commands></tt>
Each command is associated with a failsafe value which will be used if no controller is active (during initialization for example). The range of these values is [-9600:9600]. Note that these commands do not necessarily match the servo actuators. For example, the ROLL command is typically linked to two aileron actuators.

=== Servos ===

The above commands get translated to the <b><tt>servos</tt></b> here. In this example we use two ailevons (surfaces used for both pitch and roll as on a flying wing) and a motor. These are listed in the <b><tt>servos</tt></b> section:
<tt>
<servos>
<servo name="THROTTLE" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="AILEVON_LEFT" no="1" min="2000" neutral="1500" max="1000"/>
<servo name="AILEVON_RIGHT" no="2" min="1000" neutral="1500" max="2000"/>
</servos></tt>
where names are associated to the corresponding servo channel number on the autopilot and the neutral value, total range and direction are defined. Min/max/neutral values are expressed in milliseconds and the direction of travel can be reversed by exchanging min with max (as in <tt>"AILEVON_LEFT"</tt>, above). The ''standard'' travel for a hobby servo is 1000ms - 2000ms with a 1500ms neutral. Trim can be added by changing this neutral value, and absolute travel limits can be increased or reduced with the min/max values. The <tt>"THROTTLE"</tt> servo typically has the same value for the <b><tt>neutral</tt></b> and <b><tt>min</tt></b>. Note the following tips:
* Reverse the servo direction by exchanging min/max
* Trim should always be adjusted mechanically if possible to avoid asymetrical travel
* Any reduction of the total travel range should be done mechanically to maintain precision
* Many servos will respond well to values slightly outside the normal 1000-2000ms range but experiment carefully as the servo may not operate reliably outside this range and may even suffer permanent damage.

The <b><tt>servos</tt></b> are then linked to the commands in the <b><tt>command_laws</tt></b> section:
<tt>
<command_laws>
<let var="aileron" value="@ROLL * 0.3"/>
<let var="elevator" value="@PITCH * 0.7"/>
<set servo="THROTTLE" value="@THROTTLE"/>
<set servo="AILEVON_LEFT" value="$elevator + $aileron"/>
<set servo="AILEVON_RIGHT" value="$elevator - $aileron"/>
</command_laws></tt>
[[Image:airframe_sign_conventions.jpg|thumb|Sign conventions for flight dynamics]]
where the third line is the simplest: the throttle servo value equals throttle command value. The other lines define and control the pitch/roll mixing. Ailevon values are computed with a combination of two commands, '''ROLL''' and '''PITCH'''. This ''mixer'' is defined with two intermediate variables '''aileron''' and '''elevator''' introduced with the <b><tt>let</tt></b> element. The '''@''' symbol is used to reference a command value in the <b><tt>value</tt></b> attribute of the <b><tt>set</tt></b> and <b><tt>let</tt></b> elements. In the above example, the servos are limited to +/- 70% of their full travel for pitch and 30% for roll, only in combination can the servos reach 100% deflection. Note that these numbers ''should add up 100% or more, never less''. For example, you may want 100% travel available for pitch - this means if a roll is commanded along with maximum pitch only one servo will respond to the roll command as the other has already reached its mechanical limit. If you find after tuning that these numbers add to less than 100% consider reducing the surface travel mechanically.

Note that the signs used in the description follow the standard convention.

=== Manual ===
The <tt>rc_command</tt> sections links the channels of the RC transmitter (defined in the [[Radio_Control|Radio Control]] file) to the <tt>commands</tt> defined above:

<rc_commands>
<set command="THROTTLE" value="@THROTTLE"/>
<set command="ROLL" value="@ROLL"/>
<set command="PITCH" value="@PITCH"/>
</rc_commands>

This example looks trivial since the channel values have the same name than the commands.

=== Autopilot Only Commands ===
For certain missions it might be required to control servos (payload) from the autopilot (gcs) at all times (even during manual flight). These commands should not be in the <rc_commands> block but in the special <ap_only_commands> block. This allows for instance the pantilt operator to keep working when in manual flight, or safety logic to automatically close cameras below a certain altitude during manual landings.

<ap_only_commands>
<copy command="PAN"/>
<copy command="TILT"/>
<copy command="SHOOT"/>
</ap_only_commands>

=== Auto1 ===
The next section, named <b><tt>AUTO1</tt></b>, gives the maximum roll and pitch (in radians) allowed for the augmented stability mode.
<tt>
<section name="AUTO1" prefix="AUTO1_">
<define name="MAX_ROLL" value="RadOfDeg(35)"/>
<define name="MAX_PITCH" value="RadOfDeg(35)"/>
</section>
</tt>
<br>

=== ADC ===
In the "adc" section, you will find the conformity between arguments and their assigned pins on the autopilot board.
<section name="adc" prefix="ADC_CHANNEL_">
<define name="IR1" value="ADC_1"/>
<define name="IR2" value="ADC_2"/>
<define name="IR_TOP" value="ADC_0"/>
</section>
'''Important note''': To ''activate'' an ADC entry, a flag must be defined in the <tt>makefile</tt> section. For the previous example, we would have to write:

ap.CFLAGS += -DADC -DUSE_ADC_0 -DUSE_ADC_1 -DUSE_ADC_2
ap.srcs += $(SRC_ARCH)/adc_hw.c

==== ADC Generic ====

In addition, if you want to receive the value of some ADC channel, you can use the "ADC Generic" service. When activated, the aircraft sends 2 values corresponding to the selected ADC channels. They can be read from the "Messages" application.
ap.CFLAGS += -DUSE_ADC_GENERIC -DUSE_ADC_3 -DADC_CHANNEL_GENERIC1=ADC_3 -DUSE_ADC_4 -DADC_CHANNEL_GENERIC2=ADC_4
ap.srcs += adc_generic.c
In this example, the ADC channels 3 and 4 are read and sent by telemetry at 4Hz:
<message name="ADC_GENERIC" ID="18">
<field name="val1" type="uint16"/>
<field name="val2" type="uint16"/>
</message>
Only two channels can be defined. If only one is activated, 0 will send for the second value.

=== Infrared ===
The <b><tt>INFRARED</tt></b> section describes the configuration of the infrared sensors.

The first definitions are relative to the electronic neutral of the sensors (a sensor here is a pair of thermopiles). A perfect sensor should give 512 if it measures the same value on both sides.

<section name="INFRARED" prefix="IR_">
<define name="ADC_IR1_NEUTRAL" value="512"/>
<define name="ADC_IR2_NEUTRAL" value="512"/>
<define name="ADC_TOP_NEUTRAL" value="512"/>

These neutrals are tuned with the "cupboard test": Put the sensor in a close box (a cupboard) and read the values of the IR_SENSORS message (ir1, ir2 and vertical). Set the neutrals (they are subtracted from the measurement) to get null values. E.g. if you read 5 for the ir1 value with ADC_IR1_NEUTRAL equal to 512, change the latter to 517.

The next lines define the installation of the horizontal and vertical sensors. The vertical sensor must give a positive value when the temperature under the aircraft is higher than the temperature above. The two channels of the horizontal sensor must give positive values when it is warmer on the right side and the rear side. To adjust these signs, use the following declarations:

<define name="IR1_SIGN" value="-1"/>
<define name="IR2_SIGN" value="-1"/>
<define name="TOP_SIGN" value="-1"/>

Then, define how the horizontal sensor is connected to the airframe, orientation '''aligned''' or '''tilted'''. In the aligned case, ir'''1''' is along the lateral axis and ir'''2''' along the longitudian one. In the '''tilted''' case, the sensors are tilted by 45 degrees; ir'''1''' is along rear-left -- front-right, and ir'''2''' along rear-right -- front-left. The parameter "value" has no effect! If the airframe construction allows choose an aligned sensor orientation since this gives the best stabilization response results.

<define name="HORIZ_SENSOR_ALIGNED" value="1"/>
or
<define name="HORIZ_SENSOR_TILTED" value="1"/>

The three axis must give similar values for similar contrasts. The following factors can be used to scale these values. For example with an horizontal tilted sensor, the following ratios are usually needed:

<define name="LATERAL_CORRECTION" value="0.7"/>
<define name="LONGITUDINAL_CORRECTION" value="0.7"/>
<define name="VERTICAL_CORRECTION" value="1."/>
Default values are 1.

It may be hard to align the horizontal sensor with the aircraft. A tuning in flight will be needed to adjust the following neutrals. Adjust the roll neutral to fly straight. Adjust the pitch neutral to fly level with the desired throttle.
<define name="ROLL_NEUTRAL_DEFAULT" value="-2.5" unit="deg"/>
<define name="PITCH_NEUTRAL_DEFAULT" value="6" unit="deg"/>

Finally, an asymmetric (left/right, front/rear) correction can be added with a last set of factors.
<define name="CORRECTION_UP" value="1."/>
<define name="CORRECTION_DOWN" value="1."/>
<define name="CORRECTION_LEFT" value="1."/>
<define name="CORRECTION_RIGHT" value="1."/>
</section>
These corrections are set on the angles.

The old way to define the parameters is still possible, but must not be mixed with the new one describe above.

=== Gyro ===
Defines the type of gyro installed, each axis neutral, and any required temperature compensation. If the gyro has two axes, the pitch neutral is defined as well. Many gyros output their internal temperature and require a temperature-dependent linear correction be made to the neutral value. No correction is done for the temperature in this example.(<b><tt>ADC_TEMP_SLOPE=0</tt></b>).

<tt>
<section name="GYRO" prefix="GYRO_"
<define name="ADC_ROLL_COEFF" value="1"/>
<define name="ROLL_NEUTRAL" value="500"/>
<define name="ADC_TEMP_NEUTRAL" value="476"/>
<define name="ADC_TEMP_SLOPE" value="0"/>
</section>
</tt>

=== Bat ===
This section give characteristics for the monitoring of the main power battery. <b><tt>MILLIAMP_PER_PERCENT</tt></b> represents the consumption (in mA) for one percent of THROTTLE and for one time unit. It is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message.

The <b><tt>CATASTROPHIC_BAT_LEVEL</tt></b> (was previously <b><tt>LOW_BATTERY</tt></b>) value defines the voltage at which the autopilot will lock the throttle at 0% in autonomous mode (kill_throttle mode). This value is also used by the ground server to issue a '''CATASTROPHIC''' alarm message on the bus (this message will be displayed in the console of the GCS). <b><tt>CRITIC</tt></b> and <b><tt>LOW</tt></b> values will also used as threshold for '''CRITIC''' and '''WARNING''' alarms. They are optional and the respective defaults are 10.0 and 10.5V.

The <b><tt>MAX_BAT_LEVEL</tt></b> may be specified to improve the display of the battery gauge in the strip. This definition is optional with a default value of 12.5V.

<tt>
<section name="BAT">
<define name="MILLIAMP_PER_PERCENT" value="0.86"/>
<define name="VOLTAGE_ADC_A" value="0.0177531"/>
<define name="VOLTAGE_ADC_B" value="0.173626"/>
<define name="VoltageOfAdc(adc)" value ="(VOLTAGE_ADC_A * adc + VOLTAGE_ADC_B)"/>
<define name="CATASTROPHIC_BAT_LEVEL" value="6.0" unit="V"/>
<define name="CRITIC_BAT_LEVEL" value="6.5" unit="V"/>
<define name="LOW_BAT_LEVEL" value="7.0" unit="V"/>
<define name="MAX_BAT_LEVEL" value="8.4" unit="V"/>
</section>
</tt>

=== Horizontal Control ===
<tt>
<section name="HORIZONTAL CONTROL" prefix="H_CTL_">
<define name="COURSE_PGAIN" value="-0.4"/>
<define name="ROLL_MAX_SETPOINT" value="0.35" unit="radians"/>
<define name="ROLL_ATTITUDE_GAIN" value="-7500."/>
<define name="ROLL_RATE_GAIN" value="-1500"/>
<define name="PITCH_PGAIN" value="-8000."/>
<define name="ELEVATOR_OF_ROLL" value="1250"/>
</section>
</tt>

The outer loop acts on the route. It will produce a roll command from a course setpoint and a course measurement. The COURSE_PGAIN parameter is the factor multiplied by the course error (in radian) to get a roll setpoint (in radian). So if the plane is expected to go north (course=0) and is actually flying to 57 degrees (course=1 radian, i.e. ENE), with a gain of '''-0.4''', a roll of -0.4 (23 degrees) will be set for the lower control loop.

The ROLL_ATTITUDE_GAIN is used to compute a ROLL command from the roll error (setpoint minus measurement). If a gyro in installed, the ROLL_RATE_GAIN to keep a null roll rate. So these two gains provide a P-D controller.

===Vertical Control===

<section name="VERTICAL CONTROL" prefix="V_CTL_">

<define name="ALTITUDE_PGAIN" value="-0.1" unit="(m/s)/m"/>

<define name="ALTITUDE_MAX_CLIMB" value="3." unit="m/s"/>
These lines are associated with vertical control loops contained in ./sw/airborne/fw_v_ctl.c. These are outer loop parameters that calculate a desired climb rate based on altitude error. Here, if the altitude error is 10m, the climb setpoint will be set to 1m/s. ALTITUDE_MAX_CLIMB is a bounded value (in m/s) so that the outer loop does not calculate too large of a climb rate
<define name="AUTO_THROTTLE_NOMINAL_CRUISE_THROTTLE" value="0.65" unit="%"/>
<define name="AUTO_THROTTLE_MIN_CRUISE_THROTTLE" value=".4" unit="%"/>
<define name="AUTO_THROTTLE_MAX_CRUISE_THROTTLE" value="1" unit="%"/>
<define name="AUTO_THROTTLE_LOITER_TRIM" value="1000" unit="pprz_t"/>
<define name="AUTO_THROTTLE_DASH_TRIM" value="-2500" unit="pprz_t"/>
<define name="AUTO_THROTTLE_CLIMB_THROTTLE_INCREMENT" value="0.15" unit="%/(m/s)"/>
<define name="AUTO_THROTTLE_PGAIN" value="-0.008" unit="%/(m/s)"/>
<define name="AUTO_THROTTLE_IGAIN" value="0.25"/>
<define name="AUTO_THROTTLE_PITCH_OF_VZ_PGAIN" value="0.35" unit="rad/(m/s)"/>

These lines are associated with vertical rate control loops contained in ./sw/airborne/fw_v_ctl.c and are used by default in most cases. The default vertical control law is for the vertical rate to be managed by a combination of throttle and pitch.

<define name="AUTO_PITCH_PGAIN" value="-0.1"/>
<define name="AUTO_PITCH_IGAIN" value="0.025"/>
<define name="AUTO_PITCH_MAX_PITCH" value="0.5"/>
<define name="AUTO_PITCH_MIN_PITCH" value="-0.5"/>

These lines are associated with vertical control loops contained in ./sw/airborne/fw_v_ctl.c but are not used in default. The non-default vertical control law is for the vertical rate to be managed by the pitch.

<define name="THROTTLE_SLEW_LIMITER" value="2" unit="s"/>
THROTTLE_SLEW_LIMITER is the required time is seconds to change throttle from 0% to 100%.

=== Misc ===
<tt>
<section name="MISC">
<define name="NOMINAL_AIRSPEED" value ="12." unit="m/s">
<define name="CARROT" value="5." unit="s"/>
<define name="KILL_MODE_DISTANCE" value="(1.5*MAX_DIST_FROM_HOME)"/>
<define name="CONTROL_RATE" value"60" unit="Hz"/>
</section>
</tt>

* The "NOMINAL_AIRSPEED" is mainly used in the simulator.
* "CARROT" gives the distance (in seconds, so ground speed is taken into account) between the carrot and the aircraft.
* "KILL_MODE_DISTANCE" is the threshold distance to switch the autopilot into KILL mode (defined descent with no throttle)
* "CONTROL_RATE" is the rate of the low level control loops in Hertz (60 or 20).

== Hardware definitions - Makefile ==

The airframe file must include the description of the controller board and it's low-level settings. This is done in one <b><tt>makefile</tt></b> section starting with the autopilot model and flashing mode:
{{Box Code|conf/airframes/myplane.xml|
<makefile>
include $(PAPARAZZI_SRC)/conf/autopilot/tiny.makefile
<nowiki>FLASH_MODE=IAP</nowiki>
.
.
.
</makefile>
}}
Below this are the definintions and configuration of the peripherals and interfaces.

=== R/C ===

{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DRADIO_CONTROL -DRADIO_CONTROL_TYPE=RC_FUTABA</nowiki>
<nowiki>ap.EXTRA_SRCS += radio_control.c $(SRC_ARCH)/ppm_hw.c</nowiki>
<nowiki>ap.CFLAGS += -DACTUATORS=\"servos_direct_hw.h\"</nowiki>
<nowiki>ap.EXTRA_SRCS += $(SRC_ARCH)/servos_direct_hw.c</nowiki>
}}

You can set RADIO_CONTROL_TYPE to RC_FUTABA, for falling edge PPM, or RC_JR for rising edge PPM. "RC_FUTABA" is for The Futaba or compatible brands, and "RC_JR" for JR (a.k.a Graupner outside of the USA) or compatible brands.

For the classix, you must specify which pins to use for PWM by adding "-DPWM_SERVO_0, etc." to the line fbw.CFLAGS. This activate the PWM channel.

<tt>wiring on classix PWM connector
connector LPC shared port
PWM1 PWM5 AD1_6 CAP1_3 P0.21
PWM2 PWM3 RXD0 EINT0 P0.1
PWM3 PWM1 TXD0 P0.0
PWM4 PWM6 RXD1 EINT3 P0.9
PWM5 PWM4 TXD1 AD1_1 P0.8
PWM6 PWM2 SSEL0 EINT2 P0.7</tt>

PWM1 and PWM6 should be safe. PWM4 and PWM5 should be OK if you're not using UART1 on the FBW processor - same for PWM2 and PWM3 if you're not using UART0 (disable FBW telemetry for that ).

=== Modem ===
The modem protocol and baud rate must be set in both the airframe file and ground station. Any standard baud rate can be used, with 9600 being adequate and 57600 recommended for most users to allow high speed telemetry for more detailed flight data analysis. The actual data rate is determined by the number of messages being sent and the period of each message as defined in <tt>conf/telemetry/default.xml</tt>. Those wishing to experiment with "alternative" modems can reduce the number and period of each telemetry message to fit within most any bandwidth constraint.

Paparazzi supports the following modem protocols:
* Standard transparent serial (pprz) - this is compatible with all modems and can be used to connect the autopilot directly to a PC for testing without a modem.
* Maxstream API protocol (xbee) - compatible with all Maxstream modems including the 9XTend and Zigbee. This protocol enables hardware addressing, allowing multiple aircraft to be managed from a single ground modem.
* Coronis Wavecard - necessary for operation with the unusual Coronis Wavecard modem.
Select the baud/protocol in the airframe file by commenting/uncommenting the appropriate section as follows:
==== Configuring The Serial Protocol ====
New users are advised to start with the standard serial protocol before attempting to setup an addressed API link. There are no real reasons for the novice user to use the xbee protocol over the standard PPRZTransport. Even if you are using a Maxstream modem you should still start out with the standard. Lastly it should be pointed out that using a single UAV there is no disadvantage and that the [http://www.engr.usu.edu/wiki/index.php/OSAM OSAM] Paparazzi Team at UAS 2008 took second place using the STANDARD protocol. The serial protocol works with virtually any modem as well as direct cable connections. The baud rates of the airborne modem, autopilot, ground modem, and PC must be configured correctly. The PC and autopilot serial ports do not need to be set to the same baud rate, i.e. when running multiple aircraft from a single ground modem, the ground modem may require a higher baud rate than any of the airborne modems in order to stream the data from multiple simultaneous sources.

{{Box Code|conf/airframes/myplane.xml|
<nowiki>
<section name="DATALINK" prefix="DATALINK_">
<define name="DEVICE_TYPE" value="PPRZ"/>
<define name="DEVICE_ADDRESS" value="...."/>
</section>
</nowiki>
}}
The above example tells the autopilot to send and recieve data in standard serial form.

{{Box Code|conf/airframes/myplane.xml - makefile section at the bottom|
# Serial modem
<nowiki>ap.CFLAGS += -DDOWNLINK -DUSE_UART0 -DDOWNLINK_TRANSPORT=PprzTransport -DDOWNLINK_FBW_DEVICE=Uart0 -DDOWNLINK_AP_DEVICE=Uart0 -DPPRZ_UART=Uart0 -DDATALINK=PPRZ -DUART0_BAUD=B57600</nowiki>
<nowiki>ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c pprz_transport.c</nowiki>
}}
The above example configures the autopilot serial port (Uart0) to 57,600 baud and calls the serial transport protocol (pprz_transport.c). Use the "#" symbol to comment lines in this section of the airframe file.
<br>
Note:
* The autopilot and modem serial port baud rates must match at all times and also must match the ground modem rate, check your modem documentation to find the default baud rate and configure a different rate as needed.

<br style="clear:both>

Ensure that the ground station is using the same protocol and an equal or higher baud rate:
{{Box Code|conf/control_panel.xml|
<nowiki>
<session name="USB">
<program name="link">
<arg flag="-d" constant="/dev/paparazzi/ttyUSB0"/>

<arg flag="-uplink" constant=""/>
<arg flag="-s" constant="57600"/>
</program>
...
</session>
</nowiki>
}}
Use this constant /dev/paparazzi/ttyUSB0 when using either the ftdi cable or a Maxstream USB ground modem.. Otherwise use /dev/ttyUSB0 (the ttyUSB0 being the device that you are using. Note: it might not always be ttyUSB0). This paparazzi directory in the dev folder is created when setting the udev rules. [http://paparazzi.enac.fr/wiki/index.php/Installation#Setting_access_rights_for_USB_download Setting Udev rules]

==== Configuring The Maxstream API Protocol ====
The optional API protocol enables hardware addressing so that multiple aircraft can be managed from a single ground modem, or multiple aircraft and multiple ground stations can work simultaneously without interference from one another. API mode is enabled by sending an escape sequence (+++) followed by AT commands, this can be done automatically at each boot or can be permanently configured with the "ATWR" command for greater reliability.

{{Box Code|conf/airframes/myplane.xml|
<nowiki>
<section name="MISC">
...
<define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\ATBD6\rATWR\r\""/>
...
</section></nowiki>
}}
The above example will program the Maxstream to API mode, 100mW power (ATPL2), 57600 baud (ATBD6), and permanently store the changes (ATWR). After flashing allow 30 seconds for the modem to store the changes, then disable the init string by adding the line <tt><define name="NO_XBEE_API_INIT" value="TRUE"/></tt> (the parameter "value" has no effect), update the baud rate as needed, and re-flash the autopilot. The modem and autopilot serial port baud rates must match eachother at all times.
<br>
Notes:
* Maxtream modems are factory configured for 9600 baud, in order to change baud rates, first configure the autopilot serial port to match the modem (DUART0_BAUD=B9600), boot the system so that the baud rate change command is sent to the modem (ATBD6) and permanently saved (ATWR), allow 30 seconds for the modem configuration to complete, then reprogram the autopilot with the new baud rate (DUART0_BAUD=B57600) and disabled modem configuration string <tt><define name="NO_XBEE_API_INIT" value="TRUE"/> </tt>.
* The ac_id defined in <tt>conf/conf.xml</tt> is permanently programmed into the modem so this procedure would need to be re-run if the modem is moved to another plane.
* For temporary boot-time API configuration remove any baud rate changes, remove <tt>ATWR\r</tt> from the end of the string.
* Upgrade your Maxstream firmware to the latest version before attempting API mode operation.

<br style="clear:both>

{{Box Code|confAgain/airframes/myplane.xml - makefile section at the bottom|
<nowiki># Maxstream API protocol</nowiki>
<nowiki>ap.CFLAGS += -DDOWNLINK -DUSE_UART0 -DDOWNLINK_TRANSPORT=XBeeTransport -DDOWNLINK_FBW_DEVICE=Uart0 -DDOWNLINK_AP_DEVICE=Uart0 -DXBEE_UART=Uart0 -DDATALINK=XBEE -DUART0_BAUD=B57600</nowiki>
<nowiki>ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c xbee.c</nowiki>
}}
The above example configures the autopilot serial port (Uart0) to 57,600 baud and calls the Maxstream transport protocol (xbee.c). Use the "#" symbol to comment lines in this section of the airframe file.
<br style="clear:both>

Ensure that the ground station is using the same protocol and an equal or higher baud rate:
{{Box Code|conf/control_panel.xml|
<nowiki>
<session name="USB">
<program name="link">
<arg flag="-d" constant="/dev/paparazzi/ttyUSB0"/>
<arg flag="-transport" constant="xbee"/>
<arg flag="-uplink" constant=""/>
<arg flag="-s" constant="57600"/>
</program>
...
</session>
</nowiki>
}}
Use this constant /dev/paparazzi/ttyUSB0 when using either the ftdi cable or a Maxstream USB ground modem.. Otherwise use /dev/ttyUSB0 (the ttyUSB0 being the device that you are using. Note: it might not always be ttyUSB0). This paparazzi directory in the dev folder is created when setting the udev rules. [http://paparazzi.enac.fr/wiki/index.php/Installation#Setting_access_rights_for_USB_download Setting Udev rules]
=====Alternate Method=====
This is the way it is done in funjet1.xml and has been tested to work by Danstah

{{Box Code|conf/airframes/funjet1.xml|
<nowiki>
<section name="MISC">
...
<define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\""/>

...
</section></nowiki>
}}
Also use this
{{Box Code|conf/airframes/funjet1.xml|
<nowiki>

<section name="DATALINK" prefix="DATALINK_">
<define name="DEVICE_TYPE" value="XBEE"/>
<define name="DEVICE_ADDRESS" value="...."/>
</section>
</nowiki>
}}
And Finally use this in the makefile section
{{Box Code|conf/airframes/funjet1.xml|
<nowiki>
ap.CFLAGS += -DDOWNLINK -DUSE_UART1 -DDOWNLINK_TRANSPORT=XBeeTransport -DXBEE_UART=Uart1 -DDATALINK=XBEE -DUART1_BAUD=B9600
ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c xbee.c
</nowiki>
}}
By reading all the information above you should be able to infer what the above does.

Now keep in mind that the ground modem baud rate and airplanes modem baud rates do not have to match. The only things that need to match are the the modem on the planes baud rate and the rate defined in the airframe file. For example this planes modem is set to 9600 and this could be used with the ground modem configured above using 57600...
Also for multiple UAV's a good way to configure them is to use 9600 for the ap and use a ground modem configured to 57600 and its not a bad idea to use minimal telemetry.

=== GPS ===
The serial port settings must match that of the GPS and are configured here along with the necessary files to interpret the u-blox UBX binary protocol:

{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DGPS -DUBX -DUSE_UART1 -DGPS_LINK=Uart1 -DUART1_BAUD=B38400</nowiki>
<nowiki>ap.srcs += gps_ubx.c gps.c</nowiki>
}}
'''Note:'''
* u-blox GPS modules are factory configured for 9600 baud, 38,400 baud is recommended along with the other required changes. The GPS can be accessed directly thru the [[Compiling#USB_flashing|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center Configured with|u-center]]

If using the u-blox LEA-5H, add the flag -DGPS_USE_LATLONG in the makefile section of the airframe xml file in the gps section. This flag must be inserted above "ap.srcs += gps_ubx.c gps.c" for proper operation.

{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DGPS -DUBX -DUSE_UART1 -DGPS_LINK=Uart1 -DUART1_BAUD=B38400 -DGPS_USE_LATLONG
ap.srcs += gps_ubx.c gps.c</nowiki>
}}

=== Sensors ===

=== Control loops ===

The control loops can be divided in two largely independent groups : the vertical ones and the horizontal ones (files sw/airborne/fw_h_ctl.c and sw/airborne/fw_v_ctl.c ). Those loops can be commanded at different levels by either the R/C transmitter or the autonomous navigation routine.

First the horizontal loop:
{{Box Code|conf/airframes/funjet1.xml|
<nowiki>ap.CFLAGS += -DNAV -DAGR_CLIMB -DLOITER_TRIM
ap.srcs += nav.c fw_h_ctl.c fw_v_ctl.c
</nowiki>
}}

== Radio Control ==
The Paparazzi autpilot interfaces directly with the PWM signal from any standard hobby R/C receiver. Signal decoding configuration settings for this are stored in the [[Radio_Control|Radio Control]] file.

Airframe Configuration

2008-09-26T23:11:51Z

Ben P: /* GPS */

The airframe configuration file is located in <tt>conf/airframes</tt> and contains
all the hardware and software settings for an aircraft. This is an [http://en.wikipedia.org/wiki/Xml XML] document containing some [http://en.wikipedia.org/wiki/Makefile Makefile] code at the bottom. All gains, trims, and behavior settings are defined with standard XML elements. The hardware definitions such as processor type, modem protocol, servo driver, etc. are contained in the makefile raw section.

== Selecting the Airframe File ==
Each airframe file must be assigned a name, unique ID, flight plan, etc. in [[Conf.xml|<tt>conf/conf.xml</tt>]] as follows:
<?xml version="1.0"?>
<conf>
<aircraft
name="Twin1"
ac_id="1"
airframe="airframes/twinstar1.xml"
radio="radios/mc3030.xml"
flight_plan="flight_plans/mav05_cw.xml"
telemetry="telemetry/default.xml"
gui_color="blue"
/>
<aircraft
name="Plaster"
ac_id="2"
airframe="airframes/plaster1.xml"
radio="radios/cockpitMM.xml"
telemetry="telemetry/default.xml"
flight_plan="flight_plans/dummy.xml"
/>
.
.
.
</conf>
Then, to compile and flash the airframe settings and associated flight plan to your autopilot, simply select the appropriate A/C and target in the [[Paparazzi_Center|Paparazzi Center]] or specify your airframe name in the flash command typed from the prompt:
make AIRCRAFT=<b>Twin1</b> ap.upload
More information can be found on the [[Conf.xml|conf.xml]] page

== XML Parameters ==
=== Commands ===

The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. In our example, we have only three:
<tt>
<commands>
<axis name="THROTTLE" failsafe_value="0"/>
<axis name="ROLL" failsafe_value="0"/>
<axis name="PITCH" failsafe_value="0"/>
</commands></tt>
Each command is associated with a failsafe value which will be used if no controller is active (during initialization for example). The range of these values is [-9600:9600]. Note that these commands do not necessarily match the servo actuators. For example, the ROLL command is typically linked to two aileron actuators.

=== Servos ===

The above commands get translated to the <b><tt>servos</tt></b> here. In this example we use two ailevons (surfaces used for both pitch and roll as on a flying wing) and a motor. These are listed in the <b><tt>servos</tt></b> section:
<tt>
<servos>
<servo name="THROTTLE" no="0" min="1000" neutral="1000" max="2000"/>
<servo name="AILEVON_LEFT" no="1" min="2000" neutral="1500" max="1000"/>
<servo name="AILEVON_RIGHT" no="2" min="1000" neutral="1500" max="2000"/>
</servos></tt>
where names are associated to the corresponding servo channel number on the autopilot and the neutral value, total range and direction are defined. Min/max/neutral values are expressed in milliseconds and the direction of travel can be reversed by exchanging min with max (as in <tt>"AILEVON_LEFT"</tt>, above). The ''standard'' travel for a hobby servo is 1000ms - 2000ms with a 1500ms neutral. Trim can be added by changing this neutral value, and absolute travel limits can be increased or reduced with the min/max values. The <tt>"THROTTLE"</tt> servo typically has the same value for the <b><tt>neutral</tt></b> and <b><tt>min</tt></b>. Note the following tips:
* Reverse the servo direction by exchanging min/max
* Trim should always be adjusted mechanically if possible to avoid asymetrical travel
* Any reduction of the total travel range should be done mechanically to maintain precision
* Many servos will respond well to values slightly outside the normal 1000-2000ms range but experiment carefully as the servo may not operate reliably outside this range and may even suffer permanent damage.

The <b><tt>servos</tt></b> are then linked to the commands in the <b><tt>command_laws</tt></b> section:
<tt>
<command_laws>
<let var="aileron" value="@ROLL * 0.3"/>
<let var="elevator" value="@PITCH * 0.7"/>
<set servo="THROTTLE" value="@THROTTLE"/>
<set servo="AILEVON_LEFT" value="$elevator + $aileron"/>
<set servo="AILEVON_RIGHT" value="$elevator - $aileron"/>
</command_laws></tt>
[[Image:airframe_sign_conventions.jpg|thumb|Sign conventions for flight dynamics]]
where the third line is the simplest: the throttle servo value equals throttle command value. The other lines define and control the pitch/roll mixing. Ailevon values are computed with a combination of two commands, '''ROLL''' and '''PITCH'''. This ''mixer'' is defined with two intermediate variables '''aileron''' and '''elevator''' introduced with the <b><tt>let</tt></b> element. The '''@''' symbol is used to reference a command value in the <b><tt>value</tt></b> attribute of the <b><tt>set</tt></b> and <b><tt>let</tt></b> elements. In the above example, the servos are limited to +/- 70% of their full travel for pitch and 30% for roll, only in combination can the servos reach 100% deflection. Note that these numbers ''should add up 100% or more, never less''. For example, you may want 100% travel available for pitch - this means if a roll is commanded along with maximum pitch only one servo will respond to the roll command as the other has already reached its mechanical limit. If you find after tuning that these numbers add to less than 100% consider reducing the surface travel mechanically.

Note that the signs used in the description follow the standard convention.

=== Manual ===
The <tt>rc_command</tt> sections links the channels of the RC transmitter (defined in the [[Radio_Control|Radio Control]] file) to the <tt>commands</tt> defined above:

<rc_commands>
<set command="THROTTLE" value="@THROTTLE"/>
<set command="ROLL" value="@ROLL"/>
<set command="PITCH" value="@PITCH"/>
</rc_commands>

This example looks trivial since the channel values have the same name than the commands.

=== Auto1 ===
The next section, named <b><tt>AUTO1</tt></b>, gives the maximum roll and pitch (in radians) allowed for the augmented stability mode.
<tt>
<section name="AUTO1" prefix="AUTO1_">
<define name="MAX_ROLL" value="RadOfDeg(35)"/>
<define name="MAX_PITCH" value="RadOfDeg(35)"/>
</section>
</tt>
<br>

=== ADC ===
In the "adc" section, you will find the correspondance between arguments and their assigned pins on the autopilot board.
<section name="adc" prefix="ADC_CHANNEL_">
<define name="IR1" value="ADC_1"/>
<define name="IR2" value="ADC_2"/>
<define name="IR_TOP" value="ADC_0"/>
</section>
'''Important note''': To ''activate'' an ADC entry, a flag must be defined in the <tt>makefile</tt> section. For the previous example, we would have to write:

ap.CFLAGS += -DADC -DUSE_ADC_0 -DUSE_ADC_1 -DUSE_ADC_2

=== Infrared ===
The <b><tt>INFRARED</tt></b> section describes the configuration of the infrared sensors.

The first definitions are relative to the electronic neutral of the sensors (a sensor here is a pair of thermopiles). A perfect sensor should give 512 if it measures the same value on both sides.

<section name="INFRARED" prefix="IR_">
<define name="ADC_IR1_NEUTRAL" value="512"/>
<define name="ADC_IR2_NEUTRAL" value="512"/>
<define name="ADC_TOP_NEUTRAL" value="512"/>

These neutrals are tuned with the "cupboard test": Put the sensor in a close box (a cupboard) and read the values of the IR_SENSORS message (ir1, ir2 and vertical). Set the neutrals (they are subtracted from the measurement) to get null values. E.g. if you read 5 for the ir1 value with ADC_IR1_NEUTRAL equal to 512, change the latter to 517.

The next lines define the installation of the horizontal and vertical sensors. The vertical sensor must give a positive value when the temperature under the aircraft is higher than the temperature above. The two channels of the horizontal sensor must give positive values when it is warmer on the right side and the rear side. To adjust these signs, use the following declarations:

<define name="IR2_SIGN" value="-1"/>
<define name="TOP_SIGN" value="-1"/>

Then, define how the horizontal sensor is connected to the airframe, orientation '''aligned''' or '''tilted'''. In the aligned case, ir'''1''' is along the lateral axis and ir'''2''' along the longitudian one. In the '''tilted''' case, the sensors are tilted by 45 degrees; ir'''1''' is along rear-left -- front-right, and ir'''2''' along rear-right -- front-left. A value of "0" indicates x-y sensor is aligned with the fueslage, a value of "1" indicates a 45 deg rotation. If the airframe construction allows choose an aligned sensor orientation since this gives the best stabilization response results.

<define name="HORIZ_SENSOR_TILTED" value="0"/>

The three axis must give similar values for similar contrasts. The following factors can be used to scale these values. For example with an horizontal tilted sensor, the following ratios are usually needed:

<define name="LATERAL_CORRECTION" value="0.7"/>
<define name="LONGITUDINAL_CORRECTION" value="0.7"/>
<define name="VERTICAL_CORRECTION" value="1."/>
Default values are 1.

It may be hard to align the horizontal sensor with the aircraft. A tuning in flight will be needed to adjust the following neutrals. Adjust the roll neutral to fly straight. Adjust the pitch neutral to fly level with the desired throttle.
<define name="ROLL_NEUTRAL_DEFAULT" value="-2.5" unit="deg"/>
<define name="PITCH_NEUTRAL_DEFAULT" value="6" unit="deg"/>

Finally, an asymmetric (left/right, front/rear) correction can be added with a last set of factors.
<define name="CORRECTION_UP" value="1."/>
<define name="CORRECTION_DOWN" value="1."/>
<define name="CORRECTION_LEFT" value="1."/>
<define name="CORRECTION_RIGHT" value="1."/>
</section>
These corrections are set on the angles.

=== Gyro ===
Defines the type of gyro installed, each axis neutral, and any required temperature compensation. If the gyro has two axes, the pitch neutral is defined as well. Many gyros output their internal temperature and require a temperature-dependent linear correction be made to the neutral value. No correction is done for the temperature in this example.(<b><tt>ADC_TEMP_SLOPE=0</tt></b>).

<tt>
<section name="GYRO" prefix="GYRO_"
<define name="ADC_ROLL_COEFF" value="1"/>
<define name="ROLL_NEUTRAL" value="500"/>
<define name="ADC_TEMP_NEUTRAL" value="476"/>
<define name="ADC_TEMP_SLOPE" value="0"/>
</section>
</tt>

=== Bat ===
This section give characteristics for the monitoring of the main power battery. <b><tt>MILLIAMP_PER_PERCENT</tt></b> represents the consumption (in mA) for one percent of THROTTLE and for one time unit. It is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message.

The <b><tt>CATASTROPHIC_BAT_LEVEL</tt></b> (was previously <b><tt>LOW_BATTERY</tt></b>) value defines the voltage at which the autopilot will lock the throttle at 0% in autonomous mode (kill_throttle mode). This value is also used by the ground server to issue a '''CATASTROPHIC''' alarm message on the bus (this message will be displayed in the console of the GCS). <b><tt>CRITIC</tt></b> and <b><tt>LOW</tt></b> values will also used as threshold for '''CRITIC''' and '''WARNING''' alarms. They are optional and the respective defaults are 10.0 and 10.5V.

The <b><tt>MAX_BAT_LEVEL</tt></b> may be specified to improve the display of the battery gauge in the strip. This definition is optional with a default value of 12.5V.

<tt>
<section name="BAT">
<define name="MILLIAMP_PER_PERCENT" value="0.86"/>
<define name="VOLTAGE_ADC_A" value="0.0177531"/>
<define name="VOLTAGE_ADC_B" value="0.173626"/>
<define name="VoltageOfAdc(adc)" value ="(VOLTAGE_ADC_A * adc + VOLTAGE_ADC_B)"/>
<define name="CATASTROPHIC_BAT_LEVEL" value="6.0" unit="V"/>
<define name="CRITIC_BAT_LEVEL" value="6.5" unit="V"/>
<define name="LOW_BAT_LEVEL" value="7.0" unit="V"/>
<define name="MAX_BAT_LEVEL" value="8.4" unit="V"/>
</section>
</tt>

=== Horizontal Control ===
<tt>
<section name="HORIZONTAL CONTROL" prefix="H_CTL_">
<define name="COURSE_PGAIN" value="-0.4"/>
<define name="ROLL_MAX_SETPOINT" value="0.35" unit="radians"/>
<define name="ROLL_ATTITUDE_GAIN" value="-7500."/>
<define name="ROLL_RATE_GAIN" value="-1500"/>
<define name="PITCH_PGAIN" value="-8000."/>
<define name="ELEVATOR_OF_ROLL" value="1250"/>
</section>
</tt>

The outer loop acts on the route. It will produce a roll command from a course setpoint and a course measurement. The COURSE_PGAIN parameter is the factor multiplied by the course error (in radian) to get a roll setpoint (in radian). So if the plane is expected to go north (course=0) and is actually flying to 57 degrees (course=1 radian, i.e. ENE), with a gain of '''-0.4''', a roll of -0.4 (23 degrees) will be set for the lower control loop.

The ROLL_ATTITUDE_GAIN is used to compute a ROLL command from the roll error (setpoint minus measurement). If a gyro in installed, the ROLL_RATE_GAIN to keep a null roll rate. So these two gains provide a P-D controller.

===Vertical Control===

<section name="VERTICAL CONTROL" prefix="V_CTL_">

<define name="ALTITUDE_PGAIN" value="-0.1" unit="(m/s)/m"/>

<define name="ALTITUDE_MAX_CLIMB" value="3." unit="m/s"/>
These lines are associated with vertical control loops contained in ./sw/airborne/fw_v_ctl.c. These are outer loop parameters that calculate a desired climb rate based on altitude error. Here, if the altitude error is 10m, the climb setpoint will be set to 1m/s. ALTITUDE_MAX_CLIMB is a bounded value (in m/s) so that the outer loop does not calculate too large of a climb rate
<define name="AUTO_THROTTLE_NOMINAL_CRUISE_THROTTLE" value="0.65" unit="%"/>
<define name="AUTO_THROTTLE_MIN_CRUISE_THROTTLE" value=".4" unit="%"/>
<define name="AUTO_THROTTLE_MAX_CRUISE_THROTTLE" value="1" unit="%"/>
<define name="AUTO_THROTTLE_LOITER_TRIM" value="1000" unit="pprz_t"/>
<define name="AUTO_THROTTLE_DASH_TRIM" value="-2500" unit="pprz_t"/>
<define name="AUTO_THROTTLE_CLIMB_THROTTLE_INCREMENT" value="0.15" unit="%/(m/s)"/>
<define name="AUTO_THROTTLE_PGAIN" value="-0.008" unit="%/(m/s)"/>
<define name="AUTO_THROTTLE_IGAIN" value="0.25"/>
<define name="AUTO_THROTTLE_PITCH_OF_VZ_PGAIN" value="0.35" unit="rad/(m/s)"/>

These lines are associated with vertical rate control loops contained in ./sw/airborne/fw_v_ctl.c and are used by default in most cases. The default vertical control law is for the vertical rate to be managed by a combination of throttle and pitch.

<define name="AUTO_PITCH_PGAIN" value="-0.1"/>
<define name="AUTO_PITCH_IGAIN" value="0.025"/>
<define name="AUTO_PITCH_MAX_PITCH" value="0.5"/>
<define name="AUTO_PITCH_MIN_PITCH" value="-0.5"/>

These lines are associated with vertical control loops contained in ./sw/airborne/fw_v_ctl.c but are not used in default. The non-default vertical control law is for the vertical rate to be managed by the pitch.

<define name="THROTTLE_SLEW_LIMITER" value="2" unit="s"/>
THROTTLE_SLEW_LIMITER is the required time is seconds to change throttle from 0% to 100%.

=== Misc ===
<tt>
<section name="MISC">
<define name="NOMINAL_AIRSPEED" value ="12." unit="m/s">
<define name="CARROT" value="5." unit="s"/>
<define name="KILL_MODE_DISTANCE" value="(1.5*MAX_DIST_FROM_HOME)"/>
<define name="CONTROL_RATE" value"60" unit="Hz"/>
</section>
</tt>

* The "NOMINAL_AIRSPEED" is mainly used in the simulator.
* "CARROT" gives the distance (in seconds, so ground speed is taken into account) between the carrot and the aircraft.
* "KILL_MODE_DISTANCE" is the threshold distance to switch the autopilot into KILL mode (defined descent with no throttle)
* "CONTROL_RATE" is the rate of the low level control loops in Hertz (60 or 20).

== Hardware definitions - Makefile ==

The airframe file must include the description of the controller board and it's low-level settings. This is done in one <b><tt>makefile</tt></b> section starting with the autopilot model and flashing mode:
{{Box Code|conf/airframes/myplane.xml|
<makefile>
include $(PAPARAZZI_SRC)/conf/autopilot/tiny.makefile
<nowiki>FLASH_MODE=IAP</nowiki>
.
.
.
</makefile>
}}
Below this are the definintions and configuration of the peripherals and interfaces.

=== R/C ===

{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DRADIO_CONTROL -DRADIO_CONTROL_TYPE=RC_FUTABA</nowiki>
<nowiki>ap.EXTRA_SRCS += radio_control.c $(SRC_ARCH)/ppm_hw.c</nowiki>
<nowiki>ap.CFLAGS += -DACTUATORS=\"servos_direct_hw.h\"</nowiki>
<nowiki>ap.EXTRA_SRCS += $(SRC_ARCH)/servos_direct_hw.c</nowiki>
}}

You can set RADIO_CONTROL_TYPE to RC_FUTABA, for falling edge PPM, or RC_JR for rising edge PPM. "RC_FUTABA" is for The Futaba or compatible brands, and "RC_JR" for JR (a.k.a Graupner outside of the USA) or compatible brands.

For the classix, you must specify which pins to use for PWM by adding "-DPWM_SERVO_0, etc." to the line fbw.CFLAGS. This activate the PWM channel.

<tt>wiring on classix PWM connector
connector LPC shared port
PWM1 PWM5 AD1_6 CAP1_3 P0.21
PWM2 PWM3 RXD0 EINT0 P0.1
PWM3 PWM1 TXD0 P0.0
PWM4 PWM6 RXD1 EINT3 P0.9
PWM5 PWM4 TXD1 AD1_1 P0.8
PWM6 PWM2 SSEL0 EINT2 P0.7</tt>

PWM1 and PWM6 should be safe. PWM4 and PWM5 should be OK if you're not using UART1 on the FBW processor - same for PWM2 and PWM3 if you're not using UART0 (disable FBW telemetry for that ).

=== Modem ===
The modem protocol and baud rate must be set in both the airframe file and ground station. Any standard baud rate can be used, with 9600 being adequate and 57600 recommended for most users to allow high speed telemetry for more detailed flight data analysis. The actual data rate is determined by the number of messages being sent and the period of each message as defined in <tt>conf/telemetry/default.xml</tt>. Those wishing to experiment with "alternative" modems can reduce the number and period of each telemetry message to fit within most any bandwidth constraint.

Paparazzi supports the following modem protocols:
* Standard transparent serial (pprz) - this is compatible with all modems and can be used to connect the autopilot directly to a PC for testing without a modem.
* Maxstream API protocol (xbee) - compatible with all Maxstream modems including the 9XTend and Zigbee. This protocol enables hardware addressing, allowing multiple aircraft to be managed from a single ground modem.
* Coronis Wavecard - necessary for operation with the unusual Coronis Wavecard modem.
Select the baud/protocol in the airframe file by commenting/uncommenting the appropriate section as follows:
==== Configuring The Serial Protocol ====
New users are advised to start with the standard serial protocol before attempting to setup an addressed API link. There are no real reasons for the novice user to use the xbee protocol over the standard PPRZTransport. Even if you are using a Maxstream modem you should still start out with the standard. Lastly it should be pointed out that using a single UAV there is no disadvantage and that the [http://www.engr.usu.edu/wiki/index.php/OSAM OSAM] Paparazzi Team at UAS 2008 took second place using the STANDARD protocol. The serial protocol works with virtually any modem as well as direct cable connections. The baud rates of the airborne modem, autopilot, ground modem, and PC must be configured correctly. The PC and autopilot serial ports do not need to be set to the same baud rate, i.e. when running multiple aircraft from a single ground modem, the ground modem may require a higher baud rate than any of the airborne modems in order to stream the data from multiple simultaneous sources.

{{Box Code|conf/airframes/myplane.xml|
<nowiki>
<section name="DATALINK" prefix="DATALINK_">
<define name="DEVICE_TYPE" value="PPRZ"/>
<define name="DEVICE_ADDRESS" value="...."/>
</section>
</nowiki>
}}
The above example tells the autopilot to send and recieve data in standard serial form.

{{Box Code|conf/airframes/myplane.xml - makefile section at the bottom|
# Serial modem
<nowiki>ap.CFLAGS += -DDOWNLINK -DUSE_UART0 -DDOWNLINK_TRANSPORT=PprzTransport -DDOWNLINK_FBW_DEVICE=Uart0 -DDOWNLINK_AP_DEVICE=Uart0 -DPPRZ_UART=Uart0 -DDATALINK=PPRZ -DUART0_BAUD=B57600</nowiki>
<nowiki>ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c pprz_transport.c</nowiki>
}}
The above example configures the autopilot serial port (Uart0) to 57,600 baud and calls the serial transport protocol (pprz_transport.c). Use the "#" symbol to comment lines in this section of the airframe file.
<br>
Note:
* The autopilot and modem serial port baud rates must match at all times and also must match the ground modem rate, check your modem documentation to find the default baud rate and configure a different rate as needed.

<br style="clear:both>

Ensure that the ground station is using the same protocol and an equal or higher baud rate:
{{Box Code|conf/control_panel.xml|
<nowiki>
<session name="USB">
<program name="link">
<arg flag="-d" constant="/dev/paparazzi/ttyUSB0"/>

<arg flag="-uplink" constant=""/>
<arg flag="-s" constant="57600"/>
</program>
...
</session>
</nowiki>
}}
Use this constant /dev/paparazzi/ttyUSB0 when using either the ftdi cable or a Maxstream USB ground modem.. Otherwise use /dev/ttyUSB0 (the ttyUSB0 being the device that you are using. Note: it might not always be ttyUSB0). This paparazzi directory in the dev folder is created when setting the udev rules. [http://paparazzi.enac.fr/wiki/index.php/Installation#Setting_access_rights_for_USB_download Setting Udev rules]

==== Configuring The Maxstream API Protocol ====
The optional API protocol enables hardware addressing so that multiple aircraft can be managed from a single ground modem, or multiple aircraft and multiple ground stations can work simultaneously without interference from one another. API mode is enabled by sending an escape sequence (+++) followed by AT commands, this can be done automatically at each boot or can be permanently configured with the "ATWR" command for greater reliability.

{{Box Code|conf/airframes/myplane.xml|
<nowiki>
<section name="MISC">
...
<define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\ATBD6\rATWR\r\""/>
<define name="NO_XBEE_API_INIT" value="FALSE"/>
...
</section></nowiki>
}}
The above example will program the Maxstream to API mode, 100mW power (ATPL2), 57600 baud (ATBD6), and permanently store the changes (ATWR). After flashing allow 30 seconds for the modem to store the changes, then disable the init string <tt><define name="NO_XBEE_API_INIT" value="<b>TRUE</b>"/></tt>, update the baud rate as needed, and re-flash the autopilot. The modem and autopilot serial port baud rates must match eachother at all times.
<br>
Notes:
* Maxtream modems are factory configured for 9600 baud, in order to change baud rates, first configure the autopilot serial port to match the modem (DUART0_BAUD=B9600), boot the system so that the baud rate change command is sent to the modem (ATBD6) and permanently saved (ATWR), allow 30 seconds for the modem configuration to complete, then reprogram the autopilot with the new baud rate (DUART0_BAUD=B57600) and disabled modem configuration string <tt><define name="NO_XBEE_API_INIT" value="<b>TRUE</b>"/> </tt>.
* The ac_id defined in <tt>conf/conf.xml</tt> is permanently programmed into the modem so this procedure would need to be re-run if the modem is moved to another plane.
* For temporary boot-time API configuration remove any baud rate changes, remove <tt>ATWR\r</tt> from the end of the string and keep "NO_XBEE_API_INIT" value="FALSE".
* Upgrade your Maxstream firmware to the latest version before attempting API mode operation.

<br style="clear:both>

{{Box Code|confAgain/airframes/myplane.xml - makefile section at the bottom|
<nowiki># Maxstream API protocol</nowiki>
<nowiki>ap.CFLAGS += -DDOWNLINK -DUSE_UART0 -DDOWNLINK_TRANSPORT=XBeeTransport -DDOWNLINK_FBW_DEVICE=Uart0 -DDOWNLINK_AP_DEVICE=Uart0 -DXBEE_UART=Uart0 -DDATALINK=XBEE -DUART0_BAUD=B57600</nowiki>
<nowiki>ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c xbee.c</nowiki>
}}
The above example configures the autopilot serial port (Uart0) to 57,600 baud and calls the Maxstream transport protocol (xbee.c). Use the "#" symbol to comment lines in this section of the airframe file.
<br style="clear:both>

Ensure that the ground station is using the same protocol and an equal or higher baud rate:
{{Box Code|conf/control_panel.xml|
<nowiki>
<session name="USB">
<program name="link">
<arg flag="-d" constant="/dev/paparazzi/ttyUSB0"/>
<arg flag="-transport" constant="xbee"/>
<arg flag="-uplink" constant=""/>
<arg flag="-s" constant="57600"/>
</program>
...
</session>
</nowiki>
}}
Use this constant /dev/paparazzi/ttyUSB0 when using either the ftdi cable or a Maxstream USB ground modem.. Otherwise use /dev/ttyUSB0 (the ttyUSB0 being the device that you are using. Note: it might not always be ttyUSB0). This paparazzi directory in the dev folder is created when setting the udev rules. [http://paparazzi.enac.fr/wiki/index.php/Installation#Setting_access_rights_for_USB_download Setting Udev rules]
=====Alternate Method=====
This is the way it is done in funjet1.xml and has been tested to work by Danstah

{{Box Code|conf/airframes/funjet1.xml|
<nowiki>
<section name="MISC">
...
<define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\""/>

...
</section></nowiki>
}}
Also use this
{{Box Code|conf/airframes/funjet1.xml|
<nowiki>

<section name="DATALINK" prefix="DATALINK_">
<define name="DEVICE_TYPE" value="XBEE"/>
<define name="DEVICE_ADDRESS" value="...."/>
</section>
</nowiki>
}}
And Finally use this in the makefile section
{{Box Code|conf/airframes/funjet1.xml|
<nowiki>
ap.CFLAGS += -DDOWNLINK -DUSE_UART1 -DDOWNLINK_TRANSPORT=XBeeTransport -DXBEE_UART=Uart1 -DDATALINK=XBEE -DUART1_BAUD=B9600
ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c xbee.c
</nowiki>
}}
By reading all the information above you should be able to infer what the above does

Now keep in mind that the ground modem baud rate and airplanes modem baud rates do not have to match. The only things that need to match are the the modem on the planes baud rate and the rate defined in the airframe file. For example this planes modem is set to 9600 and this could be used with the ground modem configured above using 57600...
Also for multiple UAV's a good way to configure them is to use 9600 for the ap and use a ground modem configured to 57600 and its not a bad idea to use minimal telemetry

=== GPS ===
The serial port settings must match that of the GPS and are configured here along with the necessary files to interpret the u-blox UBX binary protocol:

{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DGPS -DUBX -DUSE_UART1 -DGPS_LINK=Uart1 -DUART1_BAUD=B38400</nowiki>
<nowiki>ap.srcs += gps_ubx.c gps.c</nowiki>
}}
'''Note:'''
* u-blox GPS modules are factory configured for 9600 baud, 38,400 baud is recommended along with the other required changes. The GPS can be accessed directly thru the [[Compiling#USB_flashing|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center Configured with|u-center]]

If using the u-blox LEA-5H, add the flag -DGPS_USE_LATLONG in the makefile section of the airframe xml file.

{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DGPS_USE_LATLONG</nowiki>
}}

=== Sensors ===

=== Control loops ===

The control loops can be divided in two largely independent groups : the vertical ones and the horizontal ones (files sw/airborne/fw_h_ctl.c and sw/airborne/fw_v_ctl.c ). Those loops can be commanded at different levels by either the R/C transmitter or the autonomous navigation routine.

First the horizontal loop:
{{Box Code|conf/airframes/funjet1.xml|
<nowiki>ap.CFLAGS += -DNAV -DAGR_CLIMB -DLOITER_TRIM
ap.srcs += nav.c fw_h_ctl.c fw_v_ctl.c
</nowiki>
}}

== Radio Control ==
The Paparazzi autpilot interfaces directly with the PWM signal from any standard hobby R/C receiver. Signal decoding configuration settings for this are stored in the [[Radio_Control|Radio Control]] file.

Flight Plans

2008-09-25T08:49:34Z

Ben P: /* Set */

The formal description of the flight plan file is given in the DTD (located in <tt>conf/flight_plans/flight_plan.dtd</tt>). This
DTD must be referenced in the header of your flight plan XML file using the following line:<br>

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

The flight plans are stored in the <tt>conf/flight_plans</tt> directory. The [[Flight_Plan_Editor|flight plan editor]] can be used to create basic flight plans in the GUI.

== Structure of the flight plan file ==

Extract from the DTD:
<tt><!ELEMENT flight_plan (header?,waypoints,sectors?,include*,exceptions?,blocks)></tt>

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

The root <tt>flight_plan</tt> element is specified with several attributes:
<tt><flight_plan name lat0 lon0 ground alt security height qfu alt max_dist_from_home></tt>
* <tt>name</tt>: the name of the mission (a text string)
* <tt>lat0, lon0</tt>: describe the latitude and longitude of the point {0,0} in WGS84 degree coordinates
* <tt>ground_alt</tt>: the ground altitude (in meters). It defines the <tt>GROUND_ALT</tt> constant value which can be used to define waypoint altitudes
* <tt>security_height</tt>: the altitude used by the circle-home failsafe procedure
* <tt>qfu</tt> (optional): defines the global constant <tt>QFU</tt>. It usually is the magnetic heading in degrees (north=0, east=90) of the runway, the opposite of wind direction. This constant may be used in the mission description. It is also used by the simulator as the original course of the aircraft.
* <tt>alt</tt>: the default altitude of waypoints
* <tt>max_dist_from_home</tt>: the maximum allowed distance (in meters) from the HOME waypoint.

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

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

=== Waypoints ===

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

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

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

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

=== Sectors ===
Flat ''Sectors'' can be described as a list of waypoint corners. Such an area will be displayed in the GCS.
A function is generated to check if a point (usually the aircraft itself) is ''inside'' the polygon. Currently, this feature requires that the polygon is <b>convex</b> and described in a <b>clockwise</b> order. For a sector named <tt>Sector</tt>, the generated function is <tt>bool_t InsideSector(float x, float y);</tt> where <tt>x</tt> and <tt>y</tt> are east and north coordinated, in meters, relative to the geographic reference of the flight plan. Note: If the flight plan is dynamically relocated, such a sector will be relocated but the display is currently not updated on the GCS.

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

=== Include ===

<tt>include</tt> is used to add blocks 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 [x] [y] [rotate] > [<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 jump to the blocks of the <tt>procedure</tt>, the XML referenced file. The
procedure can be shifted (<tt>x</tt> meters east, <tt>y</tt> meters north) and <tt>rotate</tt>d (clockwise degrees, north=0).
Named arguments may be given with their value in the <tt>arg</tt> elements. The <tt>with</tt> tag allows to link labels from the procedure to blocks of the main flight plan.
Then, each block of the procedure is like any block of the flight plan and is designated with a dotted identifier: block <tt>b</tt> of a procedure named <tt>p</tt> is named <tt>b.p</tt> .

Here is an example:
<tt><include name="hippo1" procedure="hippo.xml" x="-100" y="150" rotate="0">
<arg name="alt" value="GROUND ALT+100"/>
<with from="event1" to="penta"/>
</include></tt>
where a jump to <tt>event1</tt> inside the <tt>hippo.xml</tt> procedure will actually jump to the <tt>penta</tt> block of the
current flight plan.

=== Blocks ===

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

As described in the DTD, the <tt>blocks</tt> element is composed of <tt>block</tt> elements which are sequence of ''stages'':
<tt><!ELEMENT blocks (block+)>
<!ELEMENT block (exception|while|heading|attitude|go|xyz|set|circle|deroute|stay|follow
|survey_rectangle)*></tt>

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

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

An icon can be specified to display the button. The <tt>strip_button</tt> label then is a tooltip for the icon. The icon must be an image file available in the directory <tt>data/pictures/gcs_icons</tt>:
<tt><block name="Takeoff" strip_icon="takeoff.png" strip_button="Takeoff"></tt>

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

===== Expressions =====

Most of the numeric attributes in stages are analyzed as C expressions. The syntax of this C expression is restricted to
* numeric constants
* some internal autopilot variables (not fully documented, see examples)
* Some binary operators: <, >, <=, >=, <>, ==, +, -, /, *
* Some utility functions

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

==== Exceptions ====

The flight manager can handle exceptions. They consist in conditions checked periodically (at the same pace as the navigation control), allowing the control to jump to a given block. Here is the syntax of exceptions:
<tt><exception cond="..." deroute="..."></tt>
where <tt>cond</tt> is an expression and <tt>deroute</tt> is the name of the block we want to switch to as soon as the condition is true.

Here are some example of exceptions:
<tt><exception cond="10 > PowerVoltage()" deroute="go_down"/>
<exception cond="(ground_alt+10 > estimator_z)" deroute="go_up"/>
<exception cond="(estimator_flight_time > 840)" deroute="quick_land"/></tt>

Exceptions can be local to a block or global to the flight plan, in the <tt><exceptions></tt> element. In the following example, time since last reception of a message from the ground station is monitored and the navigation is switched to the <tt>Standby</tt> block if no message have been received for 22s. This exception is valid for '''all''' the blocks.
<tt><flight_plan ...>
<waypoints> ... </waypoints>
<exceptions>
<exception cond="datalink_time > 22" deroute="Standby"/>
</exceptions>
<blocks> ...</tt>

==== Deroute ====

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

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

==== Loops ====

Unbounded loops are written with <tt>while</tt> elements whose <tt>cond</tt> attribute is a boolean expression.
Children of <tt>while</tt> are stages:
<tt><while cond="TRUE">
<go wp="A"/>
<go wp="B"/>
<go wp="C"/>
<while cond="5 > stage_time"/>
</while></tt>
In this example, we run an infinite loop, going to waypoints <tt>A</tt>, <tt>B</tt> and <tt>C</tt> and waiting for 5 seconds before repeating.

Bounded loops are written with the <tt>for</tt> tag:
<tt><for var="i" from="0" to="3">
...
</for></tt>
where the body of the loop will be run four times.

The variable of a <tt>for</tt> loop can be used inside expressions appearing as attributes of the stages:
<tt><for var="i" from="1" to="5">
<circle wp="HOME" radius="75" alt="ground_alt+50*$i" until="stage_time>10" />
</for></tt>
In this example, we circle around '''HOME''' 10 seconds at height 50m, 10s at height 100m, ... until height 250m.
Note: Two bounded loops using the same control variable are not allowed in the same block.

==== Navigation modes ====

Navigation modes give the description of the desired trajectory in 3D. While the horizontal mode is specified through
''stages'', the vertical control is specified with various attributes of these stages. The current available navigation stages are
* attitude : just keep a fixed attitude;
* heading : keep a given course;
* go : go to a given waypoint;
* circle : circle around a waypoint;
* stay : hold the position (hard to realize for a fixed-win aircraft);
* follow : follow another aircraft;
* xyz : circle around a point moveable with the RC transmitter stick (obsolete with the datalink).

The vertical control is achieved using the <tt>vmode</tt> attribute of these stages. The possible values are
* '''alt''' (the default) : the autopilot keeps the desired altitude which is the altitude of the waypoint (if any) or the altitude specified with the <tt>alt</tt> attribute;
* '''climb''' : the autopilot keeps the desired vertical speed specified with the <tt>climb</tt> attribute (in m/s);
* '''throttle''' : the autopilots sets the desired throttle specified with the <tt>throttle</tt> attribute (between 0 and 1);
* '''glide''' : the autopilot keeps the desired slope between two waypoints

The default control is done with the throttle. However, setting the <tt>pitch</tt> attribute to '''auto''' and the <tt>throttle</tt> attribute to a constant allows a vertical control only by controlling the attitude of the A/C.
The <tt>pitch</tt> attribute also can be set to any value (in degrees) while the throttle control is in use: it usually affects the airspeed of the aircraft.

The different navigation modes are detailed in the next sections.

==== Attitude ====
Element <tt>attitude</tt> is the navigation mode which corresponds to the current lowest control loop for horizontal mode.
The autopilot then keeps a constant attitude. The <tt>roll</tt> attribute is required (in degrees, positive to put right wing low).

To fly away, at constant airspeed:
<tt><attitude roll="0" vmode="throttle", throttle="0.5"/></tt>

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

Note that it is not a ''safe'' navigation mode since the geographic position of the plane is not controlled. However, this mode is useful to tune the roll attitude control loop.

==== Heading ====
<tt>heading</tt> primitive is relative to the second level loop for horizontal mode in the autopilot which will keep the given <tt>course</tt>, a required attribute (in degrees, clockwise, north=0, east=90).

One example to takeoff, following the QFU, 80% throttle, nose up until height of 30m is reached:
<tt><heading course="QFU" vmode="throttle" throttle="0.8" pitch="15" until="(estimator_z > ground_alt+30)"/></tt>

==== Go ====
The <tt>go</tt> primitive is probably the most useful one. Basically, the autopilot will try to join a given waypoint (<tt>wp</tt>, the only required attribute). So the simplest thing you can ask for is
<tt><go wp="HOME"/></tt>
which will set the '''HOME''' waypoint as the desired target position. Note than since <tt>vmode="alt"</tt> is the default, the altitude of the target waypoint is also taken into account. The navigation will switch to the next stage as soon as the target is reached.

It is usually not a good idea to try to join a waypoint without asking for a precise trajectory, i.e. a given line.
Setting the <tt>hmode</tt> attribute to '''route''', the navigation will go over a segment joining two waypoints:
<tt><go from="wp1" wp="wp2" hmode="route"/></tt>

The target altitude is the altitude of the target waypoint; it can also be set with the <tt>alt</tt> attribute. The following example keeps an altitude with fixed throttle:
<tt><go from="wp2" wp="wp3" hmode="route" pitch="auto" throttle="0.75" alt="ground_alt+100"/></tt>

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

Finally, the <tt>approaching_time</tt> (in seconds) attribute helps to decide when the target is ''reached''. It can be set
to '''0''' to go over the target waypoint (default value is the '''CARROT''' time, set in the airframe configuration file).
<tt><go from="wp1" wp="wp2" hmode="route" approaching_time="1"/></tt>

==== Circle ====

The <tt>circle</tt> primitive is the second main navigation mode: the trajectory is defined as a circle around a given waypoint with a given radius:
<tt><circle wp="HOME" radius="75"/></tt>
A positive radius makes the UAV fly 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, over growing circles, until the battery level is low:
<tt><circle wp="wp1" radius="50+(estimator_z-ground_alt)/2" vmode="throttle" throttle="0.75" pitch="15" until="10>PowerVoltage()"/></tt>

==== Follow ====

The <tt>follow</tt> is a special primitive which makes the UAV follow another UAV (real or simulated, named with its <tt>ac_id</tt>) at a given <tt>distance</tt> (in meters) behind and at a given <tt>height</tt> (in meters) above.

In this example, the autopilot will try to follow A/C number '''4''', staying '''50'''m behind and '''20'''m above.
<tt><follow ac_id="4" distance="50" height="20"/></tt>

==== Stay ====

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

==== Xyz ====

<tt>xyz</tt> is a special mode where the UAV circles around a user moveable waypoint. This waypoint is moved with the RC sticks:
* YAW channel controls the point over the west-east axis;
* PITCH channel controls the point over the south-north axis;
* ROLL channel controls the altitude.

Example (default radius is '''100'''):
<tt><xyz radius="40"/></tt>

==== Set ====
The <tt>set</tt> element is a dangerous one which should be used only by expert users: it is used to directly set an internal variable of the autopilot. For example, you can change the value of the default ground altitude, a variable used by the home mode failsafe procedure (and maybe by your own flight plan):
<tt><set var="ground_alt" value="ground_alt+50"/></tt>
This directive is extremely powerful and has great potential for error - use with caution.

==== Call ====
The <tt>call</tt> allows the user to define its own navigation procedures in C. The <tt>value</tt> must be a call to a boolean function which must return TRUE as long as the stage is not completed (a function which should be called only once would then return immediately FALSE).
This feature is illustrated with the '''line''' pattern:
<tt><call fun="nav_line_init()"/>
<call fun="nav_line(WP_1, WP_2, nav_radius)"/></tt>
where <tt>nav_line_init()</tt> returns FALSE and <tt>nav_line()</tt> always returns TRUE (this stage never ends).
Such functions usually are defined in a supplementary C file which must be specified in the airframe file (in the <tt>makefile</tt> section)
<tt>ap.srcs += nav_line.c
sim.srcs += nav_line.c</tt>
These functions also must be declared in a header file which must be mentioned in the header element of the flight plan:
<tt><header>
#include "nav_line.h"
</header></tt>
These C source file and H header file must be located in the <tt>sw/airborne</tt> directory.

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

== Procedures ==

Procedures are libraries which can be included in flight plans. They are composed of waypoints and blocks. The header of a procedure may
contain some parameters which are replaced by arguments when the procedure is included.

Extract of the DTD: a procedure is a sequence of parameters, waypoints, optional global exceptions and blocks:
<tt><!ELEMENT procedure (param*,waypoints,exceptions?,blocks)></tt>

A <tt>param</tt>eter is just a name. A parameter is optional if it is declared with a default value.
An example with a required and an optional parameter:
<tt><param name="alt"/>
<param name="radius" default_value="75"/></tt>

Procedures are called with the <tt>include</tt> element in a flight plan (a procedure cannot be included by another procedure). A procedure call requires:
* the name of the procedure file, the name given to this inclusion;
* the relative position and the orientation of the procedure in the flight plan;
* values for the parameters;
* backlinks for block name exits of the procedure.

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

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

Note that the name of procedure block is then '''hippo1.oneturn''':
<tt><deroute block="hippo1.oneturn"/></tt>
will jump to this procedure block.

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