AutoTune

No AutoTune for STM32F1 based hardware

AutoTune is currently not built into CC3D/Atom firmware, due to small CPU and lack of memory.


LibrePilot version 16.09 and later has AutoTune.  Here is the simplest version of how to use AutoTune for those that don't want details.  If you don't read the details (problems to avoid and useful features you didn't know existed) and ask questions that are answered farther down in the details, be prepared for a bit of derision.  (smile)

Simplest use of AutoTune:
- use stock PIDs (or known, slow, smooth PIDs that do not have "invisible oscillation") in bank #1
- set up and save FMS (Flight Mode Switch) for
--- FMS#1 Attitude mode manual throttle (Stabilized 1) on bank 1
--- FMS#2 AutoTune mode (like Attitude mode but with shaking) on bank 1
--- FMS#3 Attitude mode manual throttle (Stabilized 1) on bank 3
- after saving, power off and on the FC so it sees AutoTune and enables the AutoTune module
- take off with FMS #1
- switch to FMS #2 and after 2 seconds, it will shake around for 60 seconds
- land after shaking stops
- disarm
- switch to FMS #3
- arm
- carefully take off to test the new PIDs (be ready to instantly drop by using zero throttle if anything strange happens)

If everything works, set up FMS as you like, with all modes pointing to bank 3

For the slightly less impatient, skip down to the section titled "Flight Mode Switch setup".

Background and Details
LibrePilot has ported Tau Labs / dRonin "Autotune" into 'next' and the coming 16.09 release (including RC#'s).

First some precautions.  Tuning carries a risk of oscillation and for LibrePilot firmware, oscillation tends to effectively move the throttle toward 50%.  If your copter requires more than 50% power to hover, then oscillation will make it descend.  If your copter needs less than 50% to hover, then obviously 50% will have it climbing.  In extreme cases any throttle above 0% will effectively be 50%.  Remember that zero throttle stick will stop the motors.  Don't make any changes to this important "motor off" safety feature.  Tuning is known to fail in some cases.  Testing has shown that these same cases fail dRonin Autotune as well.  Be prepared.

Oscillation generally comes in 3 forms.

Normal oscillation is a rhythmic motion that is generally visible and audible.  It is usually caused by PIDs being too high.

Jerkiness is random, and is not actually an oscillation.  It is usually caused by too much vibration.  Replace or straighten bent shafts, balance and track your props, and if that is not enough and the tuning doesn't fly right, try increasing (doubling) GCS -> Configuration -> Stabilization -> Expert -> Gyro Noise Filtering.

Invisible oscillation (sometimes D term oscillation or yaw oscillation) generally cannot be seen or heard.  One way you know you have it is that all throttle stick positions can act as if they were closer to the middle.  Another way you know is if you have two FMS positions that use different PID banks (and manual thrust), and one set of PIDs has significantly lower D terms (or a lower yaw PID) and you are hovering and switch from one to the other, you may notice that you need to add power to maintain altitude.  Increased thrust from the high D term / high yaw PID is caused by the ESCs being commanded up and down and being quicker when increasing RPM than when decreasing it.  You may find that motors tend to run hotter and batteries don't last as long as they should.  Powerful copters (those that require less than 50% power to hover) will take off with much less throttle than expected.  Weak copters (those that require more than 50% power to hover) will need more power than expected to take off, or will not take off even at full power.  Try reducing your D terms (Stabilization -> Advanced), reducing your yaw PID, or increasing (doubling) GyroTau (GCS -> Configuration -> Stabilization -> Expert > Gyro Noise Filtering), but realize that increasing GyroTau requires rerunning the AutoTune flight and will make AutoTune create very slow smooth PIDs.

If your multicopter is already tuned and you reduce performance by adding weight like a camera or larger battery (with same cell count); or reducing power (fewer cells in battery, different props) then you have created an oscillation.

On the other hand, if you remove a camera from a multicopter that is tuned to fly with the camera (or generally do something to increase performance), it wont' oscillate, it just won't be quite as quick reacting as it could be.  It will fly a bit "like it has a camera mounted" even when it doesn't.  That isn't so bad.

So if you are only going to do one tune, then do it with the camera on.  You can fly this tune with or without the camera.  Be aware that PID banks are excellent for storing different PIDs if you want different tunes for e.g. with / without a camera.  You can use one PID bank for with camera and one PID bank for without camera.

Oscillation can cause AutoTune to fail and even to crash.  If you have a problem with oscillation, it must be corrected before running AutoTune.  This is especially true of invisible oscillations if only because they are not obvious.  This is also especially true if you are adding a camera to a multicopter that is already tuned.

Ringing (Attitude mode) is when you move the stick suddenly and it doesn't immediately settle at the new bank angle.  Instead it oscillates a few times, but the oscillations die out quickly.

Assume that stock PIDs may oscillate or ring, especially with small multicopters or adding cameras.  Cutting your R/P/Y PI's in half will usually remove oscillation or ringing and make it safe to run AutoTune.

If AutoTune internal sanity checks fail, it won't write PIDs.  It's also possible to get PIDs that don't fly well.  This was more true in earlier versions of AutoTune.

This version of AutoTune puts the copter into a special version of Attitude flight mode that shakes the copter and measures the motions.  As a pilot, you should be able to confidently fly in Attitude mode because it will be a bit more difficult than normal to maintain control.  Tuning also needs a larger area than simple hovering.  As a point of reference, a good pilot should be able to do a tuning in a single car garage stall.

Multicopters fly better if they have "Light Damping (BLHeli)" or "COMP_PWM + MOTOR_BRAKE (SimonK)".  Without these, when there is a lot of stick control (or oscillation) happening, the copter tends to climb because the motors speed up more quickly than they slow down.  With slow or undamped/unbraked ESCs you may notice this when AutoTune mode starts shaking the copter.

AutoTune is not currently supported on CC3D, although it is hoped that a CC3D firmware can be made that removes other features to add AutoTune.  This would be flashed temporarily just to run AutoTune and then normal firmware would be reflashed.  Also, there will be a GCS GUI for all this at some time, but it was designed to make it possible to set it up at home and run it at the flying field without requiring use of the GCS at the flying field.

Flight Mode Switch setup:
Note that when AutoTune is complete, it writes the calculated PIDs into the destination stabilization (PID) bank which by default is configured to be bank 3.  The standard AutoTune procedure has you flying the AutoTune mode on bank 1 and writing the new PIDs to bank 3 (default destination PID bank was changed from 2 to 3).

Note that you must start with PIDs that will fly without oscillation.  These PIDs need to be in bank 1 in the following instructions.  Usually the default PIDs are OK, but occasionally they will need to be changed to make them flyable, or to remove oscillations.  If you have or suspect invisible / D term oscillation, set all D terms to zero and multiply all other PID P terms by 0.75 and all other PID I terms by 0.6 before flying the AutoTune flight.

Note that you must reboot the FC after adding AutoTune to the FMS because the AutoTune module is only initialized if it sees it is needed at boot time.

The recommended setup for running AutoTune uses a 3 position FMS (Flight Mode Switch).  With this, you can take off and fly Attitude mode with known working PIDs, run AutoTune with known working PIDs and fly Attitude mode with new PIDs, all without using the GCS:
Pos#1 - Attitude mode using bank 1
Pos#2 - AutoTune using bank 1 with SystemIdentSettings.DestinationPidBank set to 3 (that is the default)
Pos#3 - Attitude mode using bank 3 (bank 3 is where the tuned PIDs are written by default)
PID bank 1 should have default PIDs or something that is at least known to fly without oscillations.
PID bank 3 should have default PIDs or something that is at least known to fly without oscillations in case you use it before successfully completing a tune.
This setup can all be done at home, and everything else can be done at the flying field, without using the GCS.
With this FMS setup, you always have Pos#1 to fall back on.  Use Pos#1 to recover from any bad situation or to start over and run AutoTune again.

An alternate FMS setup for a 2 position FMS removes the ability to fly with default PIDs once you have run AutoTune:
Pos#1 - Attitude mode using bank 3 (bank 3 is where the tuned PIDs are written by default)
Pos#2 - AutoTune using bank 1 with SystemIdentSettings.DestinationPidBank set to 3 (that is the default)
PID bank 1 should have default PIDs or something that is at least known to fly without oscillations.
PID bank 3 should have default PIDs or something that is at least known to fly without oscillations.
PID bank 3 starts out with the same PIDs as bank 1, but the PIDs will be changed by AutoTune.
It is possible to arm in Pos#1, then switch to Pos#2 and immediately take off before the AutoTune shaking starts (two seconds), if your tuned PIDs don't work and you want to retune.

Remove anything that is expensive or fragile (e.g. cameras and antennas, but understand that transmitters must remain unpowered any time they don't have an antenna attached) from the multicopter if this is your first experience with AutoTune on this multicopter.  Be aware though, that you eventually need to tune in "flight trim".  Things like cameras and FPV gear that noticeably affect the total weight of the copter should be mounted to get the best tune.

Arm and take off in Pos#1 which is Attitude mode with default (or other known-good) PIDs.  These PIDs must not oscillate for the tuning to work.  Switch to Pos#2 which is AutoTune mode which is also configured to use default (or other known-good) PIDs.  After a few seconds the copter begins to shake (and may tend to climb).  Fly it smoothly.  Don't let the copter touch anything (such as the ground) while tuning is running.  60 seconds after switching into AutoTune, the shaking stops and the tuning is complete.  The PIDs have already been written to the destination PID bank, but are only stored in RAM memory at this point.  The standard procedure is to land and disarm which writes the PIDs to permanent storage.  (The PIDs will be written to permanent settings if you disarm before powering off.  The PIDs will be discarded if the copter is powered off without disarming it.)  Note that you can disarm while in AutoTune mode, but you cannot arm while in AutoTune mode.

Switch to Pos#3 (Pos#1 for the 2 position FMS) which now holds the tuned PIDs.  Cautiously take off, and be ready to immediately cut power to zero if there is any problem.  You are now flying tuned PIDs.  If for some reason you want to run AutoTune again, just switch to Pos#2 as before.

That covers the basics of AutoTune.  If you don't want to use additional AutoTune features, you can remove AutoTune from your FMS at this point.  Enhanced functionality, further tweaks, and safety issues are discussed below.

Further Information follows:
For expert pilots, in the above instructions, you might consider setting all bank 3 outer loop PIDs to zero.  If you do this, beware that you will not have roll or pitch control when using bank 3 until you have successfully completed AutoTune, so be ready to land immediately after takeoff when using bank 3.  The reason you would do this is for immediate confirmation that
AutoTune was successful and wrote new PIDs to bank 3.  After tuning, take off using an FMS position that uses bank 3, quickly test to see if you have roll or pitch control, and immediately land if you don't have control.  This is safer than starting a hover with bank 1 and and switching to bank 3 when you haven't tested the new PIDs in bank 3 yet.

Any time after tuning is complete, you can switch to Pos#3 (Pos#1 for the 2 position FMS setup) which is Attitude mode using the tuned PIDs to test them.  Use caution!  It's recommended that when tuning completes you land and disarm, but if you were to switch to Pos#3, even without landing, you would be flying the new PIDs.  If you have time and access to a GCS at this point and understand what reasonable PID values look like, you could examine the new PIDs before you fly them.

To test fly your new PIDs, switch to Pos#3 (Attitude with tuned PIDs), arm, and cautiously take off.  Beginners beware: a slow increase in motor power for takeoff is not recommended as it causes PID windup.  It is best to start with motors off and immediately jump up the smallest amount you can to barely get off the ground and stay off.  You can learn the correct amount of throttle by starting with small blips and giving bigger and bigger blips until you learn how much throttle it takes to take off.  Before you take off, mentally prepare yourself to immediately apply zero throttle if something doesn't feel right.  A fall from 3 feet / 1 meter generally causes little or no damage so it is best to keep it below that.

You can simply retune by running AutoTune again if you want to.  The use of Attitude mode when testing the new PIDs is recommended (but not required), even for experts.  AutoTune mode itself is a modified form of Attitude mode and it doesn't matter what other modes you have as far as the tune is concerned.

In the worst case scenario where you don't have your FMS set up as recommended, oscillation may cause it to climb, and the only way to get down is to cut power for short periods and let if fall.  Automatic leveling in that case is very desirable.  This isn't an issue if you have the FMS set up as recommended.  In that case, just switch to Pos#1.

Tricopters are a special issue.  They may or may not tune correctly.  An assumption is made that the control delay is the same for roll pitch and yaw.  This is not true for tricopters which use a servo for yaw, but use motor thrust for roll / pitch.

If you intend to fly this copter both with and without a significant payload attached (like a camera) or with different batteries (weight, cell count) then ideally you would tune each case separately and store them in different PID banks.  Probably the easiest way to handle the simple case of with/without a camera is to tune with the camera, copy bank 3 to bank 2, retune without the camera and leave that in bank 3.  Then remove AutoTune from your FMS and add flight modes that include both bank 3 (without camera) and bank 2 (with camera).  Note that the lighter total weight has smaller PIDs.  Smaller PIDs will work when carrying an extra load that wasn't there when tuning (it is a bit mushy), but if you use the larger PIDs that come from tuning with a camera mounted when the camera is not mounted, you may get some minor oscillations.

There is currently what might be described as a conflict between Outer Loop / Attitude Mode and the StabilizationSettingsBank#.MaximumRate's.  The outer loop PIDs are calculated assuming that there is no artificial limit to inner loop rates.  These .MaximumRate's are just such a limit.  Some high power / quick multicopters will experience oscillation in Attitude mode using the PIDs calculated by AutoTune.  You can either manually change (reduce) the outer loop PIDs or manually change (drastically increase) .MaximumRate (e.g. increase StabilizationSettingsBank3.MaximumRate.Roll and .Pitch to perhaps as high as 1500).  There is a code change that has already been coded and tested for this, but it is not yet part of rel-16.09 (or next).  The new code will automatically scale back the outer loop PIDs based on the .MaximumRate's in the destination bank.  The result of this is that (for this new code) you should set the .MaximumRate's before running AutoTune.  If you change the .MaximumRate's after flying the AutoTune flight, and later you change the .MaximumRate's, it isn't necessary to fly the AutoTune flight again, just rewrite the PIDs with SmoothQuick after the change.

It won't arm:
 It won't arm if you
- try to arm it in AutoTune mode
-
have put SystemIdent stabilization on Thrust on any FMS switch position
- use GPS Assist with AutoTune
- enable it on a vehicle that is not a multicopter

SmoothQuick:
There is a virtual slider called SmoothQuick, and the PIDs you get by default are in the middle of the slider.  At one end of the virtual slider are smooth PIDs which may be preferred for photography.  At the other end are quick PIDs which may be preferred for racing.  Once you have run the tuning, the FC will always remember the tuning and allow you to change PIDs along this sliding scale at any time in the future.  Starting the AutoTune process by staying in AutoTune mode for over 2 seconds while armed will erase the old settings and start a new tuning.  If you accidentally start an unwanted new tuning you can just power it off without disarming and it will forget the new tuning rather than making it permanent.  To use the SmoothQuick virtual slider, you need to attach a real slider (or knob or FMS 3x toggle) to it.  SmoothQuick works in real time, even while you are flying the tuned/destination PID bank if you want.

SystemIdentSettings -> SmoothQuickSource is where you attach a real slider.  SmoothQuickSource = 0 disables SmoothQuick entirely.  The default of 25 says to access the next of a set of 5 equally spaced points on the slider by toggling the Flight Mode Switch (starting outside of AutoTune) into AutoTune and back out, 3 times, in less than 2 seconds, but only if armed.  If you think of the SmoothQuick slider as a scale from -100 to +100, with smoothest being -100 and quickest being +100, then you start out in the middle at 0.  The first time you do the fast FMS 3x double toggle it will move you to +50 on the slider, then +100, then -100, then -50, then back to 0, etc.  If you do the fast FMS 3x toggle while disarmed, it will always set it to 0.  You can do that to set it to a known value if you forget.  SmoothQuickSource = 23, 25, and 27 give you 3, 5, and 7 equally spaced stops on the SmoothQuick slider.  25 is the default and gives you positions at -100, -50, 0, 50, and 100.

You can also set SmoothQuickSource to be a number from 10 to 13 which corresponds to using Accessory0 to Accessory3 to directly adjust the slider.  This requires that you have an available knob or slider on your transmitter, that you already have your transmitter configured to send it out as a separate channel, that the FC has been configured to attach that RC channel to one of the four FC Accessory channels, and that that FC Accessory is not being used by another FC function.

AutoTune / SmoothQuick 'data' is stored permanently.  Once you have run AutoTune once, you can use SmoothQuick with this stored data to produce smoother or quicker PIDs any time in the future.  You don't have to run AutoTune again, but you may want to if you change something, like props or weight or motors or cell count.

Using SmoothQuick semi-permanently:
It isn't necessary to manually enable the AutoTune module because it will be enabled each time the FC boots with AutoTune in the FMS.

If you do enable the AutoTune module manually then it will always be running, even if there is no AutoTune flight mode in your FMS.  In that case your SmoothQuick Accessory knob is always active to change the PIDs in the destination PID bank (default 3) and you can adjust PIDs from smooth to quick any time you want to.

Note that you must reboot the FC after enabling the AutoTune module because the AutoTune module is only initialized if it sees it is needed at boot.

To enable SmoothQuick permanently, enable:
GCS -> System -> Settings -> HwSettings -> Optional Modules -> AutoTune
and then press the Save (red up arrow) at the top of the page.  Reboot is required to guarantee that AutoTune is enabled.

AutoTune data:
The settings used by SmoothQuick are all stored permanently in SystemIdentSettings.  They are Tau, GyroReadTimeAverage, the 3 Beta values, and SmoothQuickValue.  'Complete' must also be True.  SmoothQuick
Value is only important if you use the 3x FMS toggle method to select how smooth or quick you want your PIDs.  It stores the current value of the toggle as a number from -1 to +1.

If you erase settings or build another of the same model of multicopter, you can copy the settings by hand if you know what they are.  They are stored as text in an exported uav file, or you can make a screen capture when they are visible on your computer screen.

AutoTune tries to produce results that make the tuning flight correctly tuned.  That does not take into account the non-linearity of thrust response.  To remove high thrust oscillations (or increase stability during descent), use TPS to decrease PIDs at high thrust (and if necessary, increase PIDs at low thrust).  Typically you want the TPS curve/line to cross the horizontal axis at the point (thrust value) where the copter hovers.  Examine SystemIdentState -> HoverThrottle after tuning and before you power off (SystemIdentState is not saved) to see what your hover thrust is.  Beware of throttle "bloom" that happens when slow responding ESC's make a copter climb just because of the fast RPY controls.

SystemIdent stabilization mode:
AutoTune is a flight mode that can directly go on the FMS.  SystemIdent is a stabilization mode that can be put in a Stabilized1-6 flight mode.  There is no reason to use SystemIdent stabilization mode.  What you will get is a mode that acts a lot like the shaking part of AutoTune, but the shakes may be bigger or smaller.  SystemIdent stabilization mode has been hidden from use when using the GCS FMS setup GUI.  It can only be enabled with settings on the System tab.

Enabling the AutoTune module manually:
The AutoTune module is automatically enabled at boot time if the FC detects that AutoTune has been added to the FMS.  The AutoTune module can also be enabled manually so it is always enabled.  After either of these changes, you must reboot the FC for AutoTune to actually run.  There are two reasons you might want to manually enable the AutoTune module:
- You no longer have AutoTune on the FMS, but you want to be able to continue to use SmoothQuick.
- You know you are going to experiment with FMS changes that include adding and removing AutoTune from the FMS (e.g. over the course of many days).  Without manually enabling the AutoTune module, you will need to reboot after adding AutoTune to the FMS if it was not enabled in the FMS at power up.

You can copy these settings from an old run of AutoTune instead of flying the AutoTune flight:
If you want to, you can copy these AutoTune settings from an old run of AutoTune.  You might do this if you are upgrading firmware or building a duplicate of a model.  They are all fields in SystemIdentSettings. 
All other SystemIdentSettings fields can be modified and the new values will affect the PIDs written the next time SmoothQuick is used to rewrite the tuned PIDs:
- Tau
- Beta.Roll

- Beta.Pitch

- Beta.Yaw

-
GyroReadTimeAverage
- Complete


Field descriptions:
System.SystemIdentSettings are stored permanently but do not show up in logs.  DataObjects.SystemIdentState shows up in logs but is not stored permanently.  Read the xml files or source if you need to know more of the technical aspects of their fields.  The field descriptions should be displayed on the System page if you hover over a field or enable "Show Descriptions" (click the eyeball at the top of the GCS System page to find this setting).

Changes to these fields generally take effect after either entering AutoTune mode (even briefly, either armed or disarmed) or rebooting the FC.

System.SystemIdentSettings:
- Is stored permanently
- Is not logged
- Is reset to default values if you stay in AutoTune mode until the shaking starts (about 2.5 seconds).  As with other AutoTune data changes (not sent by you from the GCS), this is not stored permanently until you disarm.  If you power off without disarming, the reset values are not stored permanently.
- Tau, GyroReadTimeAverage, Beta (3 values), and Complete are the fields filled in by the AutoTune flight.  Other fields are used by SmoothQuick to convert these values into PIDs and check and limit the PIDs.
- DampMin, DampRate, DampMax affect the control damping.  Decrease damping to make your aircraft response more rapidly.
- NoiseMin, NoiseRate, NoiseMax affect control sensitivity.  Increasing noise (sensitivity) will make your aircraft respond more rapidly, but will cause twitches due to noise
- These Damp and Noise values together form the dual virtual slider SmoothQuick
- The smooth end of SmoothQuick uses DampMax and NoiseMin
- The quick end of SmoothQuick uses DampMin and NoiseMax
- The center of the SmoothQuick slider uses DampRate and NoiseRate
- CalculateYaw can be False,TrueLimitToRatio,TrueIgnoreLimit default is TrueLimitToRatio
- YawToRollPitchPIDRatioMin is enabled with CalculateYaw default is 1.0
- YawToRollPitchPIDRatioMax is enabled with CalculateYaw default is 2.5
- DestinationPidBank default is 3
- TuningDuration is 60 seconds
- DerivativeFactor default is 1.0 and can be set between 0.0 and 1.0 to reduce the normal PID D term (helps reduce D term oscillation if that is a problem)
- OuterLoopKpSoftClamp is value of outer loop kp where outer loop limiting starts default is 6.5
- SmoothQuickSource default is 25 (FMS toggle method with 5 positions)
- SmoothQuickValue default is 0
- DisableSanityChecks disables certain checks that stop the PIDs from being written default is false
- Complete is set true after a successful AutoTune run.  It must be true for PIDs to be written to
DestinationPidBank 

DataObjects.SystemIdentState
- Is not stored permanently (Goes away when power is removed)
- Is logged
- HoverThrottle is the average throttle used during tuning.  It is a reasonable value to use in Settings.AltitudeHoldSettings.ThrustLimits.Neutral although it is usually a little smaller than it should be due to throttle bloom during shaking.
- The 3 values in Noise tell you how much vibration you have on the 3 axes.  Normal values range from about 100 to about 1000.  For high values, or jittery response to the PIDs created, balance your props and if that doesn't help, you may want to increase Settings.StabilizationSettings.GyroTau (found in the GCS GUI at Configuration -> Stabilization -> Expert -> GyroNoiseFiltering) and retune (you must actually fly the tuning flight again).  Now you know how much vibration you actually have.
- Contains fields that may be useful if debugging problems with AutoTune
- Contains copies (for logging purposes) of some fields from System.SystemIdentSettings