Tuning

== Intro ==
This page provides guidelines for tuning a new aircraft and additional practical tips. Be sure to familiarize yourself with the theory of PID Controllers before you begin tuning your airframe. Use of the real time plotter may help to visualize and understand the behavior of the control loops. Review User Manual as well. Also reading See How It Flies, by John S. Denker is very beneficial to get your airframe tuned well.
==Energy Control==
If you came to this page and want to learn about how to perform your Energy control tuning, this is not the page to read, go to tuning energy control loops.
==Quickstart==
Here is the sub-minimal ultra-quick-start guide: note that point 1 and 3 should ALWAYS be performed every time you reflash your plane!!!
# Before take-off check (beware: do not skip a test as it is not because 2 are good that the third will also be good)
## RC-left is aileron-left and up is up in MANUAL.
## RC-left is aileron-left and up is up in AUTO1.
## turning the plane-left is aileron-right and nose-up is elevator-down with RC in neutral in AUTO1. (to check the Artificial horizon in the GCS: use the words: right wing sees the ground to not mess up left and right if uncertain.)
# Fly manual
## trim your plane
## check servo deflections are good (sufficient but not aerobatic)
## remember the cruise throttle. (and max/min throttle if you will use aggressive-climb)
# On the ground, after trimming: 
## Check with plane flat/cruise attitude on the ground that the ailerons/elevator do not move when you switch from MANUAL to AUTO1. This checks your IMU/Thermopiles are properly aligned and that your trim values are in the airframe file and not the RC-transmitter 
# Test try AUTO1
## When entering AUTO1, make sure you try to turn before your plane is too far away since AUTO1 circles are usually much larger than manual circles.
## Make a graph on the groundstation of DESIRED->phi/theta and ATTITUDE-phi/theta to see if they match. 
## When flying with IMU pay special attention here if after several left turns the plane still turns right too. Plot the IMU_ACC->ax,ay,az to see the average vibration in your plane. If the vibration level is lower than half of gravity (5m/s2) than usually you are OK. If it is much more, you should dampen your IMU more. (in foam, or mounted on your heavy battery, ...)
# Only when AUTO1 works fine you can go to AUTO2
## check that your throttle is not killed (RED) in the groundstation
## check that your cruise throttle is correct if you have a powerful motor 
## if tuning the altitude loop seems difficult try the simple 3 gain auto_throttle_loop
== Sensors ==
=== IMU / Sensors ===
You may want to look at the ImuCalibration. 
While some Sensors can be operated with factory calibration (MPU6050 or 6000) other, for example Magnetometers require a calibration to the earth magnetic field and UAV radiated magnetic field to work satisfactory.
=== Directions ===
* Reverse any servos and make sure no mechanical binding occurs at the limits of travel in Manual mode.
* Take the plane outside and engage AUTO1. Bank and pitch the plane and verify that the controls respond in the correct direction AND that the PFD in the notebook responds correctly. Note that your body will have a tremendous impact on the measured angles if using IR sensors. If using an IMU, there is no need to be outside. See note.
* Verify that AUTO1 stick movements respond in the correct direction - important! See note.
* Move the plane rapidly to ensure the gyro response resists motion - increase the gain if needed for better visualization.
NOTE: If the PFD responds in the wrong direction to the motion, you should adjust parameters in the INFRARED or IMU parts of the airframe file. If the control surfaces respond in the wrong direction to counteract motion (stabilize the aircraft, bring it back to neutral), reverse the servos in the airframe file. If the manual input from R/C causes the control surfaces to respond in the wrong direction (want them to force motion, not counteract motion), then you must reverse the channel on the R/C transmitter. Be sure to recheck surface neutrals and endpoints after doing such modifications. Also double check the gain signs, make sure none are positive that should be negative.
== R/C, Modem, and GPS ==
* Make sure the GPS signal is strong (outdoors) - you should have a 3-D fix in less than 1 minute and at least some satellite signals above 40dB. The plane should not drift on the map by more than 10 meters.
* Perform a range test of R/C and modem signals.
* Ensure that two way communications are in place. Check that the motor starts up when launch is commanded or move a waypoint and check that it's updated in the autopilot.
== Trim ==
Important: You must never keep any trim, mixers, or rates in your R/C transmitter. R/C trim can be applied in flight but must be corrected and removed on the ground before attempting autonomous flight. Exponential can be useful and will not adversely affect AUTO1 flight but if "low rates" are needed they should be programmed on the same transmitter switch with AUTO1 so that you always have full travel in AUTO1.
* Fly the plane at what you feel is a suitable "cruise" throttle setting and set the trims. Note that setting in the GCS and try to return to that exact setting in subsequent tests. Enter that throttle setting in your airframe file.
* Check maximum pitch and roll response and adjust the mixer parameters or mechanical linkages after landing.
* Land and adjust the linkages. If necessary, the PPM values can be read from the GCS and servo neutrals adjusted electronically, but manual adjustment will produce far better results.
* Fly again to verify trim and control response. If satisfactory, check for any significant throttle-dependent roll. Again, this is best to correct mechanically but can be addressed with the AILERON_OF_THROTTLE mixer in the autopilot. Check also for any odd behavior at full throttle.
* Make sure that GPS and modem data is reliable during these test flights. Note particularly any tendency for the aircraft to appear to fly sideways on the map - this is an indication of weak GPS signals.
== Auto 1 ==
* Engage Auto1 and immediately make sure you can turn both left and right!
* Fly at your "cruise" throttle and adjust the ROLL_PGAIN until the plane doesn't quite oscillate
* Adjust the IR roll neutral as needed
* Verify adequate pitch response and adjust PITCH_PGAIN as needed
* Experiment with different throttle settings and tune P and D gains as needed
If you are alone in the field while tuning, setting values via your RC transmitter may come in handy, see RC receiver data uplink
== Auto 2 ==
* Engage AUTO2 and you're done! Make sure you keep a finger on the Mode switch to take over just in case.
==Alternate Tuning Procedure==
Danstah wrote up a tuning procedure on this website http://www.engr.usu.edu/wiki/index.php/OSAMtuning
==Sample/Simple Altitude and Throttle Loop==
The dash button changes the NOMINAL_CRUISE_THROTTLE to the MAX_CRUISE_THROTTLE while the loiter button changes it to MIN_CRUISE_THROTTLE. 
This makes it easy to suddenly make the UAV fly a bit slower or a bit faster. However, when changing the throttle, you also need to change the elevator trim in order not to climb/descend too much. This it what AUTO_THROTTLE_LOITER_TRIM and AUTO_THROTTLE_DASH_TRIM are for. (I think the unit is MAX_PPRZ = 9600 = full deflection?) 
The auto-throttle loop is actually the most difficult loop to tune as it has both the speed and altitude that are correlated. Controlling both speed and altitude with high performance is very hard. It is way easier to control 1 entity (e.g. altitude) with higher performance and let the speed change a bit, or have an airspeed controller but then do the altitude slowly... 
Sample altitude controller:
---------------------
Step1: outerloop: if altitude is not good -> compute a climb/descend rate. (including ALTITUDE_MAX_CLIMB)
 climb_command = altitude_error x alt_pgain
e.g. 10 m too low x 0.1 alt gain = climb_command at 1 m/s
e.g. 50 m too low x 0.1 alt gain = climb at 5 m/s > ALTITUDE_MAX_CLIMB(2) -> climb_command = 2m/s
---------------------
Step2: innerloop: [many many options here, but since you ask for simple I'll only give one robust and simple:]
too low -> pitch up and extra throttle (if you only apply throttle, airspeed will increase and might even start to dive with full throttle if the nose is a bit heavy, if you only apply pitch airspeed will decrease and could lead to stall, with proper tuning you can get a pretty constant speed even while climbing and descending) 
 pitch_command = climb_command x pitch_of_vz
 throttle_command = nominal_cruise_trim_throttle + climb_command x throttle_climb_increment
e.g. climb_command at 1 m/s x pitch_of_vz 0.15 = 0.15 radians pitch = 9 degrees pitch up
e.g. climb_command at 1 m/s x throttle_climb_increment 0.25 with nominal_cruise_trim_throttle 0.5 = 75% throttle
-------------------
If you use AGRESSIVE_CLIMB then if the altitude error is larger than the chosen threshold a precomputed pitch and throttle will be applied. 
AUTO_PITCH is for constant throttle and control height with elevator only
auto_throttle_p/i/d_gains are to regulate the climb rate more precisely
==Other Misc things before flying==
It's very important to address the issue of low voltage cut-off before flying (LVC). 
There's a good chance that the LVC will kick in on the brushless ESC before the Paparazzi detects it. 
If this happens, the ESC cut's off throttle, and there's no way the autopilot knows this, the plane keeps loosing altitude, 
the autopilot tries to increase throttle, but the ESC does not respond, almost always leading to a mishap. 
To avoid this, either turn off the LVC on the ESC, OR, make sure the autopilot kills throttle first, 
by programming the CATASTROPHIC_BAT_LEVEL to something higher than the ESC LVC. 
For example, set CATASTROPHIC_BAT_LEVEL to 9.5V, and the ESC LVC at 9V. 
Don't ask how we know, it was a safe landing into a small tree :) No damage. BUT you cant get lucky always!
Have a look at the failsafe and battery configuration for more details.
Category:Software Category:User_Documentation