# Controllers in CRRCSim

## 0 General information

CRRCSim comes with a number of controllers which can be used to alter a model's behaviour. They can be controllers (in the meaning of closed loop control) or simply save flight data to files or modify input variables (the user's stick input) or something else. Controllers can receive keyboard input and write to the logging console window as well.

They are activated and adjusted by tweaking either the xml file which describes the model (currently only for multicopter models) or CRRCSims global configuration file. There is no GUI.

## 1 For users and model creators

As far as controllers are concerned, you become a "model creator" once you edit one, but in contrast to general "model creating" this is easy and might therefore be done by a user, too. For example, if you don't like the quadrocopter qc01 to limit throttle in flips automatically, simply remove the corresponding line from `qc01.xml`.

Some controllers can be used together with other controllers, some can not.

### 1.1 Controller: `ScaleThrottle`

This is not a real controller. The user's throttle input is in the range 0 .. 1. This controller alters throttle in the following way:

If throttle_in < `off`, throttle_out = 0.
Otherwise, throttle_out = `min` + (throttle_in - `off`) * `mul`

It is defined like that:
`<ScaleThrottle off="0.06" min="0.178" mul="0.54" />`

It can be combined with controllers not altering throttle and with `LimitFlipThrottle`.

### 1.2 Controller: `LimitFlipThrottle`

Again, this is no real controller. It only limits throttle, which is interesting for multicopters while flying loopings or flips.

If attitude is less than 60° from horizontal, throttle is not limited. At 90° it is limited to `max90`, at 180° (upside down) it is limited to `max180`.

It is defined like that:
`<LimitFlipThrottle max90="0.618" max180="0.3" />`

It can be combined with controllers not altering throttle and with `ScaleThrottle`.

### 1.3 Controller: `Omega`

To be used with multicopters, results in a rate controlled setup, so the sticks command how fast the copter rotates around roll/nick/yaw axis.

This controller is explained in "How to adjust multicopter parameters, multicopter model version 1" (`qc01.tex`), which is available online as pdf.

This one can not be combined with `MCopter01`.

### 1.4 Controller: `MCopter01`

To be used with multicopters, results in an attitude controlled setup for roll/nick and rate controlled for yaw axis.

          <MCopter01>
            <roll  scale="1.8"  kp="7"    kd="0.246" />
            <pitch scale="1.8"  kp="7"    kd="0.246" />
            <yaw   scale="-9.93" kp="0.352" ki="0.835" />
          </MCopter01>

The yaw controller is just like the `Omega` type (see above). For roll and pitch, the setpoint is `stick_input * scale` (in radians). Remember, stick input is -0.5 ... 0.5. `kp` is multiplied with the difference in attitude and gives the setpoint for the underlying rate controller. The difference in rotation rate is multiplied with `kd`. The result is the controllers output. Therefore, `kd` here is equivalent to `kp` of the `Omega` controller.

This one can not be combined with `Omega`.

### 1.5 Definition of global controllers

Add a section like the following to your global CRRCSim configuration file `crrcsim.xml`:

    <?xml version="1.0" ?>
    <crrcsimConfig version="2">
      <controllers>
        <ScaleThrottle off="0.06" min="0.178" mul="0.54" />
        <LimitFlipThrottle max90="0.618" max180="0.3" />
      </controllers>
      ...

The examples show the file's first two lines, too, to make clear that the controller-section has to be a child of `crrcsimConfig`.

## 2 For developers

Every controller inherits its interface from `Controller`, which is defined in `src/mod_cntrl/controller.h` and `.cpp`.

They are instantiated via `Controller::LoadList()` in the same files. It is up to the FDM to execute the controllers, even the global ones.

To see how everything is done, it may be best to take a look at the class `CRRC_AirplaneSim_MCopter01` in `src/mod_fdm/fdm_mcopter01/` and `Cntrl_MCopter01` as an example. If you are new to CRRCSim, you surely don't know `SimpleXMLTransfer`, which is the class used to read/write XML. This controller shows its basic usage and makes use of keyboard input and log output, too.

The current controller implementation is not perfect; for example a serial connection of controllers is not possible (while a parallel connection is). However I felt it to be powerful enough while being simple...

### 2.1 MNav

Before this controller framework was implemented, an interface to the "MNav" autopilot was implemented into CRRCSim. It was build as an input method (similar to joystick, transmitter or whatever).

Doing it like this has several drawbacks:

- In contrast to the controller framework, the input methods are not called with fixed timesteps, but dependent on screen refresh rate.
- How to do user input if the autopilot is an input method?
- A controller needs data from the flight dynamics model. In terms of clean APIs, an input method should not know about any FDM at all.

This subsection is not here to blame MNav but to explain why it is different from other controllers and why better not doing it like this. When it was implemented I, JWW, have not been interested and/or clever enough to say 'hey, don't do it like that'.

## 3 Ideas

The list of things which can be done with controllers is quite big, but here I want to list some more or less obvious ideas.

### 3.1 Recorder

This could be a useful global controller. By a keystroke it could start/stop logging the model's position/speed/acceleration to a file for playback.

### 3.2 Altitude controller

### 3.3 Thermalling controller

like this or the one described in

Das Thermikbuch fuer Modellflieger written by Markus Lisken and Ulf Gerber, Verlag fuer Technik und Handwerk, Baden-Baden.

### 3.4 Training helper

With a helicopter, a controller could take care of pitch, throttle and yaw while the pilot practises nick and roll. Note: the heli01-FDM doesn't execute local controllers yet, only global ones.