# 1 Introduction

This file explains the power and propulsion system of CRRCSim to enable you to create your own configurations.

Most things here are taken from the developers documentation, which is extracted from the source code using a tool called doxygen. It may happen that this document is out of date, but the documentation in the source code is not.

## 1.1 History

23.09.2005 | Jens Wilhelm Wulf | The system has just been implemented into CVS. Took most texts from source code to put this document together.
26.02.2009 | Jens Wilhelm Wulf | update, added examples
22.10.2009 | Jens Wilhelm Wulf | downthrust update
08.12.2014 | Luca Gasparini | rightthrust & prop tuning factors

# 2 Overview

This class manages everything related to battery, engine, propeller. Throughout this class (and the classes used by it) the SI unit system is used (with a small number of exceptions).

Values used are:

- lengths `H` and `D` in m
- rotational velocity `omega` in rad/s
- rotational velocity `n` in 1/s
- linear velocity `V` in m/s
- Torque `M` in Nm
- Force/thrust `F` in N
- Inertia `J` in kg m^2
- Resistance `R` in Ohm
- Current `I` in A
- Voltage `U` in V
- Capacity `C` in Ah

One airplane needs exactly one Power system, even if the latter is empty. The Power system for one airplane can contain the following items, which are organized in a tree-like structure which represents mechanical and electrical connections.

- Battery
  At least one is needed, unless you have a glider.
- Shaft
  At least one is needed. Every engine/propeller is (mechanically) connected to a shaft. One or more shafts are connected to a battery. This is what electrically relates engines to batteries.
- Engine
  One or more engines can be connected to a shaft.
- Propeller or SimpleThrust
  One or more of them can be connected to a shaft.

This is an example setup (without gearboxes):

The system is configured using a description in xml. The connections mentioned above are given by the structure of xml elements. Here's an example of a system with one battery; there is a gearbox with two engines driving one prop.

       <power>
         <battery filename="nicd12_30" throttle_min="0">
           <shaft J="2E-6" brake="0">
             <engine filename="astro_cobalt_10">
               <gearing J="0" i="2.5" />
             </engine>
             <engine filename="astro_cobalt_10">
               <gearing J="0" i="2.5" />
             </engine>
             <propeller D="0.3" H="0.2" J="3E-6" n_fold="-1" />
           </shaft>
         </battery>
       </power>

Take a look at the individual items for details of their description.

If you don't want to define every single item of the system, you can take the easy way. Use a description like this:

         <automagic F="12" V="15.8">
          <battery throttle_min="0">
            <automagic T="420" />
            <shaft J="0" brake="1">
              <propeller D="0.243" H="0.17" J="0" n_fold="5" />
              <engine>
                <automagic omega_p="2827" eta_opt="0.78" eta="0.7" />
              </engine>
            </shaft>
          </battery>
        </automagic>

This will create a power system which delivers a thrust of `F=12 N` at a velocity of `V=15.8 m/s`. The battery will be designed to last `T=420 s`. You also need to fill in the dimensions of the propeller. It is best to take everything else as shown in the example.

If you use this automagic way of creating the system, the program will output the configuration it calculated from your values to give you a starting point for fine grained tunings.

# 3 Elements of a power system

## 3.1 Battery

This class models a battery.

A battery has an initial capacity. While current is being drawn from the battery, the capacity left becomes smaller. Once nothing is left, its voltage is set to zero. The battery is definitely empty in this case.

Apart from this behaviour, the voltage is modelled as `U = U_0(C, C_0) - R_I * I`. `I` is the current drawn from the battery.

The no-load-voltage `U_0` is a function of the capacity left. It is read from a table.

If the battery voltage drops below `U_off`, the voltage is set to zero and locked. By setting the throttle command to zero, it can be unlocked again. This is similar to what speed controllers do.

Set `throttle_min` to > 0 to model a glow engine which can only be started once and runs at that minimum throttle afterwards.

The xml configuration of a battery looks like this:

       <battery C="1.2" U_0="9.6" U_off="7" R_I="10E-3" throttle_min="0">
         <U_0rel>
           1.05;
           0.95;
           0.90;
           0.85;
           0.85;
           0.85;
           0.85;
           0.85;
           0.85;
           0.80;
           0.75;
           0.70;
         </U_0rel>
         ...shafts connected to this battery...
       </battery>

In contrast to other values in the power system, the initial capacity `C` is given in Ah, not As.

It is possible to read the parameters of a battery from a separate file. In this case use something like

       <battery filename="nicd12_30" throttle_min="0">

instead of writing down the parameters directly. The system will try to load a file `./models/battery/nicd12_30.xml` which might look like this:

       <?xml version="1.0"?>

       <battery C="3.0" U_0="12" U_off="9" R_I="10E-3">
         <U_0rel>
           1.05;
           0.95;
           0.90;
           0.85;
           0.85;
           0.85;
           0.85;
           0.85;
           0.85;
           0.80;
           0.75;
           0.70;
         </U_0rel>
       </battery>

In both cases, the section `U_0rel` is a table showing the no-load-voltage `U_0` as a function of the capacity left. The table does not contain absolute values. In this example, `U_0` at full charge is `1.05 * 12 V`. It does not matter how many entries this table contains; they are assumed to be at equal distances as far as the capacity left is concerned.

## 3.2 Shaft

This class models a shaft to which engines and propellers (any number of them) are connected.

For folding props a speed brake is needed, but it didn't work as expected in Engine. Therefore the simulation of the brake was ripped out of the engine (where the real model proved to be too weak) and has been put into the shaft. So if the brake is enabled, it will force the shaft to stop rotating as soon as the throttle command is zero.

Example for an xml description:

       <shaft J="0.0E-5" brake="1">
        ...engines and propellers...
       </shaft>

`J` is the inertia of the shaft; if `brake` is not zero, this shaft will stop rotating as soon as the throttle command is zero. This is needed for folding props.

## 3.3 Gearing

This class models a gearing which connects engines/propellers to a shaft. Everything connected to a shaft must be a subclass of it.

The xml description of a gearing must be written inside of the element which is connected to the shaft by the gearbox. It looks like this:

         <gearing i="1.13" J="0" />

A gearbox might have an inertia `J` which is not zero. This inertia is the value seen by the shaft. The inertia of the propeller/engine is translated to the shaft automatically.

Given `omega` is the speed of the shaft, `i*omega` is the speed of the device which is connected to the shaft using this gearing.

## 3.4 Engine

This class models a direct current motor. The model is quite realistic. However, modeling the emc brake proved to be not strong enough to stop a Propeller in flight. But this is a problem of the Propeller I think. The brake is modelled by Shaft now.

The xml configuration of an engine looks like this (without gearbox to shaft):

       <engine k_M="4.3e-03" R_I="0.185" J_M="1.79e-05" I_0="1.01" />

Example for an xml description, connection to shaft via a gearbox:

       <engine k_M="4.3e-03" R_I="0.185" J_M="1.79e-05" I_0="1.01" >
         <gearing i="1.13" J="0" />
       </engine>

The inertia `J` of the engine is translated to the shaft automatically. The inertia `J` of the gearing is the value seen by the shaft.

See Gearing for a description of a gearbox.

It is possible to read the parameters of a engine from a separate file. In this case use something like

       <engine filename="astro_cobalt"/>

       <engine filename="astro_cobalt">
         <gearing i="1.13" J="0" />
       </engine>

instead of writing down the parameters directly. The system will try to load a file `./models/engine/astro_cobalt.xml` which might look like this:

       <?xml version="1.0"?>
       <!--
        Astro Cobalt 05 at 10 V

        Data taken from
        Retzbach, Ludwig: Ratgeber Elektroflug, Neckar Verlag, 1991.

        M_r = 1.15E-2; // Nm
        I_0 = M_r/k_M = 2.74A

        J_M is just guessed.

        -->

       <engine R_I="0.08" k_M="0.42E-2" I_0="2.74" J_M="1.6E-6" >
       </engine>

Given `U_K` is the voltage applied to the engine and omega is its speed, it will draw a current of `I_M = (U_K - omega * k_M) / R_I` and will apply a torque to the gearing which is `M_M = k_M * (I_M - I_0)`.

Finding a complete parameter set for a specific engine can be impossible, but luckily the parameters can be calculated from measured data. Given the current draw for the idle engine and voltage, current draw and speed values for at least two different load points (one of them may be the idle point as well), all electric parameters can be calculated.

A worked example: Speed 400 with flux ring

For one model I wanted to simulate a Speed 400 (aka Mabuchi RS-380 PH) with an additional flux ring. I found an Excel sheet on the Internet that contained motor data for exactly this engine:

        U_K [V]  I_M [A]   n [rpm]  n [1/s]   remark
        -----------------------------------------------------------------------------------
         7.96     0.94     22290    371.5     idle, n = n_0, U_K = U_0 and I_M = I_0
         7.37     7.47     13740    229       near max. load

J_M, the engine's rotor's inertia, can be found in the manufacturer's data sheet, or it has to be guessed. I assumed 1.0E-6 for the Speed 400. You can estimate it by regarding the rotor as a solid iron cylinder of mass m (in kg) and diameter d (in m) using the formula

       J_M = 0.5 * m * d^2 / 4

All this resulted in the following engine file:

       <?xml version="1.0"?>
       <!--
         Mabuchi 380 (aka Speed 400) with additional flux ring

         J_M is just guessed.
       -->

        <engine_dcm  J_M="1.0E-6" calc="1">
          <data>
            <data U_K="7.96" I_M="0.94" n="371.5" />
            <data U_K="7.37" I_M="7.47" n="229.0" />
          </data>
          <data_idle>
            <data I_M="0.94" />
          </data_idle>
        </engine_dcm>

There must be at least two entries with different load points, but if you have more, just supply all of them.

If you only have one set of idle data, the voltage does not matter. But if you can provide several values for idle current at a certain voltage, do so. Replace

          <data_idle>
            <data I_M="0.94" />
          </data_idle>

by something like

          <data_idle>
            <data U_K="7.96" I_M="0.94" />
            <data U_K="6.13" I_M="0.87" />
            <data U_K="5.07" I_M="0.82" />
          </data_idle>

## 3.5 Propeller

This class models a propeller. It is far from perfect, so you can't use it to optimize your real airplane, but it should be good enough to achieve the feeling of a realistic propeller in the simulation.

The Propeller can be configured to be a folding prop, which folds as soon as it rotates slower than `omega_fold`. From the xml config, `n_fold` is read and converted using `(omega_fold = n_fold * 2 * pi)`. If a prop is folded, it will not create a positive torque to the Shaft (and keep it rotating) and will not create drag to the airplane. If `n_fold` is negative, this is not a folding prop.

Propeller rotational direction is usually clockwise seen from the back (pressure side), however it can be changed setting `rotation` to -1.

If your model needs downthrust or rightthrust, you can tell the simulation about the propeller's position (relative to center of gravity in body axis) and angle of downthrust and rightthrust (positive down and to the right, in degrees). Note however that position parameters shall not be used for helicopters and multicopters, since in this cases propeller simulation is only applied to compute axial thrust and torque. Additionally, for multicopters specific parameters exist to define rotational direction of each prop, thus propeller's "rotation" parameter shall not be used.

Prop performance for each model can be tuned to better suit real life behaviour with following scale factors:

- `F_V0_scale`
  scale factor for static thrust (default 1).
- `V_F0_scale`
  scale factor for flying speed at which thrust becomes zero (default 1).
- `P_scale`
  scale factor for absorbed power (default 1).
- `Pfactor_scale`
  scale factor for so-called P-factor pitch/yaw moment effect (default 1).

Formulas used: see homepage of Martin Hepperle, http://www.mh-aerotools.de/ plus additional static thrust correction factor taken from Gabriel Staples article

Example for an xml description for direct connection to shaft:

       <propeller D="0.2" H="0.14" J="0" n_fold="5"  />

Example for an xml description, connection to shaft via a gearbox:

       <propeller D="0.2" H="0.14" J="0" n_fold="5"  >
         <gearing i="1.13" J="0" />
       </propeller>

Example including rotation, position and downthrust/rightthrust:

       <propeller D="0.2" H="0.14" J="0" n_fold="5" rotation="1" >
         <pos x="0.22" z="0" downthrust="2" rightthrust="2" />
       </propeller>

Example including tuning factors:

       <propeller D="0.2" H="0.14" J="0" n_fold="5"  >
         <tune F_V0_scale="1.1" V_F0_scale="1" P_scale="1" Pfactor_scale="1" />
       </propeller>

The inertia `J` of the propeller is translated to the shaft automatically. The inertia `J` of the gearing is the value seen by the shaft.

See Gearing for a description of a gearbox.

It is possible to read the parameters of a propeller from a separate file. In this case use something like

       <propeller filename="10x7" />

       <propeller filename="10x7"  >
         <gearing i="1.13" J="0" />
       </propeller>

instead of writing down the parameters directly. The system will try to load a file `./models/propeller/10x7.xml` which might look like this:

       <?xml version="1.0"?>
       <!--
          This is just a sample.

          Units are SI!
          H, D: m
          J:    kg m^2
        -->

       <propeller H="13E-2" D="17E-2" J="1.2E-6" n_fold="5">
       </propeller>

The parameters regarding position and tuning are not in the propeller file, as they are not parameters which describe the propeller itself, but how the propeller is mounted and interacts with the airframe.

## 3.6 SimpleThrust

This is a very simple propeller to model CRRCSims first engine: thrust, no matter at which airspeed.

This simple propeller is connected to a shaft via some gearing. The gearing is described by

- `i`
  gear ratio

Given `omega` is the speed of the shaft this simple propeller is connected to, it will rotate at `(omega_p = i * omega)` and provide a thrust of `(F = k_F * omega_p)`.

The torque applied to the shaft is `(M = -1 * k_M * omega_p * i)`.

Example for an xml description for direct connection to shaft:

       <simplethrust k_F="0.004" k_M="0.00001" />

Example for an xml description, connection to shaft via a gearbox:

       <simplethrust k_F="0.005" k_M="0.00002" >
         <gearing i="1.13" J="0" />
       </simplethrust>

See Gearing for a description of a gearbox.

# 4 Determining engine parameters

## 4.1 Formulas

Finding a complete parameter set for a specific engine can be impossible, but luckily the parameters can be calculated from measured data. Given the voltage, current draw and speed for the idle engine and the same three values for a load point, all electric parameters can be calculated using the above formula `I_M = (U_K - omega * k_M) / R_I`, because k_M and R_I can be assumed to be independend of the load applied to the engine.

Assume that the idle engine draws an idle current of I_M = I_0 when running without a propeller at a voltage U_K = U_0. The engine will run at its idle speed for this voltage, n = n_0. The angular velocity omega can be calculated as `omega_0 = 2 * PI * n / 60` when n is given in "rpm". For this idle point, the formula looks like this:

       I_0 = (U_0 - omega_0 * k_M) / R_I = (U_0 - (2 * PI * n_0 / 60)) / R_I</tt>

Applying the measured data from the load point to the formula (I_M = I_L, U_K = U_L and n = n_L) results in:

       I_L = (U_L - omega_L * k_M) / R_I = (U_L - (2 * PI * n_L / 60)) / R_I</tt>

Now there are two equations with two unknown variables, so this can be solved using some linear algebra. Solve one equation for k_M and insert it into the other equation. Solve the resulting formula for R_I:

       R_I = (n_L * U_0 - n_0 * U_L) / (n_L * I_0 - n_0 * I_L)

       or

       R_I = (omega_L * U_0 - omega_0 * U_L) / (omega_L * I_0 - omega_0 * I_L)

Then solve the original formula for k_M, insert the calculated R_I and the measured values from the load point (or the idle point, that doesn't really matter) to get k_M:

       k_M = (U_L - R_I * I_L) / (2 * PI * n_L / 60)         (n_L in rpm)

       or

       k_M = (U_L - R_I * I_L) / omega_L                     (omega_L in rad/s)

## 4.2 A worked example: Speed 400 with flux ring

For one model I wanted to simulate a Speed 400 (aka Mabuchi RS-380 PH) with an additional flux ring. I found an Excel sheet on the Internet that contained motor data for exactly this engine:

        U_K [V]  I_M [A]   n [rpm]  omega [rad/s]   remark
        -----------------------------------------------------------------------------------
         7.96     0.94     22290    2334.2           idle, n = n_0, U_K = U_0 and I_M = I_0
         7.37     7.47     13740    1438.9           near max. load

Using the above formulas I calculated R_I

       R_I = (n_L * U_0 - n_0 * U_L) / (n_L * I_0 - n_0 * I_L)
           = (13740 * 7.96V - 22290 * 7.37V) / (13740 * 0.94A - 22290 * 7.47A)
           = 0.357 Ohm

and k_M

       k_M = (U_L - R_I * I_L) / omega_L
           = (7.37V - 0.357 Ohm * 7.47A) / 1438.9 rad/s
           = 0.00327 Vs    (or 3.27E-3 Vs)

That was the hardest part. The remaining parameters are easy: I_0 can be directly read from the measured data (0.94A). n_0 was also measured, but remember that it has to be in 1/s, not in rpm, so we divide it by 60: n_0 = 22290 / 60 = 371.5 1/s

J_M, the engine's rotor's inertia, can be found in the manufacturer's data sheet, or it has to be guessed. I assumed 1.0E-6 for the Speed 400. You can estimate it by regarding the rotor as a solid iron cylinder of mass m (in kg) and diameter d (in m) using the formula

       J_M = 0.5 * m * d^2 / 4

All this resulted in the following engine file:

       <?xml version="1.0"?>
       <!--
         Mabuchi 380 (aka Speed 400) with additional flux ring

         J_M is just guessed.
       -->

       <engine_dcm R_I="0.357" k_M="3.27E-3" I_0="0.94" J_M="1.0E-6" n_0="371.5">
       </engine_dcm>

# 5. Example fold/brake settings

configuration | `battery.throttle_min` | `battery.shaft.brake` | `battery.shaft.propeller.n_fold`
--- | --- | --- | ---
elecrical engine, folding prop | `0` | `1` | `5`
elecrical engine, non-folding prop | `0` | `0` | `-1`
combustion engine, non-folding prop | `0.2` | `0` | `-1`