# Helicopter parameters in xml, helicopter model version 1

## 0 About this document

This document should not provide examples. Please take a look at the files you got when downloading/installing CRRCSim. `heli.xml` should provide an example for every parameter which can be defined.

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

### 0.1 Changes

16.09.2008 | J. W. Wulf | First version.
02.10.2008 | J. W. Wulf | Explained new parameters.

## 1 General information

The file format and its structure is very similar to the one used for fixed wing airplanes, see its description. Because of this, not every part of the file will be explained in this document. To understand it, you need to read 'General information' and 'Units' of the former document at least.

### 1.1 Axis mapping

throttle controls climb
rudder controls yaw
aileron controls roll
elevator controls pitch

## 2 Ground effect: section `GroundEffect`

`GroundEffect.dist.mul` is a value bigger than zero which tells how much stronger disturbances are near ground.

## 3 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. Example:

              <CG units="0" x="-0.2234252" y="0" z="-0.043131893" />

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

## 4 Configuration: section `config`

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

### 4.1 Subsection `mass_inertia`

This is the same as described here.

### 4.2 Subsection `aero`

Set `aero.coaxial="1"` if the helicopter is of coaxial type. In this case some parameters are automatically set to zero and the main rotor does not create a yaw moment.

There are subsections `yaw`, `roll` and `pitch`, which are similar.
Every one of those subsections has an attribute `ctrl`, which states rotational velocity around that axis at full stick input in radians/s (so 2*3.1416 means one revolution per second).
There is an attribute called `damp` which dampens rotation around that axis -- generally higher values make the heli easier to fly. Damping of `roll` and `pitch` axis is fixed, but `yaw` axis is different: damping is `yaw.damp` with zero stick input and decreases to `yaw.damp * yaw.damp_min_rel` at full stick input.
The attribute `dist` describes disturbances around that axis; bigger values meaning more disturbance.

If you describe a helicopter with a 'heading hold' or 'heading lock' gyro, add an attribute `yaw.HeadingHold` with a value greater than zero, which describes the gain of the heading hold controller.

The whole `pitch` subsection can be omitted; values will be taken from the `roll` subsection in this case.

`yaw.off`: yaw offset for non-coaxial helicopters without heading hold.
`yaw.cp_to_yaw`: mixes collective pitch/throttle to yaw
`yaw.moment_mul`: set it to zero to not simulate main rotor torque, set it to one to simulate it realistically, or set it to anything in between.

`roll.ForwardToRoll`: when flying forward/sidewards/any direction, there is a 90°-coupling caused by the difference in lift of the rotor. It is automatically set to zero for coaxial type.

`cp.ctrl`: control throw for collective pitch type.
`cp.off`: pitch offset for collective pitch type, throttle offset for fixed pitch type.
`cp.auto_off`: Is assumed to be `1` if not defined. If it is equal to one, cp.off will automatically be set so that the heli will lift from ground as your command more pitch or throttle than neutral stick. So you only need to set `cp.off` in case you don't like this automatic setting.

`power.automagic.F` (in case of fixed type) is similar to pitch control throw in case of collective pitch type.

`speed.damp`: higher values make the model easier to fly

`yaw.vane` and `pitch.vane` are set to bigger than zero to simulate the weather vane effect caused by horizontal and vertical stabilizers at the tail.

### 4.3 Power system: section `power`

Only the main rotor is modelled. This section only differs from the airplane-style power section by the optional attribute `fixed_pitch` which is defined to "1" if this helicopter is a fixed pitch (in contrast to collective pitch) type.