Airframe Configuration

File Structure

The airframe file is located in conf/airframes/ and contains all the hardware and software settings for a particular aircraft. This is a hybrid file containing xml in the first half with C Makefile code at the bottom. All gains, trims, and behavior settings are in the top XML section and the hardware definitions such as processor type, modem protocol, servo driver, etc. are contained in the makefile.
Each airframe file must be assigned a name, unique ID, flight plan, etc. in conf/conf.xml 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 specify your airframe name in the flash command typed from the prompt:

make AIRCRAFT=Twin1 upload.ac

XML Parameters

Commands

The commands lists the servo commands you need to control the aircraft. In our 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>

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

Servos

The above commands get translated to the servos 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 servos section:

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

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 "AILEVON_LEFT", 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 "THROTTLE" servo typically has the same value for the neutral and min. 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 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="AILEVON_LEFT"  value="$elevator + $aileron"/>
 <set servo="AILEVON_RIGHT" value="$elevator - $aileron"/>
</command_laws>

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

Auto1

The next section, named AUTO1, gives the maximum roll and pitch (in radians) allowed for the augmented stability mode.

<section name="AUTO1" prefix="AUTO1_">
 <define name="MAX_ROLL" value="RadOfDeg(35)"/>
 <define name="MAX_PITCH" value="RadOfDeg(35)"/>
</section>

ADC

In the "adc" section, you will find the correspondance between arguments and their assigned pins on the autopilot board.

Infrared

The INFRARED section describes the configuration of the infrared sensors. It is necessary to calibrate them in order to obtain the neutral values. As the X-Y sensor pairs are usually installed with a 45 degree rotation, combining roll and pitch we have a formula to separate roll from pitch and adjust the output accordingly:

<linear name="RollOfIrs" arity="2" coeff1="-0.7" coeff2="0.7"/>
<linear name="PitchOfIrs" arity="2" coeff1="-0.7" coeff2="-0.7"/>

Pitch and roll directions are defined here with the "-" sign on each of the 4 coeff values. Some trial and error is usually needed to get the directions correct.

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.(ADC_TEMP_SLOPE=0).

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

Bat

This section for the monitoring the main power battery. The allowed voltage range for this aircraft is 9-12.5V. MILLIAMP_PER_PERCENT represents the consumption (in mA) for one percent of THROTTLE and for one time unit. The LOW_BATTERY value defines the voltage at which the autopilot will lock the throttle at 0% in autonomous mode.

<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="LOW_BATTERY" value"9.3" unit="V"/>
</section>

Horizontal Control

<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_PGAIN" value="5000."/>
   <define name="AILERON_OF_THROTTLE" value="0.0"/>
   <define name="PITCH_PGAIN" value="-8000."/>
   <define name="ELEVATOR_OF_ROLL" value="1250"/>
 </section>

The outer loop acts on the route. It will produce a roll command from a course setpoint and a course measurment. The COURSE_PGAIN parameter

Misc

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

• 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 the makefile section starting with the autopilot model and flashing mode:

<makefile>
 include $(PAPARAZZI_SRC)/conf/autopilot/tiny.makefile
 FLASH_MODE=IAP
 .
 .
 .
</makefile>

Below this are the definintions and configuration of the peripherals and interfaces.

R/C

 ap.CFLAGS += -DRADIO_CONTROL
 ap.EXTRA_SRCS += radio_control.c $(SRC_ARCH)/ppm_hw.c
 ap.CFLAGS += -DACTUATORS=\"servos_direct_hw.h\"
 ap.EXTRA_SRCS += $(SRC_ARCH)/servos_direct_hw.c

Modem

 ap.CFLAGS += -DTRACES=uart0
 ap.EXTRA_SRCS += r$(SRC_ARCH)/traces.c $(SRC_ARCH)/uart_ap.c

Control loops

The control loops can be divided in two largely independant 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:

ap.srcs += fw_h_ctl.c