Howto:Design an autopilot: Difference between revisions

== Pre-design ==

Why not make things slightly easier, before we start working on the autopilot? Since we will be updating the autopilot hunderts of times, making tiny adjustments each time, we don't want to reload FlightGear every time. Therefore, we assign an "reload autopilot configuration" action to a key on our keyboard. We've chosen Shift-F5, but it could be any key. Add the code to your <tt>[[$FG ROOT]]/keyboard.xml</tt> file.

  <key n="261">

   <name>F5</name>

   </mod-shift>

  </key>

== Creating the autopilot configuration file ==

Create an autopilot.xml file with the following content, somewhere inside your aircraft's root (eg. <tt>Aircraft/747-400/Systems/autopilot.xml</tt>).

  <?xml version="1.0"?>

   

   

  </PropertyList>

== A first controller: wing leveler ==

Be sure to add an <enable> element to easily enable/disable your controller if it gets unstable.

  <pid-controller>

   <name>Heading hold</name>

   </config>

  </pid-controller>

Since this is our first controller, we will give a short explenation of each part.

Finally (for the wing-leveler) you can turn it into a roll-hold by setting your target roll as a property for the reference. If you had <reference>0.0</reference>, bind your reference to a property (<reference>autopilot/settings/target-roll-deg</reference>) and your aircraft should roll to any value you set in target-roll-deg. The complete wing-leveler will look similar to the one below (though, the config values may vary and the reference might be replaced by a property).

  <pid-controller>

   <name>Heading hold</name>

   </config>

  </pid-controller>

This is the base for any lateral hold mode, so try to spend some time on it. It can take some hours if this is your first autopilot.

There is a filter to simulate that behaviour, it's the noise-spike filter. Here is a sample with 25 seconds transition time from -1 to +1:

  <filter>

   <name>SERVO-DRIVER:elevator</name>

   <max-rate-of-change>0.08</max-rate-of-change>

  </filter>

The formula for max-rate-of-change is (max-out - min-out)/transition-time. In our example (1--1)/25=2/25=0.08. Try it out, disable your pitch-hold controller and enable the servo-driver. Set your some/internal/elevator-cmd property to +1 and see your elevator moving to fully up or down within 12.5 seconds. Now set your property to -1 and it will take 25 seconds for the elevator to move to the other direction. The feedback-if-disabled property is needed, if this stage is driven from a pid-controller.  

== A simple auto throttle ==

  <pid-controller>

   <name>Auto throttle</name>

   </config>

  </pid-controller>

And a filter, as our autopilot does not move the throttle levers up/down in split seconds (you can imagine how that would be potentially harmful to the flight crew). Depending on the number of engines of your aircraft, you might want to add more or delete some output properties.

  <filter>

   <name>SERVO-DRIVER:throttle</name>

   <max-rate-of-change>0.1</max-rate-of-change>

  </filter>

== Vertical speed hold ==

To get the current pitch to a property which will be modified by a pid-controller later, we will now create a controller which serves as a so called "sample-and-hold" element. It simply copies the input property value to the output property value until it is disabled. The same property, that disables the sample-and-hold controller will enable the pid-controller that computes the pitch for the rate-of climb.Here is a sample-and-hold controller implemented with a gain-filter:

  <filter>

   <name>AP:Pitch sample and hold</name>

   <output>/autopilot/internal/target-pitch-deg</output>

  </filter>

You probably have to adjust the property names. Note the condition element in the <enable> section - it has the same syntax as in the well-known <animation> elements. As long as the roc-lock property is false, input is copied to output. When it becomes true, the output property is no longer written by this filter and the next step can use this value as a start.  

Right behind this filter, add a pid-controller using your current rate-of-climb as input and a target-rate-of-climb as reference. Enable this pid if your pitch sample-and-hold is not enabled (use the same condition, just remove the <not> elements). Your output goes to target-pitch-deg which should be the same property as the input of your pitch-hold controller. Use the same procedure to obtain the values for Kp and Ti. Kp will be small. The offset computes in feet per minute and 100fpm should result in a few degrees pitch change. Something like 0.01 or smaller will probably do. I'd expect Integrator time around 10-50. You should clamp the target-pitch to something less than +/- 90° - probably -10° and +20° or whatever is a reasonable value for your aircraft. It could look like this:

  <pid-controller>

   <name>Vertical speed pitch hold</name>

   </config>

  </pid-controller>

== Logic-controlled properties ==

These two new elements should give you a rate-of-climb hold mode for your autopilot. If you are not yet confused which controllers should be enabled in what mode, you will be very soon as we will add even more elements. If you are in the need for some logic-controlled properties, the autopilot can do this, too - no need for [[nasal]] helpers! There is a <logic> element that does all the magic:

  <logic>

   <name>Electrical Power</name>

   <output>autopilot/servicable</output>

  </logic>

This creates two boolean properties: has-power and serviceable, and sets them to true if the electrical system provides more than 10.0 volts. You can build complex logic tables to drive your analog stages of the autopilot.

Now, that you have a ROC-hold mode, you most certainly want an altitude-hold with preselect. This will be a simple linear amplifier without any time dependencies. Again, you have to compare your current altitude with a reference value, but this time there will be no integrator involved. The bigger your offset from the reference altitude is, the bigger your rate of climb/descent should be. Let's assume, 1000ft offset should result in 500fpm ROC. The maximum rate of descent should be 1000fpm and the maximum rate of climb should be 2000fpm. Since there is no integrator involved, we use a simple gain filter to compute the rate of climb:

  <filter>

   <name>Target Rate of Climb Computer (ALT HOLD)</name>

   <max>2000</max>

  </filter>

If everything goes well, your chain of controllers for altitude hold looks something like this:

For heading hold, you build a two stage system. The first is a comparator comparing your selected heading and the indicated heading. 1. Stage, compute heading offset. Note the period element at the bottom, it normalizes the output into the periodic -180 to +180 range

  <filter>

   <name>Heading Offset Computer</name>

   </period>

  </filter>

The second stage computes a bank angle from a heading offset. At least for smaller planes, a rule of thumb says "roll out at half the bank angle". If you fly a right hand turn at a bank angle of, say, 20° and want to end at a heading of 270°, you start your roll out at 20°/2 = 10° before your target heading. So you start rolling out at 280°. We turn this rule around and say our bank angle is twice the heading error but not more that 30° This results in a simple gain filter. You might want to make the target roll computer switchable with an enable element, otherwise it will overwrite your target-roll-deg at all times.

  <filter>

   <name>Target Roll Computer</name>

   <max>30.0</max>

  </filter>

Most aircraft have pilot selectable bank-limits. You can implement these by editing the min and max options to something like this:

  ...

   <min>

   <max>/autopilot/settings/bank-limit</max>

  ...

This filter feeds your wing leveler which is already done, but it requires a little edit in the <enable> and <reference> parts in order to obtain a pilot-selectable roll:

  ...

   <enable>

   </reference>

  ...

You can also play with the min/max values to have a nice standard rate turn. The bank angle for the standard turn is a function of your true airspeed; you can build a controller calculating the correct bank angle and feed this value into min/max (which is a commen feature on airliners).

First, add a new, switchable input element to your heading offset computer. Just change this:

  <filter>

   <name>Heading Offset Computer</name>

   </period>

  </filter>

to this (that is, adding the upper input part):

  <filter>

   <name>Heading Offset Computer</name>

   </period>

  </filter>

Now, if /autopilot/locks/heading equals "nav1-hold", the heading offset computer uses the intercept-heading-deg property as the target heading to fly.For any other value, the old heading-bug value is used. You can already test, if it works. Use the property browser to set this stage to nav-hold and enter any arbitrary value into intercept-heading-deg. Your aircraft should turn to the entered heading on the shortest path. It is crucical that this mode is stable, so spend some time again and double check.

This is a very simple stage, it just substracts a course error (which we will compute in the next stage) from our selected course and normalizes the output into the [0..360] degree interval:

  <filter>

   <name>Intercept Heading Computer</name>

   </period>

  </filter>

This stage only makes sense with a preceding one computing the course error from the cdi deflection. We want something that spits out 45 for a full CDI deflection and one might think of a <gain> filter to do this. But we also want an automatic wind correction in case of cross wind. For that we also need an integrator. Because we need to compute absolute values for the output, a pi-simple-controller is our choice here:

  <pi-simple-controller>

   <name>cdi-integrator</name>

   <max>45.0</max>

  </pi-simple-controller>

It takes our CDI deflection and compares to zero (note the missing reference element which defaults to zero). The result is multiplied by Kp (45) and a value of 0.4° per second is added to the offset. The output is clipped to 45°.