Difference between revisions of "Rotorcraft Configuration"

From PaparazziUAV
Jump to: navigation, search
(Autopilot modes)
m (Links added)
 
(61 intermediate revisions by 12 users not shown)
Line 1: Line 1:
The airframe configuration file is located in <tt>conf/airframes</tt> and contains
+
<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Airframe_Configuration</categorytree>
all the hardware and software settings for an aircraft. All gains, trims, and behavior settings are defined with standard XML elements. Optionally you can also add a raw [http://en.wikipedia.org/wiki/Makefile Makefile] section.
+
This page describes configuration options <span style="color:red"><b>specific to the rotorcraft firmware</b></span> in the [[Airframe_Configuration|airframe file]].
 +
 
 +
== Firmware and Hardware definitions ==
 +
 
 +
This is one example of a pretty standard quadcopter firmware definition:
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <firmware name="rotorcraft">
 +
    <target name="nps" board="pc">
 +
      <subsystem name="fdm"  type="jsbsim"/>
 +
    </target>
 +
    <target name="ap" board="lisa_m_1.0"/>
 +
 
 +
    <subsystem name="radio_control" type="ppm"/>
 +
    <subsystem name="telemetry"    type="transparent"/>
 +
    <subsystem name="actuators"    type="mkk"/>
 +
    <subsystem name="imu"          type="aspirin_v1.5"/>
 +
    <subsystem name="gps"          type="ublox"/>
 +
    <subsystem name="ahrs"          type="int_cmpl_quat"/>
 +
    <subsystem name="stabilization" type="int_quat"/>
 +
  </firmware>
 +
</source>
 +
}}
 +
 
 +
=== Select your Board ===
 +
Make sure you use the <b>rotorcraft [[Airframe_Configuration#Firmware|firmware]]</b> and choose the correct board, e.g.
 +
 
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <firmware name="rotorcraft">
 +
    <target name="sim" board="pc"/>      <!-- For simulation -->
 +
    <target name="ap" board="lisa_m_2.0"/> <!-- Select your board here -->
 +
    ...
 +
  </firmware>
 +
</source>
 +
}}
 +
 
 +
The ap board name can be found in /conf/boards.
 +
 
 +
=== Actuators ===
 +
You have to specify which ESCs you have by adding the appropriate [[Subsystem/actuators|actuators subsystem.]]
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <firmware name="rotorcraft">
 +
    <target name="ap" board="booz_1.0"/>
 +
    ...
 +
    <subsystem name="actuators" type="mkk"/>
 +
  </firmware>
 +
</source>
 +
}}
 +
 
 +
=== Control Loops ===
 +
See the [[Subsystem/stabilization|stabilization subsystem]] page to choose which attitude control algorithm to use and how to configure them.
 +
 
 +
The [[Control Loops]] page has some diagrams.
 +
 
 +
=== INS ===
 +
The INS (Integrated Navigation System) subsystem contains estimations filter to e.g. fuse GPS and IMU data for better position and speed estimates.
 +
The INS subsystem is optional in <= v4.2.
 +
 
 +
Since v4.9x the INS subsystem is mandatory, to use the same as in v4.2 omit the type.
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <firmware name="rotorcraft">
 +
    <target name="ap" board="booz_1.0"/>
 +
    ...
 +
    <subsystem name="ins"/>
 +
  </firmware>
 +
</source>
 +
}}
 +
You can also compensate for GPS lag in hff (horizontal filter float) if it is known (in seconds):
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <firmware name="rotorcraft">
 +
    <target name="ap" board="booz_1.0"/>
 +
    ...
 +
    <subsystem name="ins" type="hff">
 +
      <define name="GPS_LAG=0.2"/>
 +
    </subsystem>
 +
  </firmware>
 +
</source>
 +
}}
 +
 
 +
== Motor Arming ==
 +
By default the motors are armed with zero-throttle and full yaw. The motors are never started if AHRS is not aligned (disable it with AUTOPILOT_DISABLE_AHRS_KILL).
 +
 
 +
Other arming sequences can be configured:
 +
* USE_KILL_SWITCH_FOR_MOTOR_ARMING defined (to 1):
 +
** switch kill switch off to arm the motors
 +
** if kill switch is off during startup, you need to kill again first, then unkill to start
 +
** throttle needs to be down, other sticks (including the trims) centered to start motors
 +
** need to be in [[AutopilotModes|MANUAL mode]] to start the motors
 +
 
 +
* USE_THROTTLE_FOR_MOTOR_ARMING defined (to 1):
 +
** automatically start motors when applying throttle
 +
** if throttle was not down at startup, you need to put throttle down again first
 +
** other sticks (including the trims) need to be centered to start motors
 +
** need to be in [[AutopilotModes|MANUAL mode]] to start the motors
  
 
== Autopilot modes ==
 
== Autopilot modes ==
 
For rotorcrafts we have a lot of different modes that can be mapped to your 3-position switch (Manual, Auto1, Auto2).
 
For rotorcrafts we have a lot of different modes that can be mapped to your 3-position switch (Manual, Auto1, Auto2).
The horizontal and vertical mode can be set differently as the following possible modes indicate:
+
The horizontal and vertical mode can be set differently as the following possible modes indicate (in parenthesis are the abbreviations displayed in the [[GCS#Strips|GCS]] strip).
  
; AP_MODE_FAILSAFE :
+
'''Limiting max thrust via RC'''<br>
 +
Modes with 'automatic' thrust control (e.g. x_Z_HOLD and NAV) let you limit the maximum thrust via RC by default. So you should push your throttle stick up after entering such a mode so the vertical controller has some "room" to stabilize the altitude. Should something weird happen you can limit the max thrust by taking throttle back.<br> You can turn this behavior off by defining '''NO_RC_THRUST_LIMIT'''
 +
 
 +
 
 +
; AP_MODE_FAILSAFE (SAFE) :
 
This is a failsafe mode that gets triggered if:
 
This is a failsafe mode that gets triggered if:
 
* RC signal is lost (and you are not in KILL or NAV mode)
 
* RC signal is lost (and you are not in KILL or NAV mode)
 
* GPS and RC is lost in NAV mode
 
* GPS and RC is lost in NAV mode
The autopilot will level the rotorcraft out (setpoints to zero pitch and roll angles) and descend at 0.5m/s downwards.
+
The standard behaviour is that autopilot will level the rotorcraft out (setpoints to zero pitch and roll angles) and descend at 0.5m/s downwards. But this behavior can also be changed to something else ofcourse.
  
; AP_MODE_KILL :
+
; AP_MODE_KILL (KILL) :
 
Motors are simply switched off.
 
Motors are simply switched off.
  
; AP_MODE_RATE_DIRECT :
+
; AP_MODE_RATE_DIRECT (RATE) :
 
This is basically the "most" manual mode you can get. You control not the attitude (roll and pitch angles) but the rotation rate. You also set the throttle directly with your RC.
 
This is basically the "most" manual mode you can get. You control not the attitude (roll and pitch angles) but the rotation rate. You also set the throttle directly with your RC.
  
; AP_MODE_ATTITUDE_DIRECT :
+
; AP_MODE_ATTITUDE_DIRECT (ATT) :
You control the attitude (roll, pitch and yaw angles), but the throttle directly proportional to your stick position.
+
You control the attitude (roll, pitch and yaw angles), but the throttle is directly proportional to your stick position.
  
; AP_MODE_RATE_RC_CLIMB :
+
; AP_MODE_RATE_RC_CLIMB (R_RCC) :
You control the rotation rate and the vertical speed according to your throttle stick position. If you have your throttle stick in the middle position, the altitude is keept, down goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it recenter itself.
+
You control the rotation rate and the vertical speed according to your throttle stick position.<br>If you have your throttle stick in the middle position, the altitude is kept, down goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it can recenter itself.
  
; AP_MODE_ATTITUDE_RC_CLIMB :
+
; AP_MODE_ATTITUDE_RC_CLIMB (A_RCC) :
You control the attitude (roll, pitch and yaw angles) and the vertical speed according to your throttle stick position. If you have your throttle stick in the middle position, the altitude is keept, down goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it recenter itself.
+
You control the attitude (roll, pitch and yaw angles) and the vertical speed according to your throttle stick position.<br>If you have your throttle stick in the middle position the altitude is kept, if you move the stick down it goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it recenter itself.
  
; AP_MODE_ATTITUDE_CLIMB :
+
; AP_MODE_ATTITUDE_CLIMB (ATT_C) :
 
You control the attitude (roll, pitch and yaw angles) and the vertical speed. The vertical speed is set via fms (e.g. joystick).
 
You control the attitude (roll, pitch and yaw angles) and the vertical speed. The vertical speed is set via fms (e.g. joystick).
  
; AP_MODE_RATE_Z_HOLD :
+
; AP_MODE_RATE_Z_HOLD (R_ZH) :
You control the rotation rate and it holds the altitude you were at when entering this mode. Your throttle stick position still limits the max throttle authority, so you should push your throttle stick up after entering this mode so the vertical controller has some "room" to stabilize the altitude. Should something weird happen you can limit the max thrust by taking throttle back.
+
You control the rotation rate and it holds the altitude you were at when entering this mode.<br>Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.
  
; AP_MODE_ATTITUDE_Z_HOLD :
+
; AP_MODE_ATTITUDE_Z_HOLD (A_ZH) :
You control the attitude (roll, pitch and yaw angles) and it holds the altitude you were at when entering this mode. Your throttle stick position still limits the max throttle authority, so you should push your throttle stick up after entering this mode so the vertical controller has some "room" to stabilize the altitude. Should something weird happen you can limit the max thrust by taking throttle back.
+
You control the attitude (roll, pitch and yaw angles) and it holds the altitude you were at when entering this mode.<br>Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.
  
; AP_MODE_HOVER_DIRECT :
+
; AP_MODE_HOVER_DIRECT (HOVER) :
The rotorcraft hovers at the horizontal position you were at when entering this mode (position control). You still set the throttle directly with your RC.
+
The rotorcraft hovers at the horizontal position you were at when entering this mode (position control). You still set the throttle directly with your RC. Yaw command on the RC allows for heading change. If USE_SPEED_REF=1 then pitch and roll commands in the RC control speed according to max speed set with REF_MAX_SPEED in the GUIDANCE_H section of airframe file.
  
; AP_MODE_HOVER_CLIMB :
+
; AP_MODE_HOVER_CLIMB (HOV_C) :
The rotorcraft hovers at the position you were at when entering this mode (position control). The vertical speed is set via fms (e.g. joystick).
+
The rotorcraft hovers at the position you were at when entering this mode (position control). RC commands work the same as in HOVER mode. The vertical speed is set via fms (e.g. joystick).
  
; AP_MODE_HOVER_Z_HOLD :
+
; AP_MODE_HOVER_Z_HOLD (H_ZH):
The rotorcraft hovers at the 3D position you were at when entering this mode (position and altitude control). Your throttle stick position still limits the max throttle authority, so you should push your throttle stick up after entering this mode so the vertical controller has some "room" to stabilize the altitude. Should something weird happen you can limit the max thrust by taking throttle back.
+
The rotorcraft hovers at the 3D position you were at when entering this mode (position and altitude control). RC commands work the same as in HOVER mode. <br>Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.
  
; AP_MODE_NAV :
+
; AP_MODE_NAV (NAV) :
Full navigation mode. The rotorcraft follows your flightplan.
+
Full navigation mode. The rotorcraft follows your flightplan.<br>If you have a valid RC signal, your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.
  
=== Control Loops ===
+
; AP_MODE_RC_DIRECT (RC_D) :
 +
Safety pilot direct commands for helicopter.
  
The control loops for rotorcraft can be found in [[Control Loops]].
+
; AP_MODE_CARE_FREE_DIRECT (CF):
 +
Same as AP_MODE_ATTITUDE_DIRECT, but the roll and pitch commands are based on the yaw angle when entering this mode.
  
 
== XML Parameters ==
 
== XML Parameters ==
Line 56: Line 159:
 
=== Mode ===
 
=== Mode ===
 
In the mode section you can set the autopilot modes associated with your 3-way mode switch on your RC.
 
In the mode section you can set the autopilot modes associated with your 3-way mode switch on your RC.
<tt><section name="MODE" prefix="MODE_">
+
{{Box Code|conf/airframes/myrotorcraft.xml|
  <define name="MANUAL" value="AP_MODE_ATTITUDE_DIRECT" />
+
<source lang="xml">
  <define name="AUTO1" value="AP_MODE_ATTITUDE_Z_HOLD" />
+
  <section name="MODE" prefix="MODE_">
  <define name="AUTO2" value="AP_MODE_HOVER_Z_HOLD" />
+
    <define name="MANUAL" value="AP_MODE_ATTITUDE_DIRECT" />
</section></tt>
+
    <define name="AUTO1" value="AP_MODE_ATTITUDE_Z_HOLD" />
 +
    <define name="AUTO2" value="AP_MODE_NAV" />
 +
  </section>
 +
</source>
 +
}}
  
 
=== Commands ===
 
=== Commands ===
  
 
The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. For most multicopter you just need:
 
The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. For most multicopter you just need:
<tt><commands>
+
{{Box Code|conf/airframes/myrotorcraft.xml|
  <axis name="PITCH" failsafe_value="0"/>
+
<source lang="xml">
  <axis name="ROLL" failsafe_value="0"/>
+
  <commands>
  <axis name="YAW" failsafe_value="0 />
+
    <axis name="PITCH" failsafe_value="0"/>
  <axis name="THRUST" failsafe_value="0"/>
+
    <axis name="ROLL" failsafe_value="0"/>
</commands></tt>
+
    <axis name="YAW" failsafe_value="0" />
 +
    <axis name="THRUST" failsafe_value="0"/>
 +
  </commands>
 +
</source>
 +
}}
  
 
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.
 
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.
  
=== Supervision ===
+
=== Motor Mixing ===
 +
 
 +
This section describes the "mixing" used for your particular multirotor configuration. This section is needed for all ESCs except "asctec_v1" wich do their mixing themselves.
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="width:800px">
 +
Used since '''v5.0''', for previous version see [[Rotorcraft_Configuration#Supervision|Supervision]].
 +
<div class="mw-collapsible-content">Differences with the older supervision (used prior to '''v4.9_devel-164-gdb0d004'''):
 +
* names: SUPERVISION -> MOTOR_MIXING
 +
* independent of the actuators, needs to be loaded in the subsystems and call in the command_laws section
 +
* internal values have '''pprz''' format (int16, between [-9600; 9600])
 +
* min and max are not needed, coming from the servos definition
 +
* trim are renamed with more explicit names
 +
</div></div>
 +
 
 +
This subsystem takes ''roll'', ''pitch'', ''yaw'' and ''thrust'' commands as inputs and "mixes" them to get the final commands for your individual motors according to the layout of them. See [[RotorcraftMixing]] for the details behind this.
 +
 
 +
Note that after mixing the separate motor commands can "saturate", meaning you can't simply give negative thrust or more than the maximum. If a saturation is reached (desired motor command outside of possible MIN_MOTOR/MAX_MOTOR range), a saturation offset is applied to all motors in order to give attitude commands a higher priority than thrust. This offset is limited to ''MOTOR_MIXING_MAX_SATURATION_OFFSET'' (default is 10% of maximum command).
  
This section describes the "mixing" used for your particular multirotor configuration. This section is needed for "mkk" (mikrokopter) and "asctecV2" controllers, as "asctecV1" do their mixing themselves.
+
See also [https://github.com/paparazzi/paparazzi/issues/385 issue #385].
  
<pre>
+
In '''firmware''' section:
  <section name="SUPERVISION" prefix="SUPERVISION_">
+
{{Box Code|conf/airframes/myrotorcraft.xml|
    <define name="MIN_MOTOR" value="3"/>
+
<source lang="xml">
     <define name="MAX_MOTOR" value="200"/>
+
  <firmware name="rotorcraft">
     <define name="TRIM_A" value="0"/>
+
    ...
     <define name="TRIM_E" value="0"/>
+
    <subsystem name="motor_mixing"/>
     <define name="TRIM_R" value="0"/>
+
    ...
 +
  </firmware>
 +
</source>
 +
}}
 +
 
 +
Configuration of the motor mixing:
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
     <define name="TRIM_ROLL" value="0"/>
 +
     <define name="TRIM_PITCH" value="0"/>
 +
     <define name="TRIM_YAW" value="0"/>
 +
     <define name="MAX_SATURATION_OFFSET" value="MAX_PPRZ/10"/>
 
     <define name="NB_MOTOR" value="4"/>
 
     <define name="NB_MOTOR" value="4"/>
 
     <define name="SCALE" value="256"/>
 
     <define name="SCALE" value="256"/>
 
     <define name="ROLL_COEF"  value="{  0  ,    0,  256, -256 }"/>
 
     <define name="ROLL_COEF"  value="{  0  ,    0,  256, -256 }"/>
 
     <define name="PITCH_COEF"  value="{  256, -256,    0,    0 }"/>
 
     <define name="PITCH_COEF"  value="{  256, -256,    0,    0 }"/>
     <define name="YAW_COEF"    value="{ 256, 256, -256, -256 }"/>
+
     <define name="YAW_COEF"    value="{ -256, -256, 256, 256 }"/>
 
     <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
 
     <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
 
   </section>
 
   </section>
</pre>
+
</source>
 +
}}
 +
 
 +
; ''TRIM_ROLL'' : trim added to roll command
 +
; ''TRIM_PITCH'' : trim added to pitch command
 +
; ''TRIM_YAW'' : trim added to yaw command
 +
; ''MAX_SATURATION_OFFSET'' : set at "MAX_PPRZ/10" by default
 +
; x''_COEF'' : roll/pitch/yaw/thrust coefficients, see [[RotorcraftMixing]] for details or the examples below
 +
 
 +
In '''command_laws''' section (placed after section MIXING):
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <command_laws>
 +
    <call fun="motor_mixing_run(autopilot_motors_on, FALSE, values)"/>
 +
    <set servo="FRONT" value="motor_mixing.commands[0]"/>
 +
    <set servo="BACK"  value="motor_mixing.commands[1]"/>
 +
    <set servo="RIGHT" value="motor_mixing.commands[2]"/>
 +
    <set servo="LEFT"  value="motor_mixing.commands[3]"/>
 +
  </command_laws>
 +
</source>
 +
}}
  
Below are values for the common "plus cross", "time cross" quadrirotor configurations.
+
==== Mixing Examples ====
  
 +
Hint: If your rotors are spinning '''opposite''' to the '''direction''' shown in the picture, '''reverse signs''' in the YAW_COEF line.
  
 
; Plus Cross : [[Image:cross_plus_simple.png|200px]]
 
; Plus Cross : [[Image:cross_plus_simple.png|200px]]
Assuming that the order of motors, described in the "servos" section is FRONT, BACK, LEFT, RIGHT.
+
Assuming that the order of motors, described in the "servos" section is FRONT, RIGHT, BACK, LEFT.
<pre>
+
<source lang="xml">
     <define name="ROLL_COEF"  value="{    0,    0,  256, -256 }"/>
+
  <section name="MIXING" prefix="MOTOR_MIXING_">
     <define name="PITCH_COEF"  value="{  256, -256,    0,    0 }"/>
+
    <define name="NB_MOTOR" value="4"/>
     <define name="YAW_COEF"    value="{ 256256, -256, -256 }"/>
+
    <define name="SCALE" value="256"/>
 +
     <define name="ROLL_COEF"  value="{    0, -256,    0,  256 }"/>
 +
     <define name="PITCH_COEF"  value="{  256,    0, -256,    0 }"/>
 +
     <define name="YAW_COEF"    value="{ -128128, -128, 128 }"/>
 
     <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
 
     <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
</pre>
+
  </section>
 
+
</source>
 +
This is equivalent to (available since v5.5_devel-602-g0129d3e):
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="TYPE" value="QUAD_PLUS"/>
 +
  </section>
 +
</source>
  
 
; Time Cross : [[Image:cross_time_simple.png|200px]]
 
; Time Cross : [[Image:cross_time_simple.png|200px]]
Assuming that the order of motors, described in the "servos" section is NE, SE, SW, NW.
+
Assuming that the order of motors, described in the "servos" section is NW, NE, SE, SW.
<pre>
+
<source lang="xml">
     <define name="ROLL_COEF"  value="{ -256, -256,  256256 }"/>
+
  <section name="MIXING" prefix="MOTOR_MIXING_">
     <define name="PITCH_COEF"  value="{  256, -256, -256,  256 }"/>
+
    <define name="NB_MOTOR" value="4"/>
     <define name="YAW_COEF"    value="{  256, -256256, -256 }"/>
+
    <define name="SCALE" value="256"/>
 +
     <define name="ROLL_COEF"  value="{ 181, -181, -181181 }"/>
 +
     <define name="PITCH_COEF"  value="{  181,  181, -181, -181 }"/>
 +
     <define name="YAW_COEF"    value="{  128, -128128, 128 }"/>
 
     <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
 
     <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
</pre>
+
  </section>
 +
</source>
 +
This is equivalent to (available since v5.5_devel-602-g0129d3e):
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="TYPE" value="QUAD_X_CCW"/>
 +
  </section>
 +
</source>
 +
This is equivalent to (available since v5.9_devel):
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="TYPE" value="QUAD_X"/>
 +
    <define name="REVERSE" value="true"/>
 +
  </section>
 +
</source>
  
if your rotors are spinning opposite to the direction showed in the picture, just reverse signs in the YAW_COEF line.
 
  
If you want to compute mixing for a special configuration, please see the [[RotorcraftMixing]] page.
+
; Hex (Time Cross) : [[Image:Hex_cross_layout.png|200px]]
 +
Assuming that the order of motors, described in the "servos" section is FRONT_LEFT, FRONT_RIGHT, RIGHT, BACK_RIGHT, BACK_LEFT, LEFT.
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="NB_MOTOR" value="6"/>
 +
    <define name="SCALE" value="256"/>
 +
    <define name="ROLL_COEF"  value="{  128, -128,  -256,  -128,  128, 256 }"/>
 +
    <define name="PITCH_COEF"  value="{  222,  222,    0,  -222, -222,  0 }"/>
 +
    <define name="YAW_COEF"    value="{ -128,  128,  -128,  128, -128, 128 }"/>
 +
    <define name="THRUST_COEF" value="{  256,  256,  256,  256,  256, 256 }"/>
 +
  </section>
 +
</source>
 +
This is equivalent to (available since v5.5_devel-602-g0129d3e):
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="TYPE" value="HEXA_X"/>
 +
  </section>
 +
</source>
  
=== Bat ===
 
This section give characteristics for the monitoring of the main power battery.
 
  
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.
+
; Octo (time cross): [[Image:octo.jpg|border|200px]]
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="NB_MOTOR" value="8"/>
 +
    <define name="SCALE" value="256"/>
 +
    <define name="ROLL_COEF"  value="{  98,  -98, -237, -237,  -98,  98,  237,  237 }"/>
 +
    <define name="PITCH_COEF"  value="{  237,  237,  98,  -98, -237, -237,  -98,  98 }"/>
 +
    <define name="YAW_COEF"    value="{ -128,  128, -128,  128, -128,  128, -128,  128 }"/>
 +
    <define name="THRUST_COEF" value="{  256,  256,  256,  256,  256,  256,  256,  256 }"/>
 +
  </section>
 +
</source>
 +
This is equivalent to (available since v5.5_devel-602-g0129d3e):
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="TYPE" value="OCTO_X"/>
 +
  </section>
 +
</source>
  
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">
+
; Octo (plus cross): [[Image:Octo_plus_motor_layout.png|border|200px]]
  <define name="MILLIAMP_PER_PERCENT" value="0.86" />
+
<source lang="xml">
  <define name="CATASTROPHIC_BAT_LEVEL" value="9.3" unit="V" />
+
  <section name="MIXING" prefix="MOTOR_MIXING_">
  <define name="MAX_BAT_LEVEL" value="12.0" unit="V" />
+
    <define name="NB_MOTOR" value="8"/>
  <define name="BATTERY_SENS" value="0.246" integer="16" />
+
    <define name="SCALE" value="256"/>
  <define name="BATTERY_OFFSET" value="0" />
+
    <define name="ROLL_COEF"   value="{    0, -181, -256, -181,    0,  181,  256,  181 }"/>
</section></tt>
+
    <define name="PITCH_COEF" value="{  256,  181,    0, -181, -256, -181,    0,  181 }"/>
 +
    <define name="YAW_COEF"    value="{ -128,  128, -128,  128, -128,  128, -128,  128 }"/>
 +
    <define name="THRUST_COEF" value="{  256,  256,  256,  256,  256,  256,  256,  256 }"/>
 +
  </section>
 +
</source>
 +
This is equivalent to (available since v5.5_devel-602-g0129d3e):
 +
<source lang="xml">
 +
  <section name="MIXING" prefix="MOTOR_MIXING_">
 +
    <define name="TYPE" value="OCTO_PLUS"/>
 +
  </section>
 +
</source>
  
  
 +
If you want to compute mixing for a special configuration, please see the [[RotorcraftMixing]] page.
  
=== Simulation ===
+
=== Supervision ===
Values from this section can be used to tweak the SITL simulation. The NPS (New Paparazzi Sim) currently uses JSBSim as for the flight dynamic modeling, but other FDMs are possible.
+
<div class="toccolours mw-collapsible mw-collapsed">
 +
Prior to '''v5.0''' motor mixing was called supervision. Click expand to see the details.
 +
<div class="mw-collapsible-content">
 +
Valid before '''v4.9_devel-164-gdb0d004'''
  
<tt><section name="SIMULATOR" prefix="NPS_">
+
<source lang="xml">
   <define name="ACTUATOR_NAMES" value="{&quot;front_motor&quot;, &quot;back_motor&quot;, &quot;right_motor&quot;, &quot;left_motor&quot;}" />
+
  <section name="SUPERVISION" prefix="SUPERVISION_">
  <define name="INITIAL_CONDITITONS" value="&quot;reset00&quot;" />
+
    <define name="STOP_MOTOR" value="0"/> <!-- this defaults to zero, set to a different value if needed, e.g. for pwm controllers -->
  <define name="SENSORS_PARAMS" value="&quot;nps_sensors_params_booz2_a1.h&quot;" />
+
    <define name="MIN_MOTOR" value="3"/>
</section></tt>
+
    <define name="MAX_MOTOR" value="200"/>
 +
    <define name="TRIM_A" value="0"/>
 +
    <define name="TRIM_E" value="0"/>
 +
    <define name="TRIM_R" value="0"/>
 +
    <define name="NB_MOTOR" value="4"/>
 +
    <define name="SCALE" value="256"/>
 +
    <define name="ROLL_COEF"  value="{  0  ,   0,  256, -256 }"/>
 +
    <define name="PITCH_COEF" value="{ 256, -256,   0,   0 }"/>
 +
    <define name="YAW_COEF"   value="{ -256, -256,  256,  256 }"/>
 +
    <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
 +
  </section>
 +
</source>
  
=== Modules ===
+
; ''STOP_MOTOR'' : actuator specific command value to stop the motors
The [[Modules|modules]] allow to add new code in a flexible way with initialisation, periodic and event functions without modifying the main AP loop.
+
; ''MIN_MOTOR'' : actuator specific command value for idling motors
 +
; ''MAX_MOTOR'' : actuator specific command value for maximum power
 +
; ''TRIM_A'' : trim added to roll command
 +
; ''TRIM_E'' : trim added to pitch command
 +
; ''TRIM_R'' : trim added to yaw command
 +
; x''_COEF'' : roll/pitch/yaw/thrust coefficients, see [[RotorcraftMixing]] for details or the examples in the above Motor Mixing section
 +
</div>
 +
</div>
  
<tt><modules main_freq="512">
+
=== Guidance ===
  <load name="sys_mon.xml"/>
+
There are two sets of parameters for guidance: vertical (altitude) and horizontal (position).
</modules></tt>
 
  
* The main_freq parameter (in Hz) allows to specify the frequency of the main loop. Default is 60 Hz, for rotorcraft you should use 512 Hz.
+
==== vertical guidance ====
 +
{{Box Code|conf/airframes/myrotorcraft.xml|
 +
<source lang="xml">
 +
  <section name="GUIDANCE_V" prefix="GUIDANCE_V_">
 +
    <define name="HOVER_KP"    value="150"/>
 +
    <define name="HOVER_KD"    value="80"/>
 +
    <define name="HOVER_KI"    value="20"/>
  
== Firmware and Hardware definitions ==
+
     <!-- optional parameters -->
 
+
     <define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>
This is one example of a pretty standard quadcopter firmware definition:
+
     <define name="ADAPT_THROTTLE_ENABLED" value="TRUE"/>
{{Box Code|conf/airframes/myplane.xml|
+
     <define name="REF_MIN_ZD" value="-3.0" unit="m/s"/>
<pre>
+
     <define name="REF_MAX_ZD" value="3.0" unit="m/s"/>
  <firmware name="rotorcraft">
+
     <define name="MAX_RC_CLIMB_SPEED" value="-3.0" unit="m/s"/>
     <target name="sim" board="pc">
+
     <define name="MAX_RC_DESCENT_SPEED" value="3.0" unit="m/s"/>
      <subsystem name="fdm"  type="nps"/>
+
   </section>
     </target>
+
</source>
 
 
    <target name="ap" board="booz_1.0"/>
 
 
 
     <configure name="MODEM_BAUD" value="B57600"/><!--this is already the default, add and change this line only if needed-->
 
 
 
    <define name="USE_ADAPT_HOVER"/>
 
     <define name="GUIDANCE_H_USE_REF"/>
 
 
 
    <subsystem name="radio_control" type="ppm"/>
 
     <subsystem name="telemetry"     type="transparent"/>
 
    <subsystem name="actuators"    type="mkk"/>
 
     <subsystem name="imu"           type="b2_v1.1"/>
 
    <subsystem name="gps"          type="ublox"/>
 
     <subsystem name="ahrs"         type="cmpl"/>
 
    <subsystem name="ins"           type="hff"/>
 
   </firmware>
 
</pre>
 
 
}}
 
}}
=== 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 <b><tt>firmware</tt></b> section by specifying the ''board'' attribute for the ''target'' "ap" (autopilot).
 
  
Select the appropriate board:
+
; ''HOVER_K''x : PID parameters for vertical hover control loop
"twog_1.0", "tiny_2.11", "tiny_2.1", "tiny_1.1", "tiny_0.99", "booz_1.0", "lisa_l_1.0", "lisa_l_1.1", "pc"
+
; ''NOMINAL_HOVER_THROTTLE'' : expected throttle percentage needed for hovering (default is 0.4 = 40%)
 +
; ''ADAPT_THROTTLE_ENABLED'' : enable adaptive nominal hover throttle estimation (default is TRUE, set to FALSE to disable)
 +
; ''REF_MIN_ZD'' : vertical speed reference lower limit (since z-down is positive -> max speed upwards) (default -3.0m/s)
 +
; ''REF_MAX_ZD'' : vertical speed reference upper limit (since z-down is positive -> max speed downwards) (default 3.0m/s)
 +
; ''MAX_RC_CLIMB_SPEED'' : climb speed at max RC input in RC_CLIMB mode (default is ''REF_MIN_ZD'')
 +
; ''MAX_RC_DESCENT_SPEED'' : descent speed at max RC input in RC_CLIMB mode (default is ''REF_MAX_ZD'')
  
{{Box Code|conf/airframes/myplane.xml|
+
==== horizontal guidance ====
<pre>
+
{{Box Code|conf/airframes/myrotorcraft.xml|
   <firmware name="rotorcraft">
+
<source lang="xml">
     <target name="sim" board="pc"/>
+
   <section name="GUIDANCE_H" prefix="GUIDANCE_H_">
     <target name="ap" board="booz_1.0"/>
+
     <define name="PGAIN" value="50"/>
    ...
+
     <define name="DGAIN" value="100"/>
  </firmware>
+
    <define name="IGAIN" value="20"/>
</pre>
 
}}
 
  
=== Radio Control ===
+
    <!-- optional parameters -->
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|Radio Control]] file.
+
    <define name="AGAIN" value="0"/>
 +
    <define name="VGAIN" value="0"/>
  
Just specify the appropriate subsystem in your firmware section:
+
    <define name="MAX_BANK" value="20" unit="deg"/>
{{Box Code|conf/airframes/myplane.xml|
+
    <define name="USE_SPEED_REF" value="TRUE"/>
<pre>
+
    <define name="REF_MAX_SPEED" value="5.0" unit="m/s"/>
  <firmware name="rotorcraft">
+
    <define name="REF_MAX_ACCEL" value="5.66" unit="m/s2"/>
     <target name="sim" board="pc"/>
+
     <define name="REF_OMEGA" value="67" unit="deg"/>
     <target name="ap" board="booz_1.0"/>
+
     <define name="REF_ZETA" value="0.85"/>
    ...
+
    <define name="REF_TAU" value="0.5"/>
     <subsystem name="radio_control"     type="ppm"/>
+
     <define name="APPROX_FORCE_BY_THRUST" value="FALSE"/>
   </firmware>
+
   </section>
</pre>
+
</source>
 
}}
 
}}
  
On the autopilots with a STM32 processor (lisa) you can use the type ''spektrum''.
+
; [PID]''GAIN'' : PID gains for horizontal control
 +
; ''AGAIN'' : acceleration feedforward gain (default 0)
 +
; ''VGAIN'' : velocity feedforward gain (default 0)
 +
; ''MAX_BANK'' : maximum roll/pitch angle that is set from horizontal guidance (default 20deg, max 40deg)
 +
; ''USE_SPEED_REF'' : since v5.1, give velocity commands via RC in GUIDANCE_H_MODE_HOVER (default: TRUE)
 +
; ''REF_MAX_SPEED'' : maximum reference horizontal speed in m/s (default 5.0m/s)
 +
; ''REF_MAX_ACCEL'' : maximum reference horizontal acceleration in m/s² (default tanf(RadOfDeg(30.))*9.81 = 5.66)
 +
; ''REF_OMEGA'' : second order model natural frequency
 +
; ''REF_ZETA'' : second order model damping
 +
; ''REF_TAU'' : first order time constant
 +
; ''APPROX_FORCE_BY_THRUST'' : try to better approximate force commands by taking thrust into account (default FALSE, set to TRUE to use it)
  
=== Telemetry (Modem) ===
+
=== Simulation ===
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 <tt>conf/telemetry/default.xml</tt>.  Those wishing to experiment with "alternative" modems can reduce the number and period of each telemetry message to fit within most any bandwidth constraint.
+
See [[NPS]] (New Paparazzi Sim).
 
 
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'''.
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="telemetry"    type="transparent"/>
 
  </firmware>
 
</pre>
 
}}
 
 
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.
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="telemetry"    type="transparent">
 
      <configure name="MODEM_BAUD"          value="B9600"/>
 
      <configure name="MODEM_PORT"          value="UART1"/>
 
    </subsystem>
 
  </firmware>
 
</pre>
 
}}
 
 
=== GPS ===
 
For rotorcraft you can use the GPS types: 'ublox' and 'skytraq'. The ublox type is good for both lea-4p and lea-5h.
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="gps"              type="ublox"/>
 
  </firmware>
 
</pre>
 
}}
 
 
The serial port settings must match that of the GPS:
 
 
The correct UART is already defined by default according to your board. The default gps baudrate is 38400baud.
 
 
If you use different baud rates set the according parameters, e.g.
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="gps"              type="ublox">
 
      <configure name="GPS_BAUD"          value="B9600"/>
 
    </subsystem>
 
  </firmware>
 
</pre>
 
}}
 
 
'''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 [[Compiling#USB_flashing|UART Tunnel]] and [[GPS#GPS_configuration_using_U-Center|Configured with u-center]]
 
 
=== IMU ===
 
Add the imu subsystem with the type you are using. Currently possible IMU subsystems are "b2_v1.0", "b2_v1.1", "b2_v1.2", "crista" and "[[AspirinIMU|aspirin]]". Other IMUs can be used through modules or you can just add a subsystem makefile for your own. Also see the [[ImuCalibration|IMU calibration]] page.
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="imu"      type="b2_v1.0"/>
 
  </firmware>
 
</pre>
 
}}
 
 
=== AHRS ===
 
The AHRS subsystem specifies which attitude estimation filter you are using, e.g. for the complementary filter:
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="ahrs" type="cmpl"/>
 
  </firmware>
 
</pre>
 
}}
 
 
For the latest integer complementary filter (ic):
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="ahrs" type="ic"/>
 
  </firmware>
 
 
<section name="AHRS" prefix="AHRS_">
 
    <define name="PROPAGATE_FREQUENCY" value="512"/>
 
    <define name="H_X" value=" 0.51562740288882"/>
 
    <define name="H_Y" value="-0.05707735220832"/>
 
    <define name="H_Z" value=" 0.85490967783446"/>
 
  </section>
 
</pre>
 
}}
 
 
H is the normalised local magnetic field which can be derived by following instructions on the IMU calibration page [http://paparazzi.enac.fr/wiki/BoozSensorsCalibration#AHRS-integer_complementary_.28ic.29_filter_normalised_magnetic_X.2CY.2CZ_fields here].
 
 
Other flags of interest are;
 
 
*AHRS_PROPAGATE_LOW_PASS_RATES : apply a low pass filter on rotational velocity
 
*AHRS_MAG_UPDATE_YAW_ONLY : use mag to update yaw only
 
 
There is a test program ( sw/airborne/test/ahrs/compare_ahrs.py ) to compare different AHRS implementations on simple test cases.
 
 
=== INS ===
 
The optional INS (Integrated Navigation System) subsystem contains estimations filter to e.g. fuse GPS and IMU data for better position and speed estimates.
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="ins" type="hff"/>
 
  </firmware>
 
</pre>
 
}}
 
You can also compensate for GPS lag in hff (horizontal filter float) if it is known (in seconds):
 
{{Box Code|conf/airframes/myplane.xml|
 
<pre>
 
  <firmware name="rotorcraft">
 
    <target name="ap" board="booz_1.0"/>
 
    ...
 
    <subsystem name="ins" type="hff">
 
      <define name="GPS_LAG=0.2"/>
 
    </subsystem>
 
  </firmware>
 
</pre>
 
}}
 
Beware, this code is kinda bad/ugly and should be replaced/improved!
 
  
[[Category:Software]] [[Category:User_Documentation]] [[Category:Rotorcraft]]
+
[[Category:Airframe_Configuration]] [[Category:User_Documentation]] [[Category:Rotorcraft]]

Latest revision as of 02:25, 28 November 2017

This page describes configuration options specific to the rotorcraft firmware in the airframe file.

Firmware and Hardware definitions

This is one example of a pretty standard quadcopter firmware definition:

File: conf/airframes/myrotorcraft.xml
  <firmware name="rotorcraft">
    <target name="nps" board="pc">
      <subsystem name="fdm"   type="jsbsim"/>
    </target>
    <target name="ap" board="lisa_m_1.0"/>

    <subsystem name="radio_control" type="ppm"/>
    <subsystem name="telemetry"     type="transparent"/>
    <subsystem name="actuators"     type="mkk"/>
    <subsystem name="imu"           type="aspirin_v1.5"/>
    <subsystem name="gps"           type="ublox"/>
    <subsystem name="ahrs"          type="int_cmpl_quat"/>
    <subsystem name="stabilization" type="int_quat"/>
  </firmware>

Select your Board

Make sure you use the rotorcraft firmware and choose the correct board, e.g.


File: conf/airframes/myrotorcraft.xml
  <firmware name="rotorcraft">
    <target name="sim" 	board="pc"/>       <!-- For simulation -->
    <target name="ap" 	board="lisa_m_2.0"/> <!-- Select your board here -->
     ...
  </firmware>

The ap board name can be found in /conf/boards.

Actuators

You have to specify which ESCs you have by adding the appropriate actuators subsystem.

File: conf/airframes/myrotorcraft.xml
  <firmware name="rotorcraft">
    <target name="ap" board="booz_1.0"/>
     ...
    <subsystem name="actuators" type="mkk"/>
  </firmware>

Control Loops

See the stabilization subsystem page to choose which attitude control algorithm to use and how to configure them.

The Control Loops page has some diagrams.

INS

The INS (Integrated Navigation System) subsystem contains estimations filter to e.g. fuse GPS and IMU data for better position and speed estimates. The INS subsystem is optional in <= v4.2.

Since v4.9x the INS subsystem is mandatory, to use the same as in v4.2 omit the type.

File: conf/airframes/myrotorcraft.xml
  <firmware name="rotorcraft">
    <target name="ap" board="booz_1.0"/>
     ...
    <subsystem name="ins"/>
  </firmware>

You can also compensate for GPS lag in hff (horizontal filter float) if it is known (in seconds):

File: conf/airframes/myrotorcraft.xml
  <firmware name="rotorcraft">
    <target name="ap" board="booz_1.0"/>
     ...
    <subsystem name="ins" type="hff">
      <define name="GPS_LAG=0.2"/>
    </subsystem>
  </firmware>

Motor Arming

By default the motors are armed with zero-throttle and full yaw. The motors are never started if AHRS is not aligned (disable it with AUTOPILOT_DISABLE_AHRS_KILL).

Other arming sequences can be configured:

  • USE_KILL_SWITCH_FOR_MOTOR_ARMING defined (to 1):
    • switch kill switch off to arm the motors
    • if kill switch is off during startup, you need to kill again first, then unkill to start
    • throttle needs to be down, other sticks (including the trims) centered to start motors
    • need to be in MANUAL mode to start the motors
  • USE_THROTTLE_FOR_MOTOR_ARMING defined (to 1):
    • automatically start motors when applying throttle
    • if throttle was not down at startup, you need to put throttle down again first
    • other sticks (including the trims) need to be centered to start motors
    • need to be in MANUAL mode to start the motors

Autopilot modes

For rotorcrafts we have a lot of different modes that can be mapped to your 3-position switch (Manual, Auto1, Auto2). The horizontal and vertical mode can be set differently as the following possible modes indicate (in parenthesis are the abbreviations displayed in the GCS strip).

Limiting max thrust via RC
Modes with 'automatic' thrust control (e.g. x_Z_HOLD and NAV) let you limit the maximum thrust via RC by default. So you should push your throttle stick up after entering such a mode so the vertical controller has some "room" to stabilize the altitude. Should something weird happen you can limit the max thrust by taking throttle back.
You can turn this behavior off by defining NO_RC_THRUST_LIMIT


AP_MODE_FAILSAFE (SAFE) 

This is a failsafe mode that gets triggered if:

  • RC signal is lost (and you are not in KILL or NAV mode)
  • GPS and RC is lost in NAV mode

The standard behaviour is that autopilot will level the rotorcraft out (setpoints to zero pitch and roll angles) and descend at 0.5m/s downwards. But this behavior can also be changed to something else ofcourse.

AP_MODE_KILL (KILL) 

Motors are simply switched off.

AP_MODE_RATE_DIRECT (RATE) 

This is basically the "most" manual mode you can get. You control not the attitude (roll and pitch angles) but the rotation rate. You also set the throttle directly with your RC.

AP_MODE_ATTITUDE_DIRECT (ATT) 

You control the attitude (roll, pitch and yaw angles), but the throttle is directly proportional to your stick position.

AP_MODE_RATE_RC_CLIMB (R_RCC) 

You control the rotation rate and the vertical speed according to your throttle stick position.
If you have your throttle stick in the middle position, the altitude is kept, down goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it can recenter itself.

AP_MODE_ATTITUDE_RC_CLIMB (A_RCC) 

You control the attitude (roll, pitch and yaw angles) and the vertical speed according to your throttle stick position.
If you have your throttle stick in the middle position the altitude is kept, if you move the stick down it goes down at a speed proportional to your stick position (same for up). In this mode it makes sense to mount the spring for your throttle stick so it recenter itself.

AP_MODE_ATTITUDE_CLIMB (ATT_C) 

You control the attitude (roll, pitch and yaw angles) and the vertical speed. The vertical speed is set via fms (e.g. joystick).

AP_MODE_RATE_Z_HOLD (R_ZH) 

You control the rotation rate and it holds the altitude you were at when entering this mode.
Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

AP_MODE_ATTITUDE_Z_HOLD (A_ZH) 

You control the attitude (roll, pitch and yaw angles) and it holds the altitude you were at when entering this mode.
Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

AP_MODE_HOVER_DIRECT (HOVER) 

The rotorcraft hovers at the horizontal position you were at when entering this mode (position control). You still set the throttle directly with your RC. Yaw command on the RC allows for heading change. If USE_SPEED_REF=1 then pitch and roll commands in the RC control speed according to max speed set with REF_MAX_SPEED in the GUIDANCE_H section of airframe file.

AP_MODE_HOVER_CLIMB (HOV_C) 

The rotorcraft hovers at the position you were at when entering this mode (position control). RC commands work the same as in HOVER mode. The vertical speed is set via fms (e.g. joystick).

AP_MODE_HOVER_Z_HOLD (H_ZH)

The rotorcraft hovers at the 3D position you were at when entering this mode (position and altitude control). RC commands work the same as in HOVER mode.
Your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

AP_MODE_NAV (NAV) 

Full navigation mode. The rotorcraft follows your flightplan.
If you have a valid RC signal, your throttle stick position still limits the max throttle authority unless disabled with NO_RC_THRUST_LIMIT.

AP_MODE_RC_DIRECT (RC_D) 

Safety pilot direct commands for helicopter.

AP_MODE_CARE_FREE_DIRECT (CF)

Same as AP_MODE_ATTITUDE_DIRECT, but the roll and pitch commands are based on the yaw angle when entering this mode.

XML Parameters

Mode

In the mode section you can set the autopilot modes associated with your 3-way mode switch on your RC.

File: conf/airframes/myrotorcraft.xml
  <section name="MODE" prefix="MODE_">
    <define name="MANUAL" value="AP_MODE_ATTITUDE_DIRECT" />
    <define name="AUTO1" value="AP_MODE_ATTITUDE_Z_HOLD" />
    <define name="AUTO2" value="AP_MODE_NAV" />
  </section>

Commands

The commands lists the abstract commands you need to control the aircraft. For most multicopter you just need:

File: conf/airframes/myrotorcraft.xml
  <commands>
    <axis name="PITCH" failsafe_value="0"/>
    <axis name="ROLL" failsafe_value="0"/>
    <axis name="YAW" failsafe_value="0" />
    <axis name="THRUST" failsafe_value="0"/>
  </commands>

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.

Motor Mixing

This section describes the "mixing" used for your particular multirotor configuration. This section is needed for all ESCs except "asctec_v1" wich do their mixing themselves.

Used since v5.0, for previous version see Supervision.

Differences with the older supervision (used prior to v4.9_devel-164-gdb0d004):
  • names: SUPERVISION -> MOTOR_MIXING
  • independent of the actuators, needs to be loaded in the subsystems and call in the command_laws section
  • internal values have pprz format (int16, between [-9600; 9600])
  • min and max are not needed, coming from the servos definition
  • trim are renamed with more explicit names

This subsystem takes roll, pitch, yaw and thrust commands as inputs and "mixes" them to get the final commands for your individual motors according to the layout of them. See RotorcraftMixing for the details behind this.

Note that after mixing the separate motor commands can "saturate", meaning you can't simply give negative thrust or more than the maximum. If a saturation is reached (desired motor command outside of possible MIN_MOTOR/MAX_MOTOR range), a saturation offset is applied to all motors in order to give attitude commands a higher priority than thrust. This offset is limited to MOTOR_MIXING_MAX_SATURATION_OFFSET (default is 10% of maximum command).

See also issue #385.

In firmware section:

File: conf/airframes/myrotorcraft.xml
  <firmware name="rotorcraft">
     ...
    <subsystem name="motor_mixing"/>
     ...
  </firmware>

Configuration of the motor mixing:

File: conf/airframes/myrotorcraft.xml
  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TRIM_ROLL" value="0"/>
    <define name="TRIM_PITCH" value="0"/>
    <define name="TRIM_YAW" value="0"/>
    <define name="MAX_SATURATION_OFFSET"	value="MAX_PPRZ/10"/>
    <define name="NB_MOTOR" value="4"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{  0  ,    0,  256, -256 }"/>
    <define name="PITCH_COEF"  value="{  256, -256,    0,    0 }"/>
    <define name="YAW_COEF"    value="{ -256, -256,  256,  256 }"/>
    <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
  </section>
TRIM_ROLL 
trim added to roll command
TRIM_PITCH 
trim added to pitch command
TRIM_YAW 
trim added to yaw command
MAX_SATURATION_OFFSET 
set at "MAX_PPRZ/10" by default
x_COEF 
roll/pitch/yaw/thrust coefficients, see RotorcraftMixing for details or the examples below

In command_laws section (placed after section MIXING):

File: conf/airframes/myrotorcraft.xml
  <command_laws>
    <call fun="motor_mixing_run(autopilot_motors_on, FALSE, values)"/>
    <set servo="FRONT" value="motor_mixing.commands[0]"/>
    <set servo="BACK"  value="motor_mixing.commands[1]"/>
    <set servo="RIGHT" value="motor_mixing.commands[2]"/>
    <set servo="LEFT"  value="motor_mixing.commands[3]"/>
  </command_laws>

Mixing Examples

Hint: If your rotors are spinning opposite to the direction shown in the picture, reverse signs in the YAW_COEF line.

Plus Cross 
Cross plus simple.png

Assuming that the order of motors, described in the "servos" section is FRONT, RIGHT, BACK, LEFT.

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="NB_MOTOR" value="4"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{    0, -256,    0,  256 }"/>
    <define name="PITCH_COEF"  value="{  256,    0, -256,    0 }"/>
    <define name="YAW_COEF"    value="{ -128,  128, -128,  128 }"/>
    <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
  </section>

This is equivalent to (available since v5.5_devel-602-g0129d3e):

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TYPE" value="QUAD_PLUS"/>
  </section>
Time Cross 
Cross time simple.png

Assuming that the order of motors, described in the "servos" section is NW, NE, SE, SW.

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="NB_MOTOR" value="4"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{  181, -181, -181,  181 }"/>
    <define name="PITCH_COEF"  value="{  181,  181, -181, -181 }"/>
    <define name="YAW_COEF"    value="{  128, -128,  128,  128 }"/>
    <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
  </section>

This is equivalent to (available since v5.5_devel-602-g0129d3e):

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TYPE" value="QUAD_X_CCW"/>
  </section>

This is equivalent to (available since v5.9_devel):

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TYPE" value="QUAD_X"/>
    <define name="REVERSE" value="true"/>
  </section>


Hex (Time Cross) 
Hex cross layout.png

Assuming that the order of motors, described in the "servos" section is FRONT_LEFT, FRONT_RIGHT, RIGHT, BACK_RIGHT, BACK_LEFT, LEFT.

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="NB_MOTOR" value="6"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{  128, -128,  -256,  -128,  128, 256 }"/>
    <define name="PITCH_COEF"  value="{  222,  222,     0,  -222, -222,   0 }"/>
    <define name="YAW_COEF"    value="{ -128,  128,  -128,   128, -128, 128 }"/>
    <define name="THRUST_COEF" value="{  256,  256,   256,   256,  256, 256 }"/>
  </section>

This is equivalent to (available since v5.5_devel-602-g0129d3e):

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TYPE" value="HEXA_X"/>
  </section>


Octo (time cross)
Octo.jpg
  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="NB_MOTOR" value="8"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{   98,  -98, -237, -237,  -98,   98,  237,  237 }"/>
    <define name="PITCH_COEF"  value="{  237,  237,   98,  -98, -237, -237,  -98,   98 }"/>
    <define name="YAW_COEF"    value="{ -128,  128, -128,  128, -128,  128, -128,  128 }"/>
    <define name="THRUST_COEF" value="{  256,  256,  256,  256,  256,  256,  256,  256 }"/>
  </section>

This is equivalent to (available since v5.5_devel-602-g0129d3e):

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TYPE" value="OCTO_X"/>
  </section>


Octo (plus cross)
Octo plus motor layout.png
  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="NB_MOTOR" value="8"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{    0, -181, -256, -181,    0,  181,  256,  181 }"/>
    <define name="PITCH_COEF"  value="{  256,  181,    0, -181, -256, -181,    0,  181 }"/>
    <define name="YAW_COEF"    value="{ -128,  128, -128,  128, -128,  128, -128,  128 }"/>
    <define name="THRUST_COEF" value="{  256,  256,  256,  256,  256,  256,  256,  256 }"/>
  </section>

This is equivalent to (available since v5.5_devel-602-g0129d3e):

  <section name="MIXING" prefix="MOTOR_MIXING_">
    <define name="TYPE" value="OCTO_PLUS"/>
  </section>


If you want to compute mixing for a special configuration, please see the RotorcraftMixing page.

Supervision

Prior to v5.0 motor mixing was called supervision. Click expand to see the details.

Valid before v4.9_devel-164-gdb0d004

  <section name="SUPERVISION" prefix="SUPERVISION_">
    <define name="STOP_MOTOR" value="0"/> <!-- this defaults to zero, set to a different value if needed, e.g. for pwm controllers -->
    <define name="MIN_MOTOR" value="3"/>
    <define name="MAX_MOTOR" value="200"/>
    <define name="TRIM_A" value="0"/>
    <define name="TRIM_E" value="0"/>
    <define name="TRIM_R" value="0"/>
    <define name="NB_MOTOR" value="4"/>
    <define name="SCALE" value="256"/>
    <define name="ROLL_COEF"   value="{  0  ,    0,  256, -256 }"/>
    <define name="PITCH_COEF"  value="{  256, -256,    0,    0 }"/>
    <define name="YAW_COEF"    value="{ -256, -256,  256,  256 }"/>
    <define name="THRUST_COEF" value="{  256,  256,  256,  256 }"/>
  </section>
STOP_MOTOR 
actuator specific command value to stop the motors
MIN_MOTOR 
actuator specific command value for idling motors
MAX_MOTOR 
actuator specific command value for maximum power
TRIM_A 
trim added to roll command
TRIM_E 
trim added to pitch command
TRIM_R 
trim added to yaw command
x_COEF 
roll/pitch/yaw/thrust coefficients, see RotorcraftMixing for details or the examples in the above Motor Mixing section

Guidance

There are two sets of parameters for guidance: vertical (altitude) and horizontal (position).

vertical guidance

File: conf/airframes/myrotorcraft.xml
  <section name="GUIDANCE_V" prefix="GUIDANCE_V_">
    <define name="HOVER_KP"    value="150"/>
    <define name="HOVER_KD"    value="80"/>
    <define name="HOVER_KI"    value="20"/>

    <!-- optional parameters -->
    <define name="NOMINAL_HOVER_THROTTLE" value="0.5"/>
    <define name="ADAPT_THROTTLE_ENABLED" value="TRUE"/>
    <define name="REF_MIN_ZD" value="-3.0" unit="m/s"/>
    <define name="REF_MAX_ZD" value="3.0" unit="m/s"/>
    <define name="MAX_RC_CLIMB_SPEED" value="-3.0" unit="m/s"/>
    <define name="MAX_RC_DESCENT_SPEED" value="3.0" unit="m/s"/>
  </section>
HOVER_K
PID parameters for vertical hover control loop
NOMINAL_HOVER_THROTTLE 
expected throttle percentage needed for hovering (default is 0.4 = 40%)
ADAPT_THROTTLE_ENABLED 
enable adaptive nominal hover throttle estimation (default is TRUE, set to FALSE to disable)
REF_MIN_ZD 
vertical speed reference lower limit (since z-down is positive -> max speed upwards) (default -3.0m/s)
REF_MAX_ZD 
vertical speed reference upper limit (since z-down is positive -> max speed downwards) (default 3.0m/s)
MAX_RC_CLIMB_SPEED 
climb speed at max RC input in RC_CLIMB mode (default is REF_MIN_ZD)
MAX_RC_DESCENT_SPEED 
descent speed at max RC input in RC_CLIMB mode (default is REF_MAX_ZD)

horizontal guidance

File: conf/airframes/myrotorcraft.xml
  <section name="GUIDANCE_H" prefix="GUIDANCE_H_">
    <define name="PGAIN" value="50"/>
    <define name="DGAIN" value="100"/>
    <define name="IGAIN" value="20"/>

    <!-- optional parameters -->
    <define name="AGAIN" value="0"/>
    <define name="VGAIN" value="0"/>

    <define name="MAX_BANK" value="20" unit="deg"/>
    <define name="USE_SPEED_REF" value="TRUE"/>
    <define name="REF_MAX_SPEED" value="5.0" unit="m/s"/>
    <define name="REF_MAX_ACCEL" value="5.66" unit="m/s2"/>
    <define name="REF_OMEGA" value="67" unit="deg"/>
    <define name="REF_ZETA" value="0.85"/>
    <define name="REF_TAU" value="0.5"/>
    <define name="APPROX_FORCE_BY_THRUST" value="FALSE"/>
  </section>
[PID]GAIN 
PID gains for horizontal control
AGAIN 
acceleration feedforward gain (default 0)
VGAIN 
velocity feedforward gain (default 0)
MAX_BANK 
maximum roll/pitch angle that is set from horizontal guidance (default 20deg, max 40deg)
USE_SPEED_REF 
since v5.1, give velocity commands via RC in GUIDANCE_H_MODE_HOVER (default: TRUE)
REF_MAX_SPEED 
maximum reference horizontal speed in m/s (default 5.0m/s)
REF_MAX_ACCEL 
maximum reference horizontal acceleration in m/s² (default tanf(RadOfDeg(30.))*9.81 = 5.66)
REF_OMEGA 
second order model natural frequency
REF_ZETA 
second order model damping
REF_TAU 
first order time constant
APPROX_FORCE_BY_THRUST 
try to better approximate force commands by taking thrust into account (default FALSE, set to TRUE to use it)

Simulation

See NPS (New Paparazzi Sim).