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

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:

• Airframe (what this page is about)
• Flight Plan
• Settings
• Radio (if you use a PPM based R/C system)
• Telemetry

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, i.e. if you have a fixedwing aircraft or a rotorcraft:

File: conf/airframes/myplane.xml

<firmware name="fixedwing"> ... </firmware>

Select your Board

To specify autopilot hardware you are using and it's low-level settings you have to add a target "ap" (autopilot) with board attribute.

Select the appropriate hardware autopilot board you are going to use in your airframe: "twog_1.0", "tiny_0.99", "tiny_1.1", "tiny_2.1", "tiny_2.11", "booz_1.0", "lisa_l_1.0", "lisa_l_1.1", "lisa_m_1.0", "lisa_s_1.0", "pc"

File: conf/airframes/myplane.xml

<firmware name="fixedwing"> <target name="sim" board="pc"/> <target name="ap" board="tiny_2.11"/> ... </firmware>

Note that the "pc" is a special kind of "board", and is mostly used only for simulation flights of an autopilot via your computer.

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.

Radio Control

The Paparazzi autopilot can interface 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.

Proper Spektrum support is on the way.

Just specify the appropriate subsystem in your firmware section:

File: conf/airframes/myplane.xml

<firmware name="fixedwing or rotorcraft"> ... <subsystem name="radio_control" type="ppm"/> </firmware>

Obsolete Classix Autopilot

If you have a Classix Autopilot:

File: conf/airframes/myplane.xml

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

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

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.

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.

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

File: conf/airframes/myplane.xml

<firmware name="fixedwing or rotorcraft"> ... <subsystem name="telemetry" type="transparent"/> </firmware>

The correct UART is already defined by default according to your board. The default modem baudrate is 57600baud.

If you use different baud rate or Uart set the according parameters, e.g.

File: conf/airframes/myplane.xml

<firmware name="fixedwing or rotorcraft"> ... <subsystem name="telemetry" type="transparent"> <configure name="MODEM_BAUD" value="B9600"/> <configure name="MODEM_PORT" value="UART1"/> </subsystem> </firmware>

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 UAS there is no disadvantage and that the 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.

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 receive data in standard serial form.

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\""/> ... </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 by adding the line <define name="NO_XBEE_API_INIT" value="TRUE"/> (the parameter "value" has no effect), update the baud rate as needed, and re-flash the autopilot. The modem and autopilot serial port baud rates must match each other 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.
• Upgrade your Maxstream firmware to the latest version before attempting API mode operation.

Alternate Method

This is the way it is done in funjet1.xml and has been tested to work by Danstah

File: conf/airframes/funjet1.xml

<section name="MISC"> ... <define name="XBEE_INIT" value="\"ATPL2\rATRN1\rATTT80\r\""/> <!-- <define name="NO_XBEE_API_INIT" value="TRUE"/> --> ... </section>

Also use this

File: conf/airframes/funjet1.xml

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

Keep in mind that the ground modem baud rate and aircraft modem baud rate do not have to match. What does need to match however is the baud rate of your modem build into the aircraft and the rate defined in the airframe file. For example if this aircraft modem is set to 9600Baud, this modem can connect with a ground modem configured set to 57600Baud. Also for multiple UAS, a good way to configure them is to use 9600Baud for the Autopilot board and use a ground modem configured to 57600Baud. After your aircrafts are working well, set your configuration to use minimal telemetry.

Set GCS baud rate

Set can set the baudrate for the link in the GCS by specifying -s 57600 as a parameter to link. Then just save your session so you won't have to change it again next time.

You can also manually write a session:

File: conf/control_panel.xml

<session name="USB"> <program name="link"> <arg flag="-d" constant="/dev/ttyUSB0"/> <!--<arg flag="-transport" constant="xbee"/>--><!-- uncomment this line for XBee API mode --> <arg flag="-s" constant="57600"/> </program> ... </session>

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. Setting Udev rules

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 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"> ... <subsystem name="gps" type="ublox"/> </firmware>

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

If you use different baud rates or UART set the according parameters, e.g.

File: conf/airframes/myplane.xml

<firmware name="fixedwing or rotorcraft"> ... <subsystem name="gps" type="ublox"> <configure name="GPS_BAUD" value="B9600"/> <configure name="GPS_PORT" value="UART0"/> </subsystem> </firmware>

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

XML Parameters

Bat

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

<section name="BAT">
 <define name="MILLIAMP_AT_FULL_THROTTLE" value="12000" unit="mA" />
 <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>

Find more in depth information on how to get a separate current sensor working by clicking here

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