Airframe Configuration

The airframe configuration 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.

Selecting the Airframe File

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

More information can be found on the conf.xml page

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>

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

The modem protocol and baud rate must be set in both the airframe file and ground station. Any standard baud rate can be used, 9600 is adequate for most applications and 57600 will 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 conf/telemetry/default.xml. 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.

Select the baud/protocol in the airframe file by commenting/uncommenting the appropriate section as follows:

File: conf/airframes/myplane.xml

Maxstream API protocol ap.CFLAGS += -DDOWNLINK -DUSE_UART0 -DDOWNLINK_TRANSPORT=XBeeTransport -DDOWNLINK_FBW_DEVICE=Uart0 -DDOWNLINK_AP_DEVICE=Uart0 -DXBEE_UART=Uart0 -DDATALINK=XBEE -DUART0_BAUD=B57600 ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c xbee.c Serial modem ap.CFLAGS += -DDOWNLINK -DUSE_UART0 -DDOWNLINK_TRANSPORT=PprzTransport -DDOWNLINK_FBW_DEVICE=Uart0 -DDOWNLINK_AP_DEVICE=Uart0 -DPPRZ_UART=Uart0 -DDATALINK=PPRZ -DUART0_BAUD=B9600 ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c pprz_transport.c

The above example has the Maxstream protocol disabled and standard serial (PPRZ) enabled at 9600 baud.
Maxstream API mode must be enabled either permanently or upon each boot with the following variables:

File: conf/airframes/myplane.xml

<section name="MISC"> ... <define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\ATBD3\rATWR\r\""/> <define name="NO_XBEE_API_INIT" value="FALSE"/> ... </section>

The above example will program the Maxstream to power level 2 (ATPL), API mode, 9600 baud (ATBD3), and permanently store the changes (ATWR). After flashing, power cycle the autopilot to send the commands to the modem, then disable the init string <define name="NO_XBEE_API_INIT" value="TRUE"/> and re-flash the autopilot. Note that the ac_id defined in conf/conf.xml is permanently programmed into the modem so this procedure would need to be re-run if the modem is moved to another plane.
Ensure that the ground station is using the same protocol and an equal or higher baud rate:

File: conf/control_panel.xml

<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="9600"/> </program> ... </session>

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

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