[WIP] Multicopter PID Tuning Cookbook reformulation

en/SUMMARY.md

@@ -136,6 +136,7 @@
     * [MC Setpoint Tuning (Trajectory Generator)](config_mc/mc_trajectory_tuning.md)
       * [MC Jerk-limited Type Trajectory](config_mc/mc_jerk_limited_type_trajectory.md)
     * [Multicopter Racer Setup](config_mc/racer_setup.md)
+    * [Multicopter Rotor tilting for Yaw Authority](config_mc/mc_motor_tilting_for_yaw.md)
   * [Fixed Wing  Config/Tuning](config_fw/README.md)
     * [Fixedwing PID Tuning Guide](config_fw/pid_tuning_guide_fixedwing.md)
     * [Fixedwing Advanced Tuning Guide](config_fw/advanced_tuning_guide_fixedwing.md)

en/config_mc/mc_motor_tilting_for_yaw.md

@@ -0,0 +1,18 @@
+# Tilted Motors for Yaw Authority in Multicopter
+
+Multicopters utilize the reaction torque from the rotors to control the yaw. However, for large multicopters with high moment of inertias especially, controlling the yaw solely using the reaction torque becomes more challenging.
+
+The reaction torque also depends on the profile (pitch) of the rotor, which tends to be slimmer in larger rmulticopter vehicles as well.
+
+Failure to have enough yaw authority can result in a vehicle with a crash.
+
+## How to tilt rotors to increase yaw control authority
+
+To tilt the rotors, please do the following, depending on the direction of the rotor's rotation:
+
+* Rotors turning clockwise: Turn the rotor to provide extra counter-clockwise torque on vehicle's body, to aid the reaction torque from the rotor
+* Rotors turning counter-clockwise: Turn the rotor to provide extra clockwise torque on vehicle's body, to aid the reaction torque from the rotor
+
+<!-- TODO: Add diagram -->
+
+Note, this is also documented in [ArduPilot](https://ardupilot.org/plane/docs/quadplane-tips.html#increasing-yaw-authority).

en/config_mc/pid_tuning_guide_multicopter_cookbook.md

@@ -0,0 +1,119 @@
+# Multicopter PID Tuning Cookbook
+
+This document will guide you through the whole PID tuning process of Multicopter step by step, just like a cookbook!
+
+## Step 1: Hardware configuration
+
+### Check motor output settings
+First things first, you need to make sure your motors are configured correctly!
+
+If you are using PWM output, set the correct Disarmed, Minimum and Maximum output value by referring to [Actautor Outputs > Motor Configuration](../config/actuators.md#motor-configuration).
+
+It is important to set PWM minimum value properly to make sure motors won't stop spinning in the air.
+
+### Setting motor thrust curve factor
+
+<!-- TODO: Insert Thrust curve simulation (interactive diagram) -->
+
+Thrust curve factor([THR_MDL_FAC](../advanced_config/parameter_reference.md#THR_MDL_FAC)) defines the relationship between output signal and the thrust generated by the motor.
+
+This is important to set correctly, as the most fundamental rate control of the PID controller will output a torque setpoint which will get mapped to appropriate signal value depending on the thrust curve factor.
+
+Therefore, if you set it to be `linear` (`thrust = signal`) when in reality it is `quadratic`(`thrust = signal^2`), the vehicle dynamics assumption will be wrong and it may behave erratically.
+
+<!-- TODO: Insert diagram showing Thrust Curve's effect on control authority -->
+
+This is highly dependent on the ESC, Motor and Propeller (and even Battery), so it should be evaluated for every specific setup.
+
+Refer to [Thrust Curve](pid_tuning_guide_multicopter_advanced.md#thrust-curve) documentation for the detailed explanation of a Thrust Curve.
+
+The best case is to have an actual thrust measurement data that you can plot and fit onto the thrust curve. Depending on that please jump to appropriate sections below:
+
+- [If you have a thrust measurement, jump to here](#if-you-have-a-thrust-measurement-data)
+- [If you don't have a thrust measurement, jump to here](#if-you-dont-have-a-thrust-measurement-data)
+
+#### If you have a thrust measurement data
+
+If you have the thrust measurement for your ESC, motor and propeller combination, simply plot the data in a tool (e.g. Excel) and find for the best `alpha` value that fits the thrust curve data, and set it as the thrust curve factor parameter.
+
+*rel_thrust = ( `alpha` ) * rel_signal^2 + ( 1 - `alpha` ) * rel_signal*
+
+An example of a thrust measurement is something like this: [EXAMPLE](https://github.com/Auterion/thrust-bench-data/blob/master/StepsTest_2019-04-30_112217_MT2212-11_1100kv_APC10x5-5_low.csv).
+
+And this example plots to a thrust curve like below, and the appropriate thrust curve factor is identified as 0.X. (TODO)
+
+#### If you don't have a thrust measurement data
+
+This is most likely the case since most people don't have a thrust measurement system available, in that case we can select empirically depending on the type of ESC:
+
+- Set to `1.0` if your ESC explicitly states that it does RPM control (RPM proportional to signal), since thrust will be fully quadratic (proportional to `signal^2`).
+- Set to `0.3` for all other ESCs. Which is an empirically derived value that assimilates *most* ESC / Motor / Propeller combination).
+
+If you don't set any value, the default will be `0.0`, which assumes linear relationship between signal and the thrust.
+
+## Step 2: Pre conditions
+
+There are some critical pre-conditions you need to check & be aware of, in order to start tuning the PID values of the Multicopter:
+
+### Actuator mapping sanity check
+
+Before you go on any further, make sure the actuators outputs are correctly mapped. This can be done by going through the [output assignment](../config/actuators.md#output-assignment-and-configuration).
+
+Make sure that the motors order and direction of rotation as as expected! With a wrong motor assignment, the PID controller can output undesirable results (e.g. Drone flipping and crashing).
+
+### Motor Tilting for Yaw Authority
+
+Furthermore, it is recommended to [tilt the rotors](./mc_motor_tilting_for_yaw.md) to increase the yaw control authority. Especially if your vehicle is very large (with high moment of inertia around yaw-axis).
+
+### Theory behind PID Control
+
+It is helpful to understand / get intuitive sense on how PID tuning works. For that, you can refer to either the [Multicopter Control Architecture](../flight_stack/controller_diagrams.md#multicopter-control-architecture), and/or the following video:
+
+@[youtube](https://www.youtube.com/watch?v=JBvnB0279-Q)
+
+Furthermore, as we will be tuning the K, I and D gains using standard PID system notation (instead of P, I and D) in this documentation, please read the [standard vs parallel PID form](./pid_tuning_guide_multicopter_advanced.md#rate-controller-architectureform) documentation.
+
+### Note on Attitude gain for testing in Stabilized mode
+
+Although it is ideal to tune the rate controller in an Acro mode (which commands rate setpoints directly from user's setpoint), this requires fine control and lots of experience in the operator's side.
+
+Therefore, it is most convenient to test the vehicle in a 'Stabilized' mode. However, this comes with a catch.
+
+As documented in [Multicopter Attitude Controller documentation](../flight_stack/controller_diagrams.md#multicopter-attitude-controller), for stabilized mode, the 'Attitude P gain' plays a crucial role in defining the feasible vehicle dynamics.
+
+If the P-gain is too high (which is the problem case) with a big vehicle with high moment of inertia, it can quickly generate infeasible rate setpoints, and lead the vehicle into a crash.
+
+<!-- TODO: Add diagram / graph on how having too high P-attitude gain can lead to instability -->
+
+Therefore, before you go onto the rate control step, please use the default rate control gains and first tune the 'attitude controller' first.
+
+### Disabling Airmode
+
+As documented [here](./pid_tuning_guide_multicopter_advanced.md#airmode--mixer-saturation), 'Airmode' is useful to utilize vehicle's full rate control capability, but it interferes with the PID tuning (as it arbitrarily increases the overall collective thrust).
+
+Therefore, please disable the 'Airmode' before you begin PID tuning.
+
+## Step 3: Rate control tuning
+
+We will use the QGC's rate controller tuning UI, for that please do the following:
+
+1. Go to 'PID Tuning' Tab in QGC
+2. Set 'Airmode' selector to have it 'disabled' (by default)
+3. Go to 'Stabilized' flight mode
+
+Note that in Stabilized mode, you have direct control on collective thrust using the throttle, and roll/pitch/yaw angle with manual control stick input.
+
+### Roll/Pitch Rate controller tuning
+
+First, re
+
+### Yaw Rate controller tuning
+
+## Step 4: Attitude control tuning
+
+## Step 5: Velocity control tuning
+
+## Step 6: Position control tuning
+
+## Step 7: Gyro filter tuning
+