Difference between revisions of "Airframe Configuration"

From PaparazziUAV
Jump to navigation Jump to search
m
(started cleaning the airframe configuration page up, only configuration that applies to both fw and rotor firmware, still needs a lot more love)
Line 3: Line 3:


The airframe configuration file is located in <tt>conf/airframes</tt>.
The airframe configuration file is located in <tt>conf/airframes</tt>.
<b>Also see the wiki pages for [[Fixedwing_Configuration|fixedwing specific configuration]] and [[Rotorcraft_Configuration|rotorcraft specific configuration]].</b>


== Selecting the Airframe File ==
== Selecting the Airframe File ==
Line 34: Line 36:


Note that the airframe XML document always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line.
Note that the airframe XML document always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line.
== XML Parameters ==
=== Commands ===
The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. In our example, we have only three:
<tt>
<commands>
  <axis name="THROTTLE" failsafe_value="0"/>
  <axis name="ROLL"    failsafe_value="0"/>
  <axis name="PITCH"    failsafe_value="0"/>
</commands></tt>
Each command is also associated with a failsafe value which will be used if no controller is active, for example during initialization of the autopilot board. The range of these values is [-9600:9600]. For <tt>"THROTTLE"</tt>, the range is [0, 9600] and in the corresponding <b><tt>servo</tt></b> definition the <b><tt>neutral</tt></b> and <b><tt>min</tt></b> are usually the same (see below). Note that these commands do not necessarily match the servo actuators. For example, the <tt>"ROLL"</tt> command is typically linked to two aileron actuators.
=== Servos ===
The above commands get translated to the <b><tt>servos</tt></b> here. In the example below we use two elevons and a motor. ([http://en.wikipedia.org/wiki/Elevon ''Elevons''] are surfaces used for both pitch and roll as on a flying wing.) These servos are listed in the <b><tt>servos</tt></b> section:
<tt>
<servos>
  <servo name="THROTTLE"        no="0" min="1000" neutral="1000" max="2000"/>
  <servo name="ELEVON_LEFTSIDE"  no="1" min="2000" neutral="1500" max="1000"/>
  <servo name="ELEVON_RIGHTSIDE" no="2" min="1000" neutral="1500" max="2000"/>
</servos></tt>
Names are associated to the corresponding '''real physical connector''' to which a servo is connected '''on the autopilot board'''. For example no="2" means connector two on the board. Also the servo neutral value, total range and direction are defined.  Min/max/neutral values are expressed in milliseconds. The direction of travel can be reversed by exchanging min with max (as in <tt>"ELEVON_LEFTSIDE"</tt>, above).  The ''standard'' travel for a hobby servo is 1000ms - 2000ms with a 1500ms neutral. Trim can be added by changing this neutral value. Absolute servo travel limits can be increased or reduced with the min/max values.  The <tt>"THROTTLE"</tt> servo typically has the same value for the <b><tt>neutral</tt></b> and <b><tt>min</tt></b>. 
Note the following important tips:
* Reverse the servo direction by exchanging min/max
* Trim should always be adjusted mechanically if possible to avoid asymmetrical 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.
* Board connector numbering starts with <b>zero (0)</b> not with one
* Servos are also known under the synonym <b>actuators</b>
The <b><tt>servos</tt></b> are then linked to the commands in the <b><tt>command_laws</tt></b> section:
<tt>
<command_laws>
  <let var="aileron"            value="@ROLL  * 0.3"/>
  <let var="elevator"          value="@PITCH * 0.7"/> 
  <set servo="THROTTLE"        value="@THROTTLE"/>
  <set servo="ELEVON_LEFTSIDE"  value="$elevator + $aileron"/>
  <set servo="ELEVON_RIGHTSIDE" value="$elevator - $aileron"/>
</command_laws></tt>
[[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.  Elevon 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 <b><tt>let</tt></b> element.  The '''@''' symbol is used to reference a command value in the <b><tt>value</tt></b> attribute of the <b><tt>set</tt></b> and <b><tt>let</tt></b> 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 <tt>rc_command</tt> sections links the channels of the RC transmitter (defined in the [[Radio_Control|Radio Control]] file) to the <tt>commands</tt> 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.
=== RC commands in Auto ===
To control servos or other servo signal compatible devices by RC in Auto1 or Auto2, define them in the <auto_rc_commands> section.
If you have an airframe with a dedicated rudder (YAW channel) then it is still controllable in auto mode via RC. This is the default behavior and is equivalent to setting the YAW command in auto_rc_commands:
<auto_rc_commands>
  <set command="YAW" value="@YAW"/>
</auto_rc_commands>
To disable this behavior (meaning no RC control of the rudder in auto) define an empty auto_rc_commands section:
<auto_rc_commands>
</auto_rc_commands>
=== Autopilot Only Commands ===
For certain missions it might be required to control servos (payload) from the autopilot (gcs) at all times (even during manual flight). These commands should not be in the <rc_commands> block but in the special <ap_only_commands> block. This allows for instance the pantilt operator to keep working when in manual flight, or safety logic to automatically close cameras below a certain altitude during manual landings.
<ap_only_commands>
  <copy command="PAN"/>
  <copy command="TILT"/>
  <copy command="SHOOT"/>
</ap_only_commands>
=== Auto1 ===
The next section, named <b><tt>AUTO1</tt></b>, gives the maximum roll and pitch (in radians) allowed for the augmented stability mode.
<tt>
<section name="AUTO1" prefix="AUTO1_">
  <define name="MAX_ROLL" value="RadOfDeg(35)"/>
  <define name="MAX_PITCH" value="RadOfDeg(35)"/>
</section>
</tt>
<br>
=== ADC Generic ===
If you want to receive the value of some ADC channel, you can use the "ADC Generic" [[Modules|module]]. When activated, the aircraft sends 2 values corresponding to the selected ADC channels. They can be read from the "Messages" application.
Add the adc_generic to your modules:
<pre>
  <modules>
    ...
    <load name="adc_generic.xml">
      <configure name="ADC_CHANNEL_GENERIC1" value="ADC_3"/>
      <configure name="ADC_CHANNEL_GENERIC2" value="ADC_4"/>
    </load>
  </modules>
</pre>
In this example, the ADC channels 3 and 4 are read and sent by telemetry at 4Hz:
  <message name="ADC_GENERIC" ID="18">
    <field name="val1" type="uint16"/>
    <field name="val2" type="uint16"/>
  </message>
Only one or two channels can be defined. If only one is activated, 0 will be sent for the unused value.
=== Infrared ===
The <b><tt>INFRARED</tt></b> 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="IR1_SIGN" value="-1"/>
  <define name="IR2_SIGN" value="-1"/>
  <define name="TOP_SIGN" value="-1"/>
Then, define how the horizontal sensor is connected to the airframe, orientation '''aligned''' or '''tilted'''. In the aligned case, ir'''1''' is along the lateral axis (The axis that passes through the plane from wingtip to wingtip) and ir'''2''' along the longitudinal one. In the '''tilted''' case, the sensors are tilted by 45 degrees; ir'''1''' is along rear-left -- front-right, and ir'''2''' along rear-right -- front-left. The parameter "value" in the aligned and tilted definition has no effect! If the airframe construction allows choose an aligned sensor orientation since this gives the best stabilization response results.
For help with orientation of '''Previous Versions of Infrared Sensor Boards''' try here : http://paparazzi.enac.fr/wiki/Previous_Infrared_Sensors
  <define name="HORIZ_SENSOR_ALIGNED" value="1"/>
  or
  <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"/>
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.
You don't have to set these as they are set to 1. per default, but adjust them if needed.
=== 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.(<b><tt>ADC_TEMP_SLOPE=0</tt></b>).
<tt>
<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>
</tt>
=== Bat ===
This section gives characteristics for monitoring the main power battery.
<b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> 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. <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message when no [[Current_sensor|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 <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> 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 <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> 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 <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> 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 <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b>, but only partial throttle (cruise throttle) should be applied in flight.
If both <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> and <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> are tweaked well, you get precise energy estimations with less than 5% error independant of your flight pattern without even requiring a [[Current_sensor|Current sensor]].
The <b><tt>CATASTROPHIC_BAT_LEVEL</tt></b> (was previously <b><tt>LOW_BATTERY</tt></b>) 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).  <b><tt>CRITIC</tt></b> and <b><tt>LOW</tt></b> 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 <b><tt>MAX_BAT_LEVEL</tt></b> 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.
<tt>
<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>
</tt>
Find more in depth information on how to [[Current_sensor|get a separate current sensor working by clicking here]]
=== Horizontal Control ===
<tt>
<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>
</tt>
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.
The [[Control_Loops#Fixed-wing_autopilot|graphical representation of the control loops]] can help you to visualize the effect of each gain.
===Vertical Control===
  <section name="VERTICAL CONTROL" prefix="V_CTL_">
    <!-- outer loop proportional gain -->
    <define name="ALTITUDE_PGAIN" value="-0.1" unit="(m/s)/m"/>
    <!-- outer loop saturation -->
    <define name="ALTITUDE_MAX_CLIMB" value="3." unit="m/s"/>
These lines are associated with vertical control loops contained in sw/airborne/firmwares/fixedwing/guidance/guidance_v.c.  These are outer loop parameters that calculate a desired climb rate based on altitude error. Here, if the altitude error is 10m, the climb setpoint will be set to 1m/s. 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" unit="%"/>
    <define name="AUTO_THROTTLE_MIN_CRUISE_THROTTLE" value=".4" unit="%"/>
    <define name="AUTO_THROTTLE_MAX_CRUISE_THROTTLE" value="1" unit="%"/>
    <define name="AUTO_THROTTLE_LOITER_TRIM" value="1000" unit="pprz_t"/>
    <define name="AUTO_THROTTLE_DASH_TRIM" value="-2500" unit="pprz_t"/>
    <define name="AUTO_THROTTLE_CLIMB_THROTTLE_INCREMENT" value="0.15" unit="%/(m/s)"/>
    <define name="AUTO_THROTTLE_PGAIN" value="-0.008" unit="%/(m/s)"/>
    <define name="AUTO_THROTTLE_IGAIN" value="0.25"/>
    <define name="AUTO_THROTTLE_PITCH_OF_VZ_PGAIN" value="0.35" unit="rad/(m/s)"/>
These lines are associated with vertical rate control loops contained in sw/airborne/firmwares/fixedwing/guidance/guidance_v.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/firmwares/fixedwing/guidance/guidance_v.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%.
The [[Control_Loops#Fixed-wing_autopilot|graphical representation of the control loops]] can help you to visualize the effect of each gain.
=== Misc ===
<tt>
<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>
</tt>
* 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).
=== Simu ===
Values from this section can be used to tweak the software in the loop (SITL) simulation.
<tt>
<section name="SIMU">
  <define name="WEIGHT" value ="1."/>
  <define name="YAW_RESPONSE_FACTOR" value ="1."/>
  <define name="ROLL_RESPONSE_FACTOR" value ="15."/>
</section>
</tt>
* "YAW_RESPONSE_FACTOR" adapts the aircraft's turn rate corresponding to a bank angle; a larger value increases the turn radius
* "ROLL_RESPONSE_FACTOR" is basically your aileron efficiency; a higher value increases roll agility
If you want to use JSBSim as SITL simulator, you have to make some definitions in this section as well; see [[Simulation#JSBSim|here]].
=== Modules ===
The [[Modules|modules]] allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.
<tt>
<modules main_freq="60">
  <load name="demo_module.xml"/>
</modules>
</tt>
* The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz


== Firmware and Hardware definitions ==
== Firmware and Hardware definitions ==
Line 341: Line 51:
     <target name="sim" board="pc"/>
     <target name="sim" board="pc"/>
     <target name="ap" board="tiny_2.11"/>
     <target name="ap" board="tiny_2.11"/>
     .
     ...
    .
    .
   </firmware>
   </firmware>
</pre>
</pre>
Line 361: Line 69:
{{Box Code|conf/airframes/myplane.xml|
{{Box Code|conf/airframes/myplane.xml|
<pre>
<pre>
   <firmware name="fixedwing">
   <firmware name="fixedwing or rotorcraft">
    <target name="sim" board="pc"/>
     ...
    <target name="ap" board="tiny_2.11"/>
     .
    .
    .
     <subsystem name="radio_control"    type="ppm"/>
     <subsystem name="radio_control"    type="ppm"/>
   </firmware>
   </firmware>
Line 402: Line 106:
{{Box Code|conf/airframes/myplane.xml|
{{Box Code|conf/airframes/myplane.xml|
<pre>
<pre>
   <firmware name="fixedwing">
   <firmware name="fixedwing or rotorcraft">
    <target name="ap" board="tiny_2.11"/>
     ...
     .
    .
    .
     <subsystem name="telemetry"    type="transparent"/>
     <subsystem name="telemetry"    type="transparent"/>
   </firmware>
   </firmware>
Line 418: Line 119:
{{Box Code|conf/airframes/myplane.xml|
{{Box Code|conf/airframes/myplane.xml|
<pre>
<pre>
   <firmware name="fixedwing">
   <firmware name="fixedwing or rotorcraft">
    <target name="ap" board="tiny_2.11"/>
     ...
     .
    .
    .
     <subsystem name="telemetry"    type="transparent">
     <subsystem name="telemetry"    type="transparent">
       <configure name="MODEM_BAUD"          value="B9600"/>
       <configure name="MODEM_BAUD"          value="B9600"/>
Line 515: Line 213:
{{Box Code|conf/airframes/myplane.xml|
{{Box Code|conf/airframes/myplane.xml|
<pre>
<pre>
   <firmware name="fixedwing">
   <firmware name="fixedwing or rotorcraft">
    <target name="ap" board="tiny_2.11"/>
     ...
     ...
     <subsystem name="gps"              type="ublox"/>
     <subsystem name="gps"              type="ublox"/>
Line 529: Line 226:
{{Box Code|conf/airframes/myplane.xml|
{{Box Code|conf/airframes/myplane.xml|
<pre>
<pre>
   <firmware name="fixedwing">
   <firmware name="fixedwing or rotorcraft">
    <target name="ap" board="tiny_2.11"/>
     ...
     ...
     <subsystem name="gps"              type="ublox">
     <subsystem name="gps"              type="ublox">
Line 543: Line 239:
* 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 [[Compiling#USB_flashing|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center|Configured with u-center]]
* 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 [[Compiling#USB_flashing|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center|Configured with u-center]]


=== Infrared Sensors ===
== XML Parameters ==
To use the IR sensors for attitude estimation add the attitude infrared subsystem:
 
{{Box Code|conf/airframes/myplane.xml|
=== Bat ===  
<pre>
This section gives characteristics for monitoring the main power battery.
  <firmware name="fixedwing">
 
    <target name="ap"              board="tiny_2.11"/>
<b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> 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. <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> is used to compute the <tt>energy</tt> value of the <tt>BAT</tt> message when no [[Current_sensor|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 <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> 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).
    ...
 
    <subsystem name="attitude"    type="infrared"/>
The <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> 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 <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> 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 <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b>, but only partial throttle (cruise throttle) should be applied in flight.
  </firmware>
 
</pre>
If both <b><tt>MILLIAMP_AT_FULL_THROTTLE</tt></b> and <b><tt>CURRENT_ESTIMATION_NONLINEARITY</tt></b> are tweaked well, you get precise energy estimations with less than 5% error independant of your flight pattern without even requiring a [[Current_sensor|Current sensor]].
}}
 
The <b><tt>CATASTROPHIC_BAT_LEVEL</tt></b> (was previously <b><tt>LOW_BATTERY</tt></b>) 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).  <b><tt>CRITIC</tt></b> and <b><tt>LOW</tt></b> 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 <b><tt>MAX_BAT_LEVEL</tt></b> 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.


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


The ADC channels are already default to the correct ADCs for your board, but you can of course change the assignments:
Find more in depth information on how to [[Current_sensor|get a separate current sensor working by clicking here]]
{{Box Code|conf/airframes/myplane.xml|
<pre>
  <firmware name="fixedwing">
    <target name="ap"              board="tiny_2.11"/>
    ...
    <subsystem name="attitude"    type="infrared">
      <configure name="ADC_IR1"        value="ADC_1"/>
      <configure name="ADC_IR2"        value="ADC_2"/>
      <configure name="ADC_IR_TOP"    value="ADC_0"/>
      <configure name="ADC_IR_NB_SAMPLES" value="16"/>
    </subsystem>
  </firmware>
</pre>
}}


=== Control loops ===
=== Modules ===
The [[Modules|modules]] allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.


The [[Control_Loops#Fixed-wing_autopilot|control loops]] can be divided in two largely independent groups : the vertical ones and the horizontal ones (standard files sw/airborne/firmwares/fixedwing/guidance/guidance_v.c and sw/airborne/firmwares/fixedwing/stabilization/stabilization_attitude.c ). Those loops can be commanded at different levels by either the R/C transmitter or the autonomous navigation routine.
<tt>
<modules main_freq="60">
  <load name="demo_module.xml"/>
</modules>
</tt>


Just specify the appropriate subsystem in your firmware section. You can currently choose between no type (see below) and the types '''adaptive''' and '''new'''.
* The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz
{{Box Code|conf/airframes/myplane.xml|
<pre>
  <firmware name="fixedwing">
    <target name="ap" board="tiny_2.11"/>
    ...
    <subsystem name="control"/>
  </firmware>
</pre>
}}


[[Category:User_Documentation]] [[Category:Software]]
[[Category:User_Documentation]] [[Category:Software]]

Revision as of 14:59, 20 August 2011

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 airframe configuration file is located in conf/airframes.

Also see the wiki pages for fixedwing specific configuration and rotorcraft specific configuration.

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

Note that the airframe XML document always begins with a <!DOCTYPE airframe SYSTEM "airframe.dtd"> line.

Firmware and Hardware definitions

Select your Board

The airframe file must include the description of the controller board and it's low-level settings. This is done in the firmware section by specifying the board attribute for the target "ap" (autopilot).

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
Retrieved from "http://wiki.paparazziuav.org/w/index.php?title=Airframe_Configuration&oldid=9992"