Rotorcraft Configuration

2013-08-02T07:08:44Z

12fen: /* Select your Board */

<categorytree style="float:right; clear:right; margin-left:1ex; border: 1px solid gray; padding: 0.7ex;" mode=pages>Airframe_Configuration</categorytree>
This page describes configuration options specific to the rotorcraft firmware in the [[Airframe_Configuration|airframe file]].
__TOC__
The airframe configuration file is located in <tt>conf/airframes</tt> and contains
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.

== Firmware and Hardware definitions ==

This is one example of a pretty standard quadcopter firmware definition:
{{Box Code|conf/airframes/myplane.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 ===
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:
"pc", "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", "lisa_m_1.0", "lisa_m_2.0", "navgo_1.0", "umarim_1.0"
{{Box Code|conf/airframes/myplane.xml|
<source lang="xml">
<firmware name="rotorcraft">
<target name="ap" board="lisa_m_2.0"/>
...
</firmware>
</source>
}}

=== Actuators ===
You have to specify which ESCs you have by adding the appropriate [[Subsystem/actuators|actuators subsystem.]]
{{Box Code|conf/airframes/myplane.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/myplane.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/myplane.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 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 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#Strips|GCS]] strip) :

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

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

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

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

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

; AP_MODE_NAV (NAV) :
Full navigation mode. The rotorcraft follows your flightplan.

; AP_MODE_RC_DIRECT (RC_D) :
Safety pilot direct commands for helicopter.

; AP_MODE_CARE_FREE_DIRECT (CF):
Safety pilot direct commands for helicopter, 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.
<source lang="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>
</source>

=== Commands ===

The <b><tt>commands</tt></b> lists the abstract commands you need to control the aircraft. For most multicopter you just need:
<source lang="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>
</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.

=== Supervision ===

Valid before '''v4.9_devel-164-gdb0d004'''

This section describes the "mixing" used for your particular multirotor configuration. This section is needed for "mkk" (mikrokopter), "pwm_supervision" and "asctecV2" controllers, as "asctecV1" do their mixing themselves.

<source lang="xml">
<section name="SUPERVISION" prefix="SUPERVISION_">
<define name="STOP_MOTOR" value="0"/> 
<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>
</source>

; ''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 below

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]]
Assuming that the order of motors, described in the "servos" section is FRONT, BACK, LEFT, RIGHT.
<source lang="xml">
<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 }"/>
</source>

; Time Cross : [[Image:cross_time_simple.png|200px]]
Assuming that the order of motors, described in the "servos" section is NE, SE, SW, NW.
<source lang="xml">
<define name="ROLL_COEF" value="{ -256, -256, 256, 256 }"/>
<define name="PITCH_COEF" value="{ 256, -256, -256, 256 }"/>
<define name="YAW_COEF" value="{ -256, 256, -256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256 }"/>
</source>

; Octo (time cross): [[Image:octo.jpg|border|200px]]
<source lang="xml">
<define name="ROLL_COEF" value="{ 106, -106, -256, -256, -106, 106, 256, 256 }"/>
<define name="PITCH_COEF" value="{ 256, 256, 106, -106, -256, -256, -106, 106 }"/>
<define name="YAW_COEF" value="{ -256, 256, -256, 256, -256, 256, -256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256, 256, 256, 256, 256 }"/>
</source>

; Octo (plus cross): rotor 1 on x-axis (image anyone?)
<source lang="xml">
<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="{ -256, 256, -256, 256, -256, 256, -256, 256 }"/>
<define name="THRUST_COEF" value="{ 256, 256, 256, 256, 256, 256, 256, 256 }"/>
</source>

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

=== Motor Mixing ===

Valid after '''v4.9_devel-164-gdb0d004''': Supervision has been renamed Motor_mixing

The main difference with the above section are:
* 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

In '''firmware''' section:
<source lang="xml">
<subsystem name="motor_mixing"/>
</source>

Configuration of the motor mixing:
<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="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>

; ''TRIM_ROLL'' : trim added to roll command
; ''TRIM_PITCH'' : trim added to pitch command
; ''TRIM_YAW'' : trim added to yaw command
; x''_COEF'' : roll/pitch/yaw/thrust coefficients, see [[RotorcraftMixing]] for details or the examples above

In '''command_laws''' section (placed after section MIXING):
<source lang="xml">
<command_laws>
<call fun="motor_mixing_run(autopilot_motors_on, FALSE, values)"/>
<set servo="FRONT" value="motor_mixing.commands[SERVO_FRONT]/>
<set servo="BACK" value="motor_mixing.commands[SERVO_BACK]/>
<set servo="RIGHT" value="motor_mixing.commands[SERVO_RIGHT]/>
<set servo="LEFT" value="motor_mixing.commands[SERVO_LEFT]/>
</command_laws>
</source>

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

<source lang="xml">
<section name="SIMULATOR" prefix="NPS_">
<define name="ACTUATOR_NAMES" value="{"front_motor", "back_motor", "right_motor", "left_motor"}" />
<define name="INITIAL_CONDITITONS" value=""reset00"" />
<define name="SENSORS_PARAMS" value=""nps_sensors_params_default.h"" />
</section>
</source>

Hint: If you get a different start position then the flightplan describes, that is because there is maybe a Lat long in your reset00.xml. start your simulated INITIAL_CONDITITONS with an own reset.XML.

[[Category:Airframe_Configuration]] [[Category:User_Documentation]] [[Category:Rotorcraft]]

PaparazziUAV - User contributions [en]

Rotorcraft Configuration