Difference between revisions of "Airframe Configuration"

From PaparazziUAV
Jump to navigation Jump to search
 
(162 intermediate revisions by 28 users not shown)
Line 1: Line 1:
The airframe configuration file is located in <tt>conf/airframes</tt> and contains
<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Airframe_Configuration</categorytree>
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 ==
== About ==
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 ==
The airframe file is the most important configuration file and contains all the hardware and software settings for your airframe. It describes what hardware you have and which firmware, sensors, algorithms, etc. you want to use and also holds your configuration parameters. All gains, trims, and behavior settings are defined with standard XML elements.
=== Commands ===
 
The XML airframe configuration file is located in <tt>conf/airframes/<yourairframe>.xml</tt> and always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line and should look like this
{{Box Code|conf/airframes/<yourairframe>.xml|<source lang="xml">
<!DOCTYPE airframe SYSTEM "airframe.dtd">
<airframe name="yourairframe">
  <!-- The airframe configuration goes here. -->
</airframe>
</source>}}
 
<b>Also see the wiki pages for [[Fixedwing_Configuration|fixedwing specific configuration]] and [[Rotorcraft_Configuration|rotorcraft specific configuration]].</b>
 
== Creating a new Aircraft ==
 
While the airframe file is where you configure most aspects of your aircraft, a fully specified aircraft needs several XML configuration files:
* Airframe (what this page is about)
* [[Flight_Plans|Flight Plan]]
* [[Settings]]
* [[Radio_Control|Radio]] (if you use a PPM based R/C system)
* [[Telemetry]]
* [[settings_modules]]
Each aircraft is assigned a name, unique ID and the associated configuration files in [[Conf.xml|<tt>conf/conf.xml</tt>]]. To create a new Aircraft, click new in the menu A/C in the [[Paparazzi_Center|Paparazzi Center]] and select your new airframe file, etc. (or specify it by hand in [[Conf.xml|<tt>conf/conf.xml</tt>]]).
 
== Firmware and Hardware definitions ==
First you should specify which firmware you want to use, that is if you have a <tt>[[Fixedwing_Configuration|fixedwing]]</tt> aircraft or a <tt>[[Rotorcraft_Configuration|rotorcraft]]</tt>:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
  <firmware name="fixedwing or rotorcraft">
    ...
  </firmware>
</source>
}}
 
=== Select your Board ===
 
To specify autopilot hardware you are using and it's low-level settings you have to add a ''target''-tag.
Each ''target'' has two attributes, which are ''name'' and a corresponding ''board'' attribute.
The ''name'' attribute is either "ap" (autopilot) or "sim/jsbsim/nps" (simulation).
 
 
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
  <firmware name="fixedwing or rotorcraft">
    <target name="sim" board="pc"/> <!-- For simulation. -->
    <target name="ap"  board="lisa_m_1.0"/> <!-- Select your board here -->
    ...
  </firmware>
</source>
}}
 
==== Simulation targets ====
 
target name="sim","jsbsim","nps"<br/>
board="pc"<br/>
 
More Information at [[Simulation]].


The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. In our example, we have only three:
==== Board targets ====
<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 ===
target name="ap"<br/>
board=
"apogee_0.99",
"apogee_1.0",
"ardrone2",
"booz_1.0",
"classix",
"hb_1.1",
"krooz_sd",
"lisa_l_1.0",
"lisa_l_1.1",
"lisa_m_1.0",
"lisa_m_2.0",
"lisa_mx_2.0",
"lisa_s_0.1",
"logom_2.6",
"navgo_1.0",
"sdlog_1.0",
"stm32f4_discovery",
"tiny_0.99",
"tiny_1.1",
"tiny_2.1",
"tiny_2.11",
"twog_1.0",
"umarim_1.0",
"umarim_lite_2.0",
"yapa_2.0",


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:
All targets can be found in /conf/boards.
<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:
==== Direct Makefile ====
<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.


Optionally you can also add a raw [http://en.wikipedia.org/wiki/Makefile Makefile] section. This is only needed in very advanced setups. For example when testing newly developed hardware.


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


=== Manual ===
You can configure the LEDs on the autopilot to be used for different status indicators:
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:
; ''SYS_TIME_LED'': blinks with 1Hz
; ''AHRS_ALIGNER_LED'': blinks until the AHRS is aligned (gyro bias initialized) and then stays on
; ''GPS_LED'': blinking if trying to get a fix, on if 3D fix
; ''RADIO_CONTROL_LED'': on if RC signal is ok
; ''BARO_LED'' : only on booz and navgo boards: blinks until baro offset is initialized and then stays on


<rc_commands>
Depending on your board some of the LEDs on it are already assigned to some indicators by default, check the appropriate autopilot board makefile for the defaults.
  <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.
To reconfigure the default assignment, assign the indicator to an other value. Use ''none'' if indicator should not be assigned to any LED.


=== Autopilot Only Commands ===
{{Box Code|conf/airframes/myplane.xml|
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.
<source lang="xml">
  <firmware name="fixedwing or rotorcraft">
    ...
    <configure name="SYS_TIME_LED" value="1"/>
    <configure name="RADIO_CONTROL_LED" value="2"/>
    <configure name="GPS_LED" value="none"/>
  </firmware>
</source>
}}


<ap_only_commands>
Beware that you can only assign '''one''' indicator to a LED number. So if the LED you want to use is already in use because another indicator is set to that number by default you have to disable that other indicator by setting it to ''none'' or reconfigure it to an other LED.
  <copy command="PAN"/>
  <copy command="TILT"/>
  <copy command="SHOOT"/>
</ap_only_commands>


=== Auto1 ===
== Subsystems ==
The next section, named <b><tt>AUTO1</tt></b>, gives the maximum roll and pitch (in radians) allowed for the augmented stability mode.
{| class="wikitable"
<tt>
|-
<section name="AUTO1" prefix="AUTO1_">
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. The roadmap of Paparazzi is to convert existing subsystems to [[modules]].
  <define name="MAX_ROLL" value="RadOfDeg(35)"/>
|}
  <define name="MAX_PITCH" value="RadOfDeg(35)"/>
Each autopilot features certain [[Subsystems|subsystems]] which need to be configured properly.
</section>
The most important ones are described below.
</tt>
<br>


=== ADC ===  
=== IMU ===
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
Add the [[Subsystem/imu|imu subsystem]] with the type you are using.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
  <firmware name="fixedwing or rotorcraft">
    ...
    <module name="imu"      type="aspirin_v1.5"/>
  </firmware>
</source>
}}


=== Infrared ===
See the [[Subsystem/imu|imu subsystem]] page for more details.
The <b><tt>INFRARED</tt></b> section describes the configuration of the infrared sensors.
Also see the [[ImuCalibration|IMU calibration]] page.


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


<section name="INFRARED" prefix="IR_">
The [[Subsystem/ahrs|AHRS subsystem]] specifies which attitude estimation filter you are using, e.g. for the complementary filter:
  <define name="ADC_IR1_NEUTRAL" value="512"/>
{{Box Code|conf/airframes/myplane.xml|
  <define name="ADC_IR2_NEUTRAL" value="512"/>
<source lang="xml">
  <define name="ADC_TOP_NEUTRAL" value="512"/>
  <firmware name="fixedwing or rotorcraft">
    ...
    <module name="ahrs" type="int_cmpl_euler"/>
  </firmware>
</source>
}}
All AHRS algorithms depend on an imu subsystem, except for the ahrs_infrared which depends on the infrared module.
See the [[Subsystem/ahrs|AHRS subsystem page]] for more details.


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.
If the magnetometer should be used the [[Subsystem/ahrs#Local_Magnetic_Field|local magnetic field section]] must be filled in.


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:
=== Radio Control ===


  <define name="IR2_SIGN" value="-1"/>
Supported types are:
  <define name="TOP_SIGN" value="-1"/>
* ''ppm''
* ''spektrum''
* ''sbus''
* ''datalink''


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.  
Just specify the appropriate [[Subsystem/radio_control|radio control subsystem]] in your firmware section, e.g.:
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
  <firmware name="fixedwing or rotorcraft">
    ...
    <module name="radio_control"    type="ppm"/>
  </firmware>
</source>
}}


  <define name="HORIZ_SENSOR_TILTED" value="0"/>
=== Telemetry (Modem) ===


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:
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 your [[Telemetry|telemetry file]], e.g. <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.


  <define name="LATERAL_CORRECTION" value="0.7"/>
The [[Subsystem/telemetry|telemetry subsystem]] supports the following modem protocols:
  <define name="LONGITUDINAL_CORRECTION" value="0.7"/>
* 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.
  <define name="VERTICAL_CORRECTION" value="1."/>
* 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.
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.
Just specify the appropriate [[Subsystem/telemetry|telemetry subsystem]] in your firmware section. You can currently choose between the types ''transparent'', ''transparent_usb'' and ''xbee_api''.
  <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.
'''The default baudrate is 57600 baud, see the [[Subsystem/telemetry|telemetry subsystem]] page for more details and configuration options.'''
  <define name="CORRECTION_UP" value="1."/>
{{Box Code|conf/airframes/myplane.xml|
  <define name="CORRECTION_DOWN" value="1."/>
<source lang="xml">
  <define name="CORRECTION_LEFT" value="1."/>
  <firmware name="fixedwing or rotorcraft">
  <define name="CORRECTION_RIGHT" value="1."/>
    ...
</section>
    <module name="telemetry"     type="transparent"/>
These corrections are set on the angles.
  </firmware>
</source>
}}


=== Gyro ===  
=== GPS ===
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>
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:
<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>


Just specify the appropriate [[Subsystem/gps|gps subsystem]] in your firmware section. You can currently choose between the types '''ublox''' and '''ublox_utm''' for the older series 4 modules which still provide a UTM message.
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
  <firmware name="fixedwing or rotorcraft">
    ...
    <module name="gps"              type="ublox"/>
  </firmware>
</source>
}}


=== Bat ===
The correct UART is already defined by default according to your board.
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 default GPS baudrate is 38400baud.


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.
If you need to set different baud rates or UART see the [[Subsystem/gps]] page for the options.


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.
'''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 through the [[tunnel|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center|Configured with u-center]]


<tt>
== XML Parameters ==
<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 ===
'''When defining parameters you can use [[Units|automatic unit conversion]] to conveniently set it in e.g. degrees.'''
<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.
=== Commands ===


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.
The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. In a simple fixed-wing example, we have only three:
<source lang="xml">
<commands>
  <axis name="THROTTLE" failsafe_value="0"/>
  <axis name="ROLL"    failsafe_value="0"/>
  <axis name="PITCH"    failsafe_value="0"/>
</commands>
</source>
For rotorcraft, it is usually:
<source lang="xml">
<commands>
  <axis name="PITCH"    failsafe_value="0"/>
  <axis name="ROLL"    failsafe_value="0"/>
  <axis name="YAW"      failsafe_value="0"/>
  <axis name="THRUST"  failsafe_value="0"/>
</commands>
</source>


===Vertical Control===
Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board. The range of these values is [-9600:9600]. For <tt>"THROTTLE"</tt>, the range is [0, 9600] and in the corresponding <b><tt>servo</tt></b> definition the <b><tt>neutral</tt></b> and <b><tt>min</tt></b> are usually the same for PWM based servos (see below). Note that these commands do not necessarily match the servo actuators. For example, the <tt>"ROLL"</tt> command is typically linked to two aileron actuators.


  <section name="VERTICAL CONTROL" prefix="V_CTL_">
=== Servos ===
    <!-- outer loop proportional gain -->
    <define name="ALTITUDE_PGAIN" value="-0.1" unit="(m/s)/m"/>
    <!-- outer loop saturation -->
    <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.
The above commands get translated to the <b><tt>servos</tt></b> here. In the example below we use two elevons and a motor. ([http://en.wikipedia.org/wiki/Elevon ''Elevons''] are surfaces used for both pitch and roll as on a flying wing.) These servos are listed in the <b><tt>servos</tt></b> section:
<source lang="xml">
<servos>
  <servo name="THROTTLE"        no="0" min="1000" neutral="1000" max="2000"/>
  <servo name="ELEVON_LEFTSIDE"  no="1" min="2000" neutral="1500" max="1000"/>
  <servo name="ELEVON_RIGHTSIDE" no="2" min="1000" neutral="1500" max="2000"/>
</servos>
</source>


    <define name="AUTO_PITCH_PGAIN" value="-0.1"/>
Names are associated to the corresponding '''real physical connector''' to which a servo is connected '''on the autopilot board'''. For example no="2" means connector two on the board. Also the servo neutral value, total range and direction are defined. Min/max/neutral values are expressed in microseconds. The direction of travel can be reversed by exchanging min with max (as in <tt>"ELEVON_LEFTSIDE"</tt>, above).  The ''standard'' travel for a hobby servo is 1000µs - 2000µs with a 1500µs neutral. Trim can be added by changing this neutral value. Absolute servo 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>.
    <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.
The attribute <b><tt>driver</tt></b> for <b><tt>servos</tt></b> node tells which actuators' driver is associated to the listed servos. After the version '''v4.9_devel-164-gdb0d004''', multiple servos sections can be defined and used together, if the correct [[Subsystem/actuators| actuators subsystems]] are loaded. Some boards are automatically loading a default driver, the one used when no <b><tt>driver</tt></b> attribute is specified.


  <define name="THROTTLE_SLEW_LIMITER" value="2" unit="s"/>
Note the following important tips:
THROTTLE_SLEW_LIMITER is the required time is seconds to change throttle from 0% to 100%.
* Reverse the servo direction by exchanging min/max
* Trim should always be adjusted mechanically if possible to avoid asymmetrical 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-2000µs range but experiment carefully as the servo may not operate reliably outside this range and may even suffer permanent damage.
* Board connector numbering starts with <b>zero (0)</b> not with one
* Servos are also known under the synonym <b>actuators</b>
* (after version '''v4.9_devel-164-gdb0d004''') For I2C based motor speed control using the [[Rotorcraft_Configuration#Motor_Mixing|motor mixing]]:
** min: command to stop the motor
** neutral: motor idle command
** max: max thrust command


=== Misc ===
The <b><tt>servos</tt></b> are then linked to the commands in the <b><tt>command_laws</tt></b> section:
<tt>
<source lang="xml">
<section name="MISC">
<command_laws>
   <define name="NOMINAL_AIRSPEED" value ="12." unit="m/s">
   <let var="aileron"           value="@ROLL  * 0.3"/>
   <define name="CARROT" value="5." unit="s"/>
   <let var="elevator"           value="@PITCH * 0.7"/> 
   <define name="KILL_MODE_DISTANCE" value="(1.5*MAX_DIST_FROM_HOME)"/>
  <set servo="THROTTLE"         value="@THROTTLE"/>
   <define name="CONTROL_RATE" value"60" unit="Hz"/>
   <set servo="ELEVON_LEFTSIDE" value="$elevator + $aileron"/>
  </section>
   <set servo="ELEVON_RIGHTSIDE" value="$elevator - $aileron"/>
</tt>
  </command_laws>
</source>


* The "NOMINAL_AIRSPEED" is mainly used in the simulator.
[[Image:airframe_sign_conventions.jpg|thumb|Sign conventions for flight dynamics]]
* "CARROT" gives the distance (in seconds, so ground speed is taken into account) between the carrot and the aircraft.
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.  Elevon 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.
* "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:
Note that the signs used in the description follow the standard convention.
{{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 ===
After '''v4.9_devel-164-gdb0d004''', the <b><tt>command_laws</tt></b> section is mandatory for both fixedwing and rotorcraft firmwares, only for fixedwing otherwise.


{{Box Code|conf/airframes/myplane.xml|
=== Battery ===  
  <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.
This section gives characteristics for monitoring the main power battery.


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.  
<b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> represents the actual current (in mA) when full THROTTLE is applied. Note that when flying the current typically is significantly lower than in static tests at home on your workbench. <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message when no [[Current_sensor|Current sensor]] is mounted in the airframe. This value can also be used in flight plans. For example, if at full throttle your motor consumes 10 Amps, use a value of 10000. You can "tweak" this number after a few flights to match the capacity of your battery. If upon landing your bat.energy messages says that you used 2500 mAh while the energy recharged into the battery is only 2000 mAh, you could reduce the <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> value by 20% to match your in-flight current consumption. This tweaking is most precise if you fly full throttle only (respectively no throttle to glide down again).


  <tt>wiring on classix PWM connector
The <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> can be added to tweak the energy estimation for non full throttle cruise. As the current consumption is nonlinear, at 50% throttle it is likely to be substantially less than 50%. A superellipse is used to approximate this nonlinearity. The default setting is 1.2 and is used if the <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> is not defined in your airframe file. A value 1 corresponds to linear behaviour, 1.5 corresponds to strong nonlinearity. The tweaking is done same as described above for <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b>, but only partial throttle (cruise throttle) should be applied in flight.
  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 ).
If both <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> and <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> are tweaked well, you get precise energy estimations with less than 5% error independent of your flight pattern without even requiring a [[Current_sensor|current sensor]].


=== Modem ===
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 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:
The <b><tt>MAX_BAT_LEVEL</tt></b> may be specified to improve the display of the battery gauge in the strip or in "papgets". Note that this definition is optional, with a default value of 12.5V.
* 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|
{{Box Code|conf/airframes/myplane.xml|
<nowiki>
<source lang="xml">
<section name="DATALINK" prefix="DATALINK_">
  <firmware name="fixedwing">
     <define name="DEVICE_TYPE" value="PPRZ"/>
    ...
     <define name="DEVICE_ADDRESS" value="...."/>
    <define name="ADC_CHANNEL_VSUPPLY" value="ADC_4" />
  </firmware>
  ...
  <section name="BAT">
    <define name="MILLIAMP_AT_FULL_THROTTLE" value="12000" unit="mA" />
     <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>
   </section>
</nowiki>
</source>
}}
}}
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|
The conversion of ADC measurements to Voltage is already defined for the different autopilot boards, if you need to override these defaults you can use the <b><tt>VoltageOfAdc(adc)</tt></b> define and also specify offsets or anything else you might need, e.g.:
# 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>
{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c pprz_transport.c</nowiki>
<source lang="xml">
  <section name="BAT">
    ...
    <define name="VOLTAGE_ADC_SCALE" value="0.0177531"/>
    <define name="VOLTAGE_OFFSET" value="0.5" unit="V"/>
    <define name="VoltageOfAdc(adc)" value="(VOLTAGE_ADC_SCALE * adc + VOLTAGE_OFFSET)"/>
  </section>
</source>
}}
}}
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>
Calculating '''VOLTAGE_ADC_SCALE''':
 
<math>VOLTAGE\_ADC\_SCALE=\frac{Vref}{ADCresolution-1}\div\frac{R2}{R1+R2}</math>
 
*Vref - Voltage reference for the ADC (will be 3.3V in most cases, can be found in mcu/adc datasheet)
*ADCresolution - ADC bit depth (e.g. 2^12=4096 for a 12 bit ADC)
*R1 - Resistor between battery and ADC input pin of MCU
*R2 - Resistor between ADC input pin of the MCU and GND
 
It is also a good idea to measure the actual voltage of the battery with a precision voltage meter, compare it with the calculated value from the autopilot (e.g. via [[Paparazzi_Center#Messages]]) and edit the vales for ADC scaling. Since the resistors have a tolerance, this can fine tune the measurement.


Ensure that the ground station is using the same protocol and an equal or higher baud rate:
=== Modules ===
{{Box Code|conf/control_panel.xml|
 
<nowiki>
The [[Modules|modules]] allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.
<session name="USB">
 
  <program name="link">
<source lang="xml">
    <arg flag="-d" constant="/dev/paparazzi/ttyUSB0"/>
<modules main_freq="60">
    <!-- <arg flag="-transport" constant="xbee"/> Comment this line for standard serial protocol -->
  <load name="demo_module.xml"/>
    <arg flag="-uplink" constant=""/>
  </modules>
    <arg flag="-s" constant="57600"/>
</source>
  </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 main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz
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|
{| class="wikitable"
<nowiki>
|-
<section name="MISC">
| Since '''v5.8''' it is possible to safely replace ''subsystem'' by ''module'' in your airframe file. It is therefore also possible to use the modules the same way subsystems used to be (i.e. as children of the ''firmware'' node and not only the ''modules'' node as presented above. The roadmap of Paparazzi is to convert existing subsystems to [[modules]].
    ...
|}
    <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>
{| class="wikitable"
|-
| Starting from '''v5.12''' the ''modules'' element will gradually be phased out. Instead, the modules should be added inside the ''firmware'' tags of the airframe file:
|}
<source lang="xml>
  <firmware name="fixedwing or rotorcraft">
    ...
    <module name="demo_module"/>
  </firmware>
</source>


{{Box Code|confAgain/airframes/myplane.xml - makefile section at the bottom|
Additional modules can also be added from the [[Flight Plans#Modules|flight plan]].
<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:
=== GCS ===
{{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|
[[Image:ac_icon_multi_uav.png|thumb|Various A/C icons demonstrated on a multi UAV simulation session]]
<nowiki>
<section name="MISC">
    ...
    <define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\""/>
<!--    <define name="NO_XBEE_API_INIT" value="TRUE"/> -->
    ...
</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...
[[Image:Icons_Theme_Default.png|thumb|Default Theme]]
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 ===
[[Image:Icons_Theme_Flat.png|thumb|Flat Theme]]
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:


Use this <b>optional</b> section to help customize parts of the GCS for a specific airframe:
{{Box Code|conf/airframes/myplane.xml|
{{Box Code|conf/airframes/myplane.xml|
<nowiki>ap.CFLAGS += -DGPS -DUBX -DUSE_UART1 -DGPS_LINK=Uart1 -DUART1_BAUD=B38400</nowiki>
<source lang="xml">
<nowiki>ap.srcs += gps_ubx.c gps.c</nowiki>
  <section name="GCS">
    ...
    <define name="ICONS_THEME" value="flat_theme"/>
    <define name="ALT_SHIFT_PLUS_PLUS" value="30"/>
    <define name="ALT_SHIFT_PLUS" value="5"/>
    <define name="ALT_SHIFT_MINUS" value="-5"/>
    <define name="SPEECH_NAME" value="Quad"/>
    <define name="AC_ICON" value="flyingwing"/>
  </section>
</source>
}}
}}
'''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]]


* <tt>ICONS_THEME</tt> can be used to define an alternate/custom GCS icons theme for a given aircraft The '''flat_theme''' is one example of an alternate set of GCS icons.
* <tt>ALT_SHIFT_PLUS_PLUS</tt> sets the number of metres the target altitude will change when the double up arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>ALT_SHIFT_PLUS</tt> sets the number of metres the target altitude will change when the up arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>ALT_SHIFT_MINUS</tt> sets the number of metres the target altitude will change when the down arrow button is pressed on the [[GCS#Strips|strip]]
* <tt>SPEECH_NAME</tt> a string ([a-zA-Z0-9_]) that will be used in place of the aircraft name specified in <tt>conf.xml</tt> for the [[Speech|speech]] and [[GCS#Alarms|alarms]] functionality. Set this to "_" to prevent the speech function from saying the aircraft name. Useful if your aircraft name takes a long time to say (i.e. "UAV1-A_with_spektrum" can be shortened to "Plane").
* <tt>AC_ICON</tt> can be used to define the vehicle icon (or overwrite the default icon) that shows up on the 2D-map of the GCS. Available values are: <tt>flyingwing</tt> , <tt>fixedwing</tt> , <tt>rotorcraft</tt> , <tt>quadrotor</tt> , <tt>hexarotor</tt> , <tt>octorotor</tt> , <tt>quadrotor_x</tt> , <tt>hexarotor_x</tt> , <tt>octorotor_x</tt> , <tt>home</tt>.
==== Custom Icons Theme Support ====


If using the u-blox LEA-5H, add the flag -DGPS_USE_LATLONG in the makefile section of the airframe xml file.
A custom icons theme is supported through the use of the '''ICONS_THEME''' attribute. Set the '''ICONS_THEME''' attribute ''value'' to the path of your custom icons theme directory and the given aircraft will now display your custom icons. Note that the path is relative to the default GCS icons path root: ''$PAPARAZZI_HOME/data/pictures/gcs_icons''


{{Box Code|conf/airframes/myplane.xml|
{{Box Code|code snippet|
<nowiki>ap.CFLAGS += -DGPS_USE_LATLONG</nowiki>
<source lang="xml">
  <section name="GCS">
      <define name="ICONS_THEME" value="myawesome_icons"/>
  </section>
</source>
}}
}}


=== Sensors ===
The directory that contains your custom icons, in this example named ''myawesome_icons'', is located at ''$PAPARAZZI_HOME/data/pictures/gcs_icons''.


=== 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 ==
[[Category:User_Documentation]] [[Category:Airframe_Configuration]]
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.

Latest revision as of 06:34, 24 September 2018

Airframe Configuration
Modules
Subsystems
Airframe Configuration
Autopilot generation
Fixedwing Configuration
Rotorcraft Configuration

About

The airframe file is the most important configuration file and contains all the hardware and software settings for your airframe. It describes what hardware you have and which firmware, sensors, algorithms, etc. you want to use and also holds your configuration parameters. All gains, trims, and behavior settings are defined with standard XML elements.

The XML airframe configuration file is located in conf/airframes/<yourairframe>.xml and always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line and should look like this

File: conf/airframes/<yourairframe>.xml 
<!DOCTYPE airframe SYSTEM "airframe.dtd">
<airframe name="yourairframe">
  <!-- The airframe configuration goes here. -->
</airframe>

Also see the wiki pages for fixedwing specific configuration and rotorcraft specific configuration.

Creating a new Aircraft

While the airframe file is where you configure most aspects of your aircraft, a fully specified aircraft needs several XML configuration files:

Each aircraft is assigned a name, unique ID and the associated configuration files in conf/conf.xml. To create a new Aircraft, click new in the menu A/C in the Paparazzi Center and select your new airframe file, etc. (or specify it by hand in conf/conf.xml).

Firmware and Hardware definitions

First you should specify which firmware you want to use, that is if you have a fixedwing aircraft or a rotorcraft:

File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
  </firmware>

Select your Board

To specify autopilot hardware you are using and it's low-level settings you have to add a target-tag. Each target has two attributes, which are name and a corresponding board attribute. The name attribute is either "ap" (autopilot) or "sim/jsbsim/nps" (simulation).


File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
    <target name="sim" board="pc"/> <!-- For simulation. -->
    <target name="ap"  board="lisa_m_1.0"/> <!-- Select your board here -->
     ...
  </firmware>

Simulation targets

target name="sim","jsbsim","nps"
board="pc"

More Information at Simulation.

Board targets

target name="ap"
board= "apogee_0.99", "apogee_1.0", "ardrone2", "booz_1.0", "classix", "hb_1.1", "krooz_sd", "lisa_l_1.0", "lisa_l_1.1", "lisa_m_1.0", "lisa_m_2.0", "lisa_mx_2.0", "lisa_s_0.1", "logom_2.6", "navgo_1.0", "sdlog_1.0", "stm32f4_discovery", "tiny_0.99", "tiny_1.1", "tiny_2.1", "tiny_2.11", "twog_1.0", "umarim_1.0", "umarim_lite_2.0", "yapa_2.0",

All targets can be found in /conf/boards.

Direct Makefile

Optionally you can also add a raw Makefile section. This is only needed in very advanced setups. For example when testing newly developed hardware.

LEDs

You can configure the LEDs on the autopilot to be used for different status indicators:

SYS_TIME_LED
blinks with 1Hz
AHRS_ALIGNER_LED
blinks until the AHRS is aligned (gyro bias initialized) and then stays on
GPS_LED
blinking if trying to get a fix, on if 3D fix
RADIO_CONTROL_LED
on if RC signal is ok
BARO_LED
only on booz and navgo boards: blinks until baro offset is initialized and then stays on

Depending on your board some of the LEDs on it are already assigned to some indicators by default, check the appropriate autopilot board makefile for the defaults.

To reconfigure the default assignment, assign the indicator to an other value. Use none if indicator should not be assigned to any LED.


File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
     <configure name="SYS_TIME_LED" value="1"/>
     <configure name="RADIO_CONTROL_LED" value="2"/>
     <configure name="GPS_LED" value="none"/>
  </firmware>

Beware that you can only assign one indicator to a LED number. So if the LED you want to use is already in use because another indicator is set to that number by default you have to disable that other indicator by setting it to none or reconfigure it to an other LED.

Subsystems

Since v5.8 it is possible to safely replace subsystem by module in your airframe file. The roadmap of Paparazzi is to convert existing subsystems to modules.

Each autopilot features certain subsystems which need to be configured properly. The most important ones are described below.

IMU

Add the imu subsystem with the type you are using.

File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
    <module name="imu"       type="aspirin_v1.5"/>
  </firmware>

See the imu subsystem page for more details. Also see the IMU calibration page.

AHRS

The AHRS subsystem specifies which attitude estimation filter you are using, e.g. for the complementary filter:

File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
    <module name="ahrs" type="int_cmpl_euler"/>
  </firmware>

All AHRS algorithms depend on an imu subsystem, except for the ahrs_infrared which depends on the infrared module. See the AHRS subsystem page for more details.

If the magnetometer should be used the local magnetic field section must be filled in.

Radio Control

Supported types are:

  • ppm
  • spektrum
  • sbus
  • datalink

Just specify the appropriate radio control subsystem in your firmware section, e.g.:

File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
    <module name="radio_control"     type="ppm"/>
  </firmware>

Telemetry (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 your telemetry file, e.g. conf/telemetry/default.xml. Those wishing to experiment with "alternative" modems can reduce the number and period of each telemetry message to fit within most any bandwidth constraint.

The telemetry subsystem 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.

Just specify the appropriate telemetry subsystem in your firmware section. You can currently choose between the types transparent, transparent_usb and xbee_api.

The default baudrate is 57600 baud, see the telemetry subsystem page for more details and configuration options.

File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
    <module name="telemetry"     type="transparent"/>
  </firmware>

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:

Just specify the appropriate gps subsystem in your firmware section. You can currently choose between the types ublox and ublox_utm for the older series 4 modules which still provide a UTM message.

File: conf/airframes/myplane.xml 
  <firmware name="fixedwing or rotorcraft">
     ...
    <module name="gps"               type="ublox"/>
  </firmware>

The correct UART is already defined by default according to your board. The default GPS baudrate is 38400baud.

If you need to set different baud rates or UART see the Subsystem/gps page for the options.

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 through the UART Tunnel and Configured with u-center

XML Parameters

When defining parameters you can use automatic unit conversion to conveniently set it in e.g. degrees.

Commands

The commands lists the abstract commands you need to control the aircraft. In a simple fixed-wing example, we have only three: 

 <commands>
  <axis name="THROTTLE" failsafe_value="0"/>
  <axis name="ROLL"     failsafe_value="0"/>
  <axis name="PITCH"    failsafe_value="0"/>
 </commands>

For rotorcraft, it is usually: 

 <commands>
  <axis name="PITCH"    failsafe_value="0"/>
  <axis name="ROLL"     failsafe_value="0"/>
  <axis name="YAW"      failsafe_value="0"/>
  <axis name="THRUST"   failsafe_value="0"/>
 </commands>

Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board. The range of these values is [-9600:9600]. For "THROTTLE", the range is [0, 9600] and in the corresponding servo definition the neutral and min are usually the same for PWM based servos (see below). 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 servos here. In the example below we use two elevons and a motor. (Elevons are surfaces used for both pitch and roll as on a flying wing.) These servos are listed in the servos section: 

 <servos>
  <servo name="THROTTLE"         no="0" min="1000" neutral="1000" max="2000"/>
  <servo name="ELEVON_LEFTSIDE"  no="1" min="2000" neutral="1500" max="1000"/>
  <servo name="ELEVON_RIGHTSIDE" no="2" min="1000" neutral="1500" max="2000"/>
 </servos>

Names are associated to the corresponding real physical connector to which a servo is connected on the autopilot board. For example no="2" means connector two on the board. Also the servo neutral value, total range and direction are defined. Min/max/neutral values are expressed in microseconds. The direction of travel can be reversed by exchanging min with max (as in "ELEVON_LEFTSIDE", above). The standard travel for a hobby servo is 1000µs - 2000µs with a 1500µs neutral. Trim can be added by changing this neutral value. Absolute servo travel limits can be increased or reduced with the min/max values. The "THROTTLE" servo typically has the same value for the neutral and min.

The attribute driver for servos node tells which actuators' driver is associated to the listed servos. After the version v4.9_devel-164-gdb0d004, multiple servos sections can be defined and used together, if the correct actuators subsystems are loaded. Some boards are automatically loading a default driver, the one used when no driver attribute is specified.

Note the following important tips:

  • Reverse the servo direction by exchanging min/max
  • Trim should always be adjusted mechanically if possible to avoid asymmetrical 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-2000µs range but experiment carefully as the servo may not operate reliably outside this range and may even suffer permanent damage.
  • Board connector numbering starts with zero (0) not with one
  • Servos are also known under the synonym actuators
  • (after version v4.9_devel-164-gdb0d004) For I2C based motor speed control using the motor mixing:
    • min: command to stop the motor
    • neutral: motor idle command
    • max: max thrust command

The servos are then linked to the commands in the command_laws section: 

 <command_laws>
  <let var="aileron"            value="@ROLL  * 0.3"/>
  <let var="elevator"           value="@PITCH * 0.7"/>  
  <set servo="THROTTLE"         value="@THROTTLE"/>
  <set servo="ELEVON_LEFTSIDE"  value="$elevator + $aileron"/>
  <set servo="ELEVON_RIGHTSIDE" value="$elevator - $aileron"/>
 </command_laws>
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. Elevon 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 let element. The @ symbol is used to reference a command value in the value attribute of the set and let 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.

After v4.9_devel-164-gdb0d004, the command_laws section is mandatory for both fixedwing and rotorcraft firmwares, only for fixedwing otherwise.

Battery

This section gives characteristics for monitoring the main power battery.

MILLIAMP_AT_FULL_THROTTLE represents the actual current (in mA) when full THROTTLE is applied. Note that when flying the current typically is significantly lower than in static tests at home on your workbench. MILLIAMP_AT_FULL_THROTTLE is used to compute the energy value of the BAT message when no Current sensor is mounted in the airframe. This value can also be used in flight plans. For example, if at full throttle your motor consumes 10 Amps, use a value of 10000. You can "tweak" this number after a few flights to match the capacity of your battery. If upon landing your bat.energy messages says that you used 2500 mAh while the energy recharged into the battery is only 2000 mAh, you could reduce the MILLIAMP_AT_FULL_THROTTLE value by 20% to match your in-flight current consumption. This tweaking is most precise if you fly full throttle only (respectively no throttle to glide down again).

The CURRENT_ESTIMATION_NONLINEARITY can be added to tweak the energy estimation for non full throttle cruise. As the current consumption is nonlinear, at 50% throttle it is likely to be substantially less than 50%. A superellipse is used to approximate this nonlinearity. The default setting is 1.2 and is used if the CURRENT_ESTIMATION_NONLINEARITY is not defined in your airframe file. A value 1 corresponds to linear behaviour, 1.5 corresponds to strong nonlinearity. The tweaking is done same as described above for MILLIAMP_AT_FULL_THROTTLE, but only partial throttle (cruise throttle) should be applied in flight.

If both MILLIAMP_AT_FULL_THROTTLE and CURRENT_ESTIMATION_NONLINEARITY are tweaked well, you get precise energy estimations with less than 5% error independent of your flight pattern without even requiring a current sensor.

The CATASTROPHIC_BAT_LEVEL (was previously LOW_BATTERY) 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). CRITIC and LOW 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 MAX_BAT_LEVEL may be specified to improve the display of the battery gauge in the strip or in "papgets". Note that this definition is optional, with a default value of 12.5V.


File: conf/airframes/myplane.xml 
  <firmware name="fixedwing">
    ...
    <define name="ADC_CHANNEL_VSUPPLY" value="ADC_4" /> 
  </firmware>
  ...
  <section name="BAT">
    <define name="MILLIAMP_AT_FULL_THROTTLE" value="12000" unit="mA" />
    <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>

The conversion of ADC measurements to Voltage is already defined for the different autopilot boards, if you need to override these defaults you can use the VoltageOfAdc(adc) define and also specify offsets or anything else you might need, e.g.:


File: conf/airframes/myplane.xml 
  <section name="BAT">
    ...
    <define name="VOLTAGE_ADC_SCALE" value="0.0177531"/>
    <define name="VOLTAGE_OFFSET" value="0.5" unit="V"/>
    <define name="VoltageOfAdc(adc)" value="(VOLTAGE_ADC_SCALE * adc + VOLTAGE_OFFSET)"/>
  </section>

Calculating VOLTAGE_ADC_SCALE:

  • Vref - Voltage reference for the ADC (will be 3.3V in most cases, can be found in mcu/adc datasheet)
  • ADCresolution - ADC bit depth (e.g. 2^12=4096 for a 12 bit ADC)
  • R1 - Resistor between battery and ADC input pin of MCU
  • R2 - Resistor between ADC input pin of the MCU and GND

It is also a good idea to measure the actual voltage of the battery with a precision voltage meter, compare it with the calculated value from the autopilot (e.g. via Paparazzi_Center#Messages) and edit the vales for ADC scaling. Since the resistors have a tolerance, this can fine tune the measurement.

Modules

The modules allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop. 

 <modules main_freq="60">
  <load name="demo_module.xml"/>
 </modules>
  • The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz
Since v5.8 it is possible to safely replace subsystem by module in your airframe file. It is therefore also possible to use the modules the same way subsystems used to be (i.e. as children of the firmware node and not only the modules node as presented above. The roadmap of Paparazzi is to convert existing subsystems to modules.
Starting from v5.12 the modules element will gradually be phased out. Instead, the modules should be added inside the firmware tags of the airframe file: 
  <firmware name="fixedwing or rotorcraft">
     ...
    <module name="demo_module"/>
  </firmware>

Additional modules can also be added from the flight plan.

GCS

Various A/C icons demonstrated on a multi UAV simulation session
Default Theme
Flat Theme

Use this optional section to help customize parts of the GCS for a specific airframe:

File: conf/airframes/myplane.xml 
  <section name="GCS">
    ...
    <define name="ICONS_THEME" value="flat_theme"/>
    <define name="ALT_SHIFT_PLUS_PLUS" value="30"/>
    <define name="ALT_SHIFT_PLUS" value="5"/>
    <define name="ALT_SHIFT_MINUS" value="-5"/>
    <define name="SPEECH_NAME" value="Quad"/>
    <define name="AC_ICON" value="flyingwing"/>
  </section>
  • ICONS_THEME can be used to define an alternate/custom GCS icons theme for a given aircraft The flat_theme is one example of an alternate set of GCS icons.
  • ALT_SHIFT_PLUS_PLUS sets the number of metres the target altitude will change when the double up arrow button is pressed on the strip
  • ALT_SHIFT_PLUS sets the number of metres the target altitude will change when the up arrow button is pressed on the strip
  • ALT_SHIFT_MINUS sets the number of metres the target altitude will change when the down arrow button is pressed on the strip
  • SPEECH_NAME a string ([a-zA-Z0-9_]) that will be used in place of the aircraft name specified in conf.xml for the speech and alarms functionality. Set this to "_" to prevent the speech function from saying the aircraft name. Useful if your aircraft name takes a long time to say (i.e. "UAV1-A_with_spektrum" can be shortened to "Plane").
  • AC_ICON can be used to define the vehicle icon (or overwrite the default icon) that shows up on the 2D-map of the GCS. Available values are: flyingwing , fixedwing , rotorcraft , quadrotor , hexarotor , octorotor , quadrotor_x , hexarotor_x , octorotor_x , home.

Custom Icons Theme Support

A custom icons theme is supported through the use of the ICONS_THEME attribute. Set the ICONS_THEME attribute value to the path of your custom icons theme directory and the given aircraft will now display your custom icons. Note that the path is relative to the default GCS icons path root: $PAPARAZZI_HOME/data/pictures/gcs_icons


File: code snippet 
  <section name="GCS">
      <define name="ICONS_THEME" value="myawesome_icons"/>
  </section>

The directory that contains your custom icons, in this example named myawesome_icons, is located at $PAPARAZZI_HOME/data/pictures/gcs_icons.

Retrieved from "http://wiki.paparazziuav.org/w/index.php?title=Airframe_Configuration&oldid=24115"