APM_Control: APM tuning guide.txt - Added step by step tuning description.

libraries/APM_Control/APM tuning guide.txt

@@ -1,3 +1,75 @@
+Tuning Overview:
+The following instruction assume that
+a) your model is trimmed correctly in manual mode
+b) you have done your radio calibration
+c) you have calbrated your airspeed sensor
+d) you have set your APM and transmitter to be able to select FBW-A mode
+e) You have checked your pitch roll and yaw angle on the HUD and verified that they match the rotation of the model
+
+Ground checks:
+1) On the ground selet FBW-A mode
+2) Rotate your model nose up - you should see the elevators/elevons deflect down
+3) Rotate your model nose down - you should see the elevators/alevons deflect up
+4) roll the model to the right - you should see the LH aileron/elevon go up and the RH aileron/elevon go down.
+5) roll the model to the left - you should see the LH aileron/elevon go down and the RH aileron/elevon go up.
+6) level the model - the control surfaces should be close to neutral. Tthere will be a little bit of offset, but any more thn 10% of your maximum throw indicates that the APM has not been levelled or the radio calibration needs to be repeated.
+7) With the model level apply LH and RH roll stick inputs  on your transmitter - the controls should deflect in the same direction that they would in manual mode.
+8) With the model level apply up and down pitch stick inputs on your transmitter  the controls should deflect in the same direction that they would in manual mode.
+6) Blow air towards the front of the pitot tube and wathc the HUD. You should see the airspeed reading incease
+
+Flight testing:
+You will need a second person to do this - one person to fly the plane and one person to adjust the parameters.
+You need to be a proficient RC pilot and have the skills to be able to recover from an unusual attitude. If not, then get someone who can to help you.
+
+Initial asssessment:
+1) Takeoff in manual and adjust the trims and throttle to a cruise position so that the plane flies straight and level at a speed that you are comfortable with. This will normally be somewhere between 30 and 60% throttle depending on how overposwered your model is.
+2) With the plane flying away from you switch to FBW-A. It should continue to fly wings level and at a fairly constant height (it will climb or descend slowly). If it wants to roll or pitch imore than a small amount then there is a problem with the models trim or radio calibration and you need to solve that first before procedding further.
+3) If the model starts to wag its wings, then the autopilot default gain is too high for your model (this is unlikely but could happen) and you need to switch back to manual immediately and ask your assisitant to halve the CTL_RLL_K_P parameter before switching back into FBW-A
+4) If the model starts to porpoise, the default autopilot gain is too high (this is unlikely but could happen)  and you need to switch back to manual immediately and ask your assisitant to halve the CTL_PTCH_K_P parameter before switching back into FBW-A
+
+Roll control tuning:
+
+Basic:
+1) With the model in FBW-A mode, put in a rapid bank angle demand, hold it and release. So the same in the other direction. You want the model to roll quickly and smoothly to the new bank angle and back again without overshoot or any wing 'waggle'. If the roll response is too slow, then progressively increase the CTL_RLL_K_P paameter in increments of 0.1 until it starts to overshoot and wing rock a little.
+2) Now increase the CTL_RLL_K_D gain in small increments of 0.01 until the overshoot or waggle goes away. If it hasn't worked by the time you have reached a vlue of 0.1 for CTL_RLL_K_D, DONT go any further - you need to reduce CTL_RLL_K_P.
+
+Advanced:
+1) Select the tuning box on the bottom of the Mission planeers Flight Data page. You should get a scrolling black window above the map. Double click in the black window and you should get a list of paremters to plot. uChange the selection until you have the roll and nav_roll plotted. Nav_roll is the demand and roll is the response. You can use this to look for overshoot and other behaviour that isn't so obvious from the ground looking at the model.
+2) Check for any steady offset between nav-roll and roll. If there is one you can set the CTL_RLL_K_I to a small value (say 0.01) which will allow the control loop to slowly trim the aileron demand to remove the steady error.if you want it to trim faster, you can increase the value fo this gain.
+3) If you can slow down the rate of roll and make the model bank more smoothly by reducing the roll rate limit CTL_RLL_RMAX parameter. The default is 60 degrees/sec which is fine for most models.
+4) If the model appears to roll rapidly initially and then appears to slow down and take noticeably longer to complete the roll, them this normally indicates that the parameter that sets the time constant of the roll manoeuvre CTL_RLL_OMEGA needs to be increased and CTL_RLL_OMEGA nees to be reduced.
+
+Pitch Control Tuning:
+
+Basic:
+1) With the model in FBW-A mode and the throttle at the cruise position, put in a pitch angle demand, hold it and release. So the same in the other direction. You want the model to pitch smoothly to the new pitch angle and back again without overshoot or porpoising. If the pitch response is too slow, then progressively increase the CTL_PTCH_K_P paameter in increments of 0.1 until it starts to overshoot and porposie a little.
+2) Now increase the CTL_RLL_K_D gain in small increments of 0.01 until the overshoot or porposie goes away. If it hasn't worked by the time you have reached a vlue of 0.1 for CTL_PTCH_K_D, DONT go any further - you need to reduce CTL_PTCH_K_P.
+3) Now roll the model to maximum bank in each direction. The nose should stay fairly level during the turns without significant gain or lss of altitude. Some loss of altitude during sustained turns at constnt throttle is expected, becasue the extra drag of turning slows the model down which will cause a mild descent . If the model gains height during the turns then you need to reduce the CTL_PTCH_K_RLL by small increments of 0.01 from the default value of 1.0. If the model descends immediately when the model banks (a mild descent later in the turn when the model slows down is normal as explained earlier) then increase the CTL_PTCH_K_RLL by small increments of 0.01 from the default value of 1.0. If you need to change the CTL_PTCH_K_RLL parameter outside the range from 0.8 to 1.2 then something is likely wrong with either the earlier tuning of your pitch loop, your airspeed calibration or you APM's bank angle estimate.
+
+Advanced:
+1) The maximum nose down and nose up pitch rate in degrees/second can be constrained by setting the CTL_PTCH_RMAX_D and CTL_PTCH_RMAX_U parameters to a value other than 0. These parameters These can be used to limit the amount of g produced during a pull-up or push down.
+2) The time constant of the pitch control lop can be reduced by increasing the CTL_PTCH_OMEGA paameter from the default value of 1.0. this will give a 'snappier' pitch response, but does mean that the noise in the demands from the airspeed control loop can casue unwanted pitch motion.
+
+Yaw Control Tuning:
+
+The yaw control loop can be configured either as a simple yaw damper (good for models with inadequate fin area) or as a combined yaw damper and sideslip controller. Becasue control of sideslip uses measured lateral acceleration, it will only work for those models that have enough fuselage side area to produce  a measureable lateral acceleration when they sideslip (an extreme example of this is an aerobatic model flying a knife-edge manouvre where all of the lift is produced by the fuselage). Giders with very skinny fuselages and flying wings cannot use this feature,but can still benefit from  the yaw damper provided they have a yaw control of some sort of yaw control (rudder, differential airbrakes, etc)
+
+Tunng the yaw damper:
+1) Verify that the CTL_YAW_K_A and CTL_YAW_K_I gain terms are set to zero, the CTL_YAW_K_RLL gain term is set to 1.0 and the CTL_YAW_K_D gain term is set to zero
+2) Roll into and out of turns in both directions and observe the yawing motion as it rolls into the turn. If the nose yaws away fom the direction of roll, you need to increase the KFF_RDDRMIX gain until the yaw goes away.
+3) Increase CTL_YAW_K_D fromin small increments of 0.05 until the tail starts to 'wag'. Halve the the gain from value at which you start to see the tail 'wag'.
+4) Now roll the model into and out of turns in both directions. If the model has a tendency to yaw the nose to the outside of the turn, then increase the CTL_YAW_K_RLL gain term in increments of 0.01 from its default value of 1.0. Conversely if the model has the tendency to yaw the nose to the inside of the turn on turn entry, then reduce the CTL_YAW_K_RLL gain term in increments of 0.01 from its default value of 1.0. If you have to go outside the range from 0.8 to 1.2, then there is something else that needs to be sorted and you should check step 2), the airpseed calibration and accuracy of the bank angle measurement. 
+
+Tuning the sideslip controller (advanced):
+1) Tune the yaw damper first
+2) Set the CTL_YAW_K_I gain term to 1.0. If this causes the tail to 'wag' then reduce this gain until the wag stops
+3) Bring up the tuning graph window in the misson planner and plot the lateral acceleration ay.
+4) Roll the model rapidly from full bank in each direction and observe the lateral acceleration ay. If the lateral acceleration sits around zero and doesn't change when you roll into or out of turns then your model is very well trimmed and no sideslip control is required. You can change the CTL_YAW_K_I gain term back to zero.
+5) IF you see that the y acceleration is offset or spikes up during turns, then progressively  increase the CTL_YAW_K_A gain in steps of 0.5 until the error goes away or the tail starts to wag. If the tail starts to wag, then halve the gain frm the value at which the wag appeared.
+
+
+Control Parameter Descriptions:
+
 Pitch control parameters:
 
 Main Parameters:
@@ -11,11 +83,11 @@ This is the gain for integration of the pitch rate error. It has essentially the
 CTL_PTCH_K_D= 0.0
 This is the gain from pitch rate error to demanded elevator. This adjusts the damping of the pitch control loop. It has the same effect as the D term in the old PID but without the large spikes in servo demands. this will be set to 0 as a default. Some aiframes such as flying wings that have poor pitch damping can benefit from a small value of up to 0.1 on this gain term. This should be increased in 0.01 increments as to high a value can lead to a high frequency pitch oscillation that could overstress the airframe.
 
-Advanced Parameters:
-
 CTL_PTCH_K_RLL = 1.0
 This is the gain term that is applied to the pitch rate offset calculated as required to keep the nose level during turns. The default value is 1 which will work for all models. Advanced users can use it to correct for height variation in turns. If height is lost initially in the turn this can be increased in small increments of 0.05 to compensate. If height is gained initially then it can be decreased. 
 
+Advanced Parameters:
+
 CTL_PTCH_RMAX_D = 0
 This sets the maximum nose down pitch rate that the controller will demand in (degrees/sec). Setting it to zero disables the limit.