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

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 some of the 4 coeff values. Some trial and error is usually needed to get the directions correct.

Note that the roll angle is positive when the right wing low while pitch is positive when the nose is up.

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

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

File: conf/airframes/myplane.xml

<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

File: conf/airframes/myplane.xml

ap.CFLAGS += -DRADIO_CONTROL -DRADIO_CONTROL_TYPE=RC_FUTABA 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

You can set RADIO_CONTROL_TYPE to RC_FUTABA, for falling edge PPM, or RC_JR for rising edge PPM.

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

Paparazzi supports the following modem protocols:

• Standard transparent serial (pprz) - this is compatible with all modems and can be used to connect the autopilot directly to a PC for testing without a modem.
• Maxstream API protocol (xbee) - compatible with all Maxstream modems including the 9XTend and Zigbee. This protocol enables hardware addressing, allowing multiple aircraft to be managed from a single ground modem.
• Coronis Wavecard - necessary for operation with the unusual Coronis Wavecard modem.

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

Configuring The Serial Protocol

Users are advised to start with the standard serial protocol before attempting to setup an addressed API link. 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.

File: conf/airframes/myplane.xml

<section name="DATALINK" prefix="DATALINK_"> <define name="DEVICE_TYPE" value="PPRZ"/> <define name="DEVICE_ADDRESS" value="...."/> </section>

The above example tells the autopilot to send and recieve data in standard serial form.

File: conf/airframes/myplane.xml - makefile section at the bottom

# 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=B57600 ap.srcs += downlink.c $(SRC_ARCH)/uart_hw.c datalink.c pprz_transport.c

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

• The autopilot and modem serial port baud rates must match at all times, check your modem documentation to find the default baud rate and configure a different rate as needed.

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"/> Comment this line for standard serial protocol --> <arg flag="-uplink" constant=""/> <arg flag="-s" constant="57600"/> </program> ... </session>

Configuring The Maxstream API Protocol

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

File: conf/airframes/myplane.xml

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

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 <define name="NO_XBEE_API_INIT" value="TRUE"/>, 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.
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 <define name="NO_XBEE_API_INIT" value="TRUE"/> .
• 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.
• For temporary boot-time API configuration remove any baud rate changes, remove ATWR\r 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.

File: conf/airframes/myplane.xml - makefile section at the bottom

# 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

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.

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

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:

File: conf/airframes/myplane.xml

ap.CFLAGS += -DGPS -DUBX -DUSE_UART1 -DGPS_LINK=Uart1 -DUART1_BAUD=B38400 ap.srcs += gps_ubx.c gps.c

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 UART Tunnel and u-center

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:

File: conf/airframes/myplane.xml

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.