# Airplanes in xml

## 0 About this document

This document is not complete yet. It may be inaccurate or wrong, too.

This document should not provide examples. Please take a look at the files you got when downloading/installing CRRCSim. At the time of this writing only `superzagi.xml` uses more features than other files.

You need to know basics about xml files: they are structured text. Whitespace and line breaks do not matter in most places. Just take a look at the examples and you will understand.

The files can be edited using a text editor. There are lots of them. Use something like notepad, vi, emacs, joe...

## 1 General information

The first part of the file should be quite easy to understand. It contains a description of the model and a changelog. Whenever you edit such a file, please add a new `change` section and fill in what is needed. The example below shows a template.

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <CRRCSim_airplane version="2">
      <description>
        <en>
            This plane has been automatically converted from superzagi.air.
            Please update this text if you know more about it.
        </en>
      </description>
      <changelog>
        <change>
          <date>Unknown</date>
          <author>CRRCSim 0.9.5</author>
          <en>Automatically converted from .air file.</en>
        </change>
        <change>
          <date>Please write date.</date>
          <author>Please write your name and email.</author>
          <en>Please write down what you changed.</en>
        </change>
      </changelog>

Every text is written in english, so it is enclosed in `<en> </en>`. If you want to add something in italian for example, you should enclosed it in `<it> </it>`.

## 2 Units

Some sections have an attribute `units`, which tells which units are used for the values in that section. Take a look at the tables below. There is a file called non_SI_units.txt in the CRRCSim distribution which explains some strange units.

## 3 Aerodynamics: section `aero`

### 3.1 Subsection `ref`

The following table explains attributes in that subsection.

Name | Description | units=0 | units=1
--- | --- | --- | ---
chord | reference chord | ft | m
span | reference span | ft | m
area | reference area | ft^2 | m^2
speed | reference speed for Re-scaling of CD_prof | ft/s | m/s

### 3.2 Subsection `misc`

Name | Description | units=0 | units=1
--- | --- | --- | ---
Alpha_0 | baseline alpha | rad | rad
eta_loc | eta_loc for stall model | 1 | 1
CG_arm | CG_arm for stall model, see below. | 1 | 1
span_eff | span efficiency: Effective span, 0.95 for most planes, 0.85 flying wing. | 1 | 1

#### 3.2.1 `CG_arm`

Email from Mark Drela, 10.01.2006:

The stall model computes the values (dCL_left, dCL_cent, dCL_right) which represent the changes in CL due to stall.
To get the stall effect on the Cm, these are multiplied by the length CG_arm, which is the distance between the CG and the effective point of application of dCL:
dCm_stall = (0.25*dCL_left + 0.5*dCL_cent + 0.25*dCL_right)*CG_arm;

The typical value CG_arm = 0.25 means that the point of application of the averaged dCL is 0.25*chord ahead of the CG.

This CG_arm can be deduced from airfoil data. If dCL and dCm are the changes due to stall, the implied CG_arm is
CG_arm = dCm/dCL
Typically, both dCm and dCL will be negative, so CG_arm is positive.

You can also adjust CG_arm to get a realistic simulator pitch response due to stall. The larger CG_arm is, the more pitch-down you will get during stall.

### 3.3 Subsection `m`

Name | Description | units=0 | units=1
--- | --- | --- | ---
Cm_0 | baseline Cm at Alpha_0 | 1 | 1
Cm_a | pitch-moment / alpha (pitch stability) | 1 | 1
Cm_q | pitch-moment / pitch-rate (pitch damping) | 1 | 1
Cm_de | pitch-moment / elevator | 1 | 1

### 3.4 Subsection `lift`

Name | Description | units=0 | units=1
--- | --- | --- | ---
CL_0 | baseline CL at Alpha_0 | 1 | 1
CL_max | positive stall limit | 1 | 1
CL_min | negative stall limit | 1 | 1
CL_a | lift slope; lift-force / alpha, round about 2 pi / (1 + 2/AR) | 1 | 1
CL_q | lift-force / pitch-rate | 1 | 1
CL_de | lift-force / elevator | 1 | 1
CL_drop | CL drop during stall break | 1 | 1
CL_CD0 | CL at minimum profile CD: 0.30 for 7037, 0.15 MH32, 0.0 RG15, AGxx, power | 1 | 1

### 3.5 Subsection `drag`

Name | Description | units=0 | units=1
--- | --- | --- | ---
CD_prof | profile CD at U_ref | 1 | 1
Uexp_CD | CD Re-scaling exponent; scales profile CD with Reynolds number via simple power law | 1 | 1
CD_stall | drag coeff. during stalling | 1 | 1
CD_CLsq | d(CD)/d(CL^2), curvature of parabolic profile polar: 0.01 composites, 0.015 saggy ships, 0.02 beat up ship | 1 | 1
CD_AIsq | drag due to aileron deflection. d(CD)/d(aileron^2) , curvature of ail. CD influence: 0.01/(max_aileron)^2 | 1 | 1
CD_ELsq | drag due to elevon deflection. d(CD)/d(elevator^2), curvature of ele. CD influence: 0.01/(max_elevator)^2 for Zagi otherwise 0 | 1 | 1

### 3.6 Subsection `Y`

Name | Description | units=0 | units=1
--- | --- | --- | ---
CY_b | side-force / sideslip | 1 | 1
CY_p | side-force / roll-rate | 1 | 1
CY_r | side-force / yaw-rate | 1 | 1
CY_dr | side-force / rudder | 1 | 1
CY_da | side-force / aileron | 1 | 1

### 3.7 Subsection `l`

Name | Description | units=0 | units=1
--- | --- | --- | ---
Cl_b | roll-moment / sideslip (crucial for rudder-only turns) | 1 | 1
Cl_p | roll-moment / roll-rate (roll damping) | 1 | 1
Cl_r | roll-moment / yaw-rate | 1 | 1
Cl_dr | roll-moment / rudder | 1 | 1
Cl_da | roll-moment / aileron | 1 | 1

### 3.8 Subsection `n`

Name | Description | units=0 | units=1
--- | --- | --- | ---
Cn_b | yaw-moment / sideslip (yaw stability) | 1 | 1
Cn_p | yaw-moment / roll-rate (yaw-roll coupling) | 1 | 1
Cn_r | yaw-moment / yaw-rate (yaw damping) | 1 | 1
Cn_dr | yaw-moment / rudder | 1 | 1
Cn_da | yaw-moment / aileron | 1 | 1

## 4 Configuration: section `config`

There can be more than one configuration for an airplane, so there may be several `config` sections. Because of this, each `config` needs a description.

      <config version="1">
        <descr_long>
          <en> Powerful motor which makes this config heavy, too.</en>
        </descr_long>
        <descr_short>
          <en>powerful and heavy</en>
        </descr_short>

### 4.1 Subsection `mass_inertia`

Name | Description | units=0 | units=1
--- | --- | --- | ---
Mass | Mass of airplane | slug | kg
I_xx |  | slug ft^2 | kg m^2
I_yy |  | slug ft^2 | kg m^2
I_zz |  | slug ft^2 | kg m^2
I_xz |  | slug ft^2 | kg m^2

### 4.2 Subsection `sound`

The `sound` subsection contains the description of the sound samples used for this airplane. Each sample is described in a `sample` subsubsection.

#### 4.2.1 Subsubsection `sample`

Name | Description | units=0 | units=1
--- | --- | --- | ---
filename | name of file for engine sound | - | -
type | Type of sound: 0 glow engine, 1 electric engine, 2 glider sound | - | -
pitchfactor | This number converts from speed of propeller to pitch of engine sound. | s | s
maxvolume | The maximum sample volume (0.0 ... 1.0). The loudest sample should be set to 1.0. | 1 | 1
v_min | Only for type=2: minimal velocity (relative to the airplane's "neutral" velocity) at which the sound can be heard | 1 | 1
v_max | Only for type=2: velocity (relative to the airplane's "neutral" velocity) at which the sound reaches maximum volume. | 1 | 1
dist_max | Only for type=2: distance at which the sound reaches the minimum volume | ft | m

### 4.3 Subsection `power`

There is a separate documentation (`power_propulsion.html`) which explains the power and propulsion system.

## 5 Graphics: section `graphics`

There can be more than one graphical representation for an airplane, so there may be several `graphics` sections. Because of this, each `graphics` needs a description.

      <graphics version="1" model="zagi.ac" >
        <descr_long>
          <en>Automatically converted from superzagi.air.</en>
        </descr_long>
        <descr_short>
          <en>default</en>
        </descr_short>

Currently you only need to specify the name of the graphics file.

## 6 Hard points and wheels: section `wheels`

This section contains a number of entries, each of them describing one hard point on the airplane. The caster angle is specified with respect to the plane body's z-axis, a value of zero means that the wheel is oriented straight ahead (which should be the case for most gears).

Name | Description | units=0 | units=1
--- | --- | --- | ---
percent_brake | Percentage of max braking applied initially | 1 | 1
caster_angle_rad | wheel angle | rad | rad

### 6.1 Subsection `pos`

Position of hard point in body axes with regard to center of gravity. Unit is feet (`units="0"`) or meters (`units="1"`). x positive forward, y positive right, z positive down.

Remark: 3D modelling tools sometimes use other coordinate system orientations. In this case the coordinates of a hard point have to be converted into the CRRCsim coordinate system. Here's an example for AC3D:

Axis in XML file | Axis in AC3D
--- | ---
+X | +Z
+Y | -X
+Z | -Y

This means that a point in AC3D at X = -3.28, Y = 0.55, Z = -0.37 (this could be the right wingtip of a 2m sailplane) will result in the following position tag:

        <pos x="-0.37" y="3.28" z="-0.55" />

### 6.2 Subsection `spring`

This subsection defines the springiness of the hardpoint, e.g. if a collision of this hardpoint with ground makes the plane bounce or is damped by the hardpoint's flexibility.

Name | Description | units=0 | units=1
--- | --- | --- | ---
constant | spring constant, has to be positive | slug / s^2 = lbf / ft | N/m
damping | damping, has to be positive | slug / s = lbf / (ft/s) | N/(m/s)

### 6.3 Subsection `steering`

In this subsection a mapping of the hardpoint to an R/C channel can be defined. Possible values for the "mapping" parameter are "NOTHING" (which makes this subsection redundant), "RUDDER", "AILERON" or "ELEVATOR". By specifying a negative value for max_angle the coupling from the control input to the wheel will be reversed. A positive angle should be correct for a tail wheel while a steerable nose wheel usually needs a negative angle.

Name | Description | units=0 | units=1
--- | --- | --- | ---
mapping | symbolic name of the R/C channel | - | -
max_angle | deflection of the wheel at full control input | rad | rad

Example: this maps a nose wheel to the rudder channel, giving 20 degrees (= 0.349 radians) of wheel deflection at full rudder input.

            <steering mapping="RUDDER" max_angle="-0.349" />

## 7 Center of gravity: section `CG`

Position of center of gravity in body axes with regard to coordinates used by `wheels` and the 3D graphics file.
Unit is feet (`units="0"`) or meters (`units="1"`). x positive forward, y positive right, z positive down.

This section and values do not have to exist, it is optional. However, it gives you the following advantage: There is no need to create the 3D model (and the points in the `wheels` section) around the center of gravity. You can use any reference point and give the position of the CG using your coordinates in this section.

This also makes it possible to change the location of the CG without changing the 3D model and `wheels`.

You can visually check the position of the CG using test mode, as the airplane rotates around the center of gravity (given that throttle=0).

## 8 Animated parts: section `animations`

This section contains information needed to animate parts of the model, e.g. to move the control surfaces according to stick input. It is optional to define animations for a model; however it is strongly recommended to make use of this feature because it adds much to the appearance of a model.

To animate a part of a 3D model it is required that this part is modelled as an independent object in the 3D model file, and that the object has a unique name. A proper 3D modelling tool should allow one to group surfaces to objects and give them names, so this shouldn't be a problem.

The `<animations>` section contains one `<animation>` subsection per animated object. The `<animation>` tag must contain a `type` attribute to define the kind of animation that should be created. Currently only the type `ControlSurface` is implemented.

Name | Description | unit
--- | --- | ---
type | kind of animation | -

### 8.1 Animation type `ControlSurface`

This kind of animation is used to move an object of the 3D model according to stick input.

#### 8.1.1 Subsection `object`

This subsection defines the object to which the animation is applied and the maximum amount of movement.

Name | Description | unit
--- | --- | ---
name | name of the object in the 3D model | -
max_angle | control surface deflection at full control input | rad

#### 8.1.2 Subsection `control`

This subsection defines how the surface interacts with the input from the controller. `mapping` can be set to one of `RUDDER`, `ELEVATOR`, `AILERON` or `THROTTLE`. There can be more than one `control` section for a surface, e.g. there will be a mapping to `ELEVATOR` and `AILERON` if the model has elevon controls (aka "delta-mix"). The `gain` setting determines the relationship of the control input to the surface deflection. A `gain` value of `1.0` means that the surface will travel the full `max_angle` from the `object` section above if the associated control is moved to its extents. Negative `gain` values will reverse the surface movement.

Name | Description | unit
--- | --- | ---
mapping | symbolic name of the R/C channel | -
gain | control surface deflection at full control input | -

#### 8.1.3 Subsection `hinge`

To define the rotation axis of the control surface it is mandatory to define exactly two `<hinge>` subsections. The rotation will occur around an imaginary axis from the first to the second hinge, and the direction of the rotation can be determined by applying the right-hand rule to this axis. The X/Y/Z values are kind of unit-less ("OpenGL"-units). They can be determined by selecting a vertex close to the hinge point in the 3D modelling tool and then transforming the displayed vertex coordinates into the coordinate system described below (same as with the `<wheel>` positions described above).

Name | Description | unit
--- | --- | ---
x | X coordinate (positive forward) | -
y | Y coordinate (positive right) | -
z | Z coordinate (positive down) | -

This is an example for the animation of left and right aileron on an 1.6m aerobatics model, giving 20 degrees (= 0.349 radians) of control surface deflection at full aileron input, assuming that the aileron objects of the 3D model are called `ail_right` and `ail_left`:

          <animations>
            <animation type="ControlSurface">
              <object name="ail_right" max_angle="0.349" />
              <control mapping="AILERON" gain="-1.0" />
              <hinge x="-0.56" y="0.63" z="0.03" />
              <hinge x="-2.64" y="0.40" z="0.02" />
            </animation>
            <animation type="ControlSurface">
              <object name="ail_left" max_angle="0.349" />
              <control mapping="AILERON" gain="-1.0" />
              <hinge x="0.56" y="0.63" z="0.03" />
              <hinge x="2.64" y="0.40" z="0.02" />
            </animation>
          </animations>

## 9 Launch presets: section `launch`

This section is optional. It contains launch presets that will be shown in the launch dialog of the GUI if this airplane is currently selected. The <launch> section shall only contain <preset> tags, each one containing the attributes that describe the launch process like in CRRCsim's main configuration file.

Name | Description | unit
--- | --- | ---
name_en | name of the preset for the GUI dialog | -
altitude | launch altitude above ground | ft
velocity_rel | velocity relative to the trimmed flight velocity | -
angle | launch angle (+ means "nose up") | rad
sal | simulate side-arm-launch (0: no, 1: yes) | -

Example:

          <launch>
            <preset name_en="Gap65 default (ground)" altitude="0" velocity_rel="0" angle="0.22" sal="0" />
          </launch>