Airframe Configuration

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

Selecting the Airframe File

Each airframe file must be assigned a name, unique ID, flight plan, etc. in conf/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 select the appropriate A/C and target in the Paparazzi Center or 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 abstract 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]. 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 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.

Manual

The rc_command sections links the channels of the RC transmitter (defined in the Radio Control file) to the commands defined above:

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

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

Auto1

The next section, named 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.

<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 makefile section. For the previous example, we would have to write:

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

Infrared

The INFRARED section describes the configuration of the infrared sensors.

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

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

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

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

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

Then, define the orientation of the horizontal sensor, TILTED or ALIGNED:

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

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

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

Default values are 1.

It may be hard to align the horizontal sensor with the aircraft. A tuning in flight will be needed to adjust the following neutrals. Adjust the roll neutral to fly straight. Adjust the pitch neutral to fly level with the desired throttle.

  <define name="ROLL_NEUTRAL_DEFAULT" value="-2.5" unit="deg"/>
  <define name="PITCH_NEUTRAL_DEFAULT" value="6" unit="deg"/>

Finally, an asymmetric (left/right, front/rear) correction can be added with a last set of factors.

  <define name="CORRECTION_UP" value="1."/>
  <define name="CORRECTION_DOWN" value="1."/>
  <define name="CORRECTION_LEFT" value="1."/>
  <define name="CORRECTION_RIGHT" value="1."/>
</section>

These corrections are set on the angles.

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 give characteristics for the monitoring of the main power battery. MILLIAMP_PER_PERCENT represents the consumption (in mA) for one percent of THROTTLE and for one time unit. It is used to compute the energy value of the BAT message.

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. This definition is optional with a default value of 12.5V.

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

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

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

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

Vertical Control

  <section name="VERTICAL CONTROL" prefix="V_CTL_">
   <define name="ALTITUDE_PGAIN" value="-0.065"/>
   <define name="ALTITUDE_MAX_CLIMB" value="3."/>

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. 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"/>
   <define name="AUTO_THROTTLE_MIN_CRUISE_THROTTLE" value=".4"/>
   <define name="AUTO_THROTTLE_MAX_CRUISE_THROTTLE" value="1"/>
   <define name="AUTO_THROTTLE_LOITER_TRIM" value="1000"/>
   <define name="AUTO_THROTTLE_DASH_TRIM" value="-2500"/>
   <define name="AUTO_THROTTLE_CLIMB_THROTTLE_INCREMENT" value="0.15" unit="%/(m/s)"/>
   <define name="AUTO_THROTTLE_PGAIN" value="-0.008"/>
   <define name="AUTO_THROTTLE_IGAIN" value="0.25"/>
   <define name="AUTO_THROTTLE_PITCH_OF_VZ_PGAIN" value="0.35"/>

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

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

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

  <define name="THROTTLE_SLEW_LIMITER" value="2" unit="s"/>

THROTTLE_SLEW_LIMITER is the required time is seconds to change throttle from 0% to 100%.

 </section>

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.

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.

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

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

Modem

The modem protocol and baud rate must be set in both the airframe file and ground station. Any standard baud rate can be used, with 9600 being adequate and 57600 recommended for most users to allow high speed telemetry for more detailed flight data analysis. The actual data rate is determined by the number of messages being sent and the period of each message as defined in 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.