View source for Autopilot configuration reference

{{WIP}}

This page serves as a reference for the elements of FlightGear xml autopilot configuration files. It describes all elements available within the autopilot configuration file supported in the bleeding edge CVS sources. Some of the elements may not be available in the current release version of FlightGear.
Refer to [[Howto: Design an autopilot]] as a guide how to use these elements.

== Structure Of a Configuration File ==
Autopilot configurations live in a separate file, formatted using the well known XML syntax like so many other FlightGear files with a PropertyList node as a root element. A basic skeleton file looks like this:
 <?xml version="1.0" encoding="utf8"?>
 <PropertyList>
   <params>
     <controls>
       <aileron>controls/flight/aileron</aileron>
       <rudder>controls/flight/rudder</rudder>
       <elevator>controls/flight/elevator</elevator>
     </controls>
   </params>
   
 </PropertyList>
Note: Using aliased property names is good style and makes the configuration file more readable. For complex autopilot systems spread over multiple autopilot configuration files, the params section may be included from an external file using <tt><params include="my-params.xml"/></tt> to avoid duplication of code.

The location and the name of the configuration file is up to the developer. A descriptive name like 'autopilot.xml' might be a good choice. Most developers put these files into the Systems folder of the aircraft.

== Adding a Autopilot Configuration to Aircraft ==
Autopilot configuration files are added to the aircraft by adding 
  <autopilot>
    <path>Aircraft/MyAircraft/Systems/my-autopilot.xml</path>
  </autopilot>
to the 
 <sim>
   <systems>
     <!- - many other elements live here - ->
     <autopilot>
       <path>Aircraft/MyAircraft/Systems/my-autopilot.xml</path>
     </autopilot>
   </systems>
  </sim>
node of your aircraft-set.xml file. Note, that more than one <autopilot> node may be present, each will create a new instance of the autopilot subsystem when running FlightGear. They run in the order of appearance under <systems>. For example, lateral and vertical autopilot modes could live in separate files, as could a yaw-damper system.

== Available Elements ==
All elements may contain the attributes "include" and "alias". 
The "include" property takes a file name as a parameter. This can be used to read the document tree of an external XML file into the node containing the "include" attribute. The included file must have a PropertyList node as the root node. All nodes under this PropertyList node will be added to the node containing the "include" attribute.
The "alias" attribute refers to an element defined elsewhere in this XMl document. Alias references are in a path-style syntax, either as a relative or absolute path. Absolute paths start with a slash, like <foo alias="/params/bar/baz"/>. Use the colon to move through the document tree, similar to file system paths like <foo alias="../../bar/baz"/>.

Any top-level element can appear in an autopilot XML file, but only the following elements will be recognised and used:
* <pid-controller>
* <pi-simple-controller>
* <filter>
* <predict-simple>

== Common Elements Used By All Elements ==

=== Name ===
The &lt;name&gt; element is optional, but should be added to give the controller a distinct name. It is only used in debug output.
 <name>NAV hold</name>

=== Feedback if disabled ===
The &lt;feedback-if-disabled&gt; element advises the controller to feed back the output property value to the active input property if the
condition defined in the &lt;enable&gt; tag evaluates to false. This is usually required for controllers like servo drivers behind a PID-controller to give that PID-controller a valid starting value when it becomes enabled. The absence of this element or anything but the word ''true'' within this element results in feedback disabled.
 <feedback-if-disabled>true</feedback-if-disabled>

=== Debug ===
If the &lt;debug&gt; element is present and if it contains the word ''true'', the containing controller prints out some diagnostic information on the console for each processing loop.
 <debug>true</debug>

=== Input and Reference ===
Each controller has two input "lines", denoted by the tags &lt;input&gt; and &lt;reference&gt;. The arithmetic difference of these two values is used by the respective controller to compute it's output. Unfortunately due to historical reasons, the sign of input and reference is not consistent for all controllers. While the pid-controller and the pi-simple-controller compute "reference-input", the filter controller computes "input-reference". Each element is optional with a default value of zero. These elements are made of so called '''Input Values''' described further down in this document.
Example for a simple differential amplifier, computing output = (input-reference)*2
 <filter>
   <type>gain</type>
   <gain>1.0</gain>
   <input>/some/input</input>
   <reference>/some/output</reference>
   <output>/some/output</output>
 </filter>

=== Output ===
The &lt;outptu&gt; element names the properties, the computed value should be written to. More than one &lt;output&gt; may be present, each named property will be assigned the computed value.
 <output>controls/flight/elevator</output>
 
=== Enable ===
Controllers can be enabled or disabled using property values. This element &lt;enable&gt; may contain a &lt;prop&gt; and a &lt;value&gt; element. The controller is enabled, if the value of the named property equals the given value. This feature is considered deprecated and might go away in future releases. The preferred way of defining the enable-condition is by adding a &lt;condition&gt; element to the &lt;enable&gt; element. This &lt;condition&gt; follows the same syntactical rules as the one used in model animations and can model complex expression trees.
To enable a wing leveler only if the current bank angle does not exceed 30&deg; of bank, use this condition
 <enable>
   <condition>
     <less-than>
       <property>orientation/bank-angle-deg</property>
       <value>30.0</value>
     </less-than>
     <greater-than>
       <property>orientation/bank-angle-deg</property>
       <value>-30.0</value>
     </greater-than>
   </condition>
 </enable>

=== Input Values ===
Input values for controllers may be specified in several notations. Values may be supplied as constants, from properties or by means of simple linear transformations. Conditions allow the selection of one of multiple input sources. The following text will use the <tt>reference</tt> element as an example but it may be substituted by any other input element like <tt>Kp</tt>, <tt>gain</tt> etc. Input values will be interpreted as double values.

==== A constant value ====
A constant value is defined by just adding the value as text to the input element: 
 <reference>
   <value>3.5</value>
 </reference>
The shortcut syntax is also valid:
 <reference>3.5</reference>
If the text can be parsed by <tt>strtod()</tt> to a double value, it will be used as a constant value, otherwise it will be interpreted as a property value (see next paragraph)

==== A property value ====
To evaluate the value of a property, place the name of the property into the text element:
 <reference>
   <property>/my/property</property>
 </reference>
The shortcut syntax is also valid:
 <reference>/my/property</reference>
Note: the shortcut syntax is only valid, if neither &lt;property&gt; nor &lt;value&gt; element exists.
If both, &lt;property&gt; '''and''' &lt;value&gt; element exist, the property will be initialized with the given value with scale and offset applied correctly.
Properties don't have to exist, the will be created as needed.

'''Note:''' for backward compatibility, the notation &lt;prop&gt; instead of &lt;property&gt; is also valid but considered deprecated and might go away in future releases.

==== Linear transformation of the input value ====
Input values may be scaled and shifted before they are processed by the controller using the formula <tt>y = value * scale + offset</tt>
To use a celsius temperature property in a controller which expects the temperature in fahrenheit you might use
 <reference>
   <property>/environment/temperature-degc</property>
   <scale>1.8</scale>
   <offset>32</offset>
 </reference>

==== Periodical transformation of the input value ====
Periodical (like angular) input values can be transformed to appear in the correct phase before they are processed by the controller by adding or substracting multiples of the period to the input value until the values is in the requested periods interval.
The following example converts the heading which comes in the range of [0..360] into the range of [-180..+180]. This will cause a heading of 270 to be processed as a value of -90.
 <reference>
   <property>/orientation/heading-deg</property>
   <period>
     <min>-180.0</min>
     <max>180.0</max>
   </period>
 </reference>

==== Input clamping ====
To clamp the input to a minimum value, maximum value or both, the tags <tt>&lt;min&gt;</tt> and <tt>&lt;max&gt;</tt> can be used. Clamping will occur after the linear transformation has been applied. Note the difference of input clamping to output clamping. While input clamping is applied '''before''' the signal reaches the controller, output clamping will be applied to the output signal '''after''' it has been processed.
The following code will keep the input to the controller in the range of 60 to 80 degrees Fahrenheit:
 <reference>
   <property>/environment/temperature-degc</property>
   <scale>1.8</scale>
   <offset>32</offset>
   <min>60</min>
   <max>80</max>
 </reference>

==== Absolute values ====
To use the absolute (unsigned) value of the input, add <tt>&lt;abs type="bool"&gt;true&lt;/abs&gt;</tt>.
 <reference>
   <property>/autopilot/internal/course-error-deg</property>
   <abs type="bool">true</abs>
 </reference>

==== Recursive definition ====
The elements <tt>&lt;scale&gt;</tt>, <tt>&lt;offset&gt;</tt>, <tt>&lt;min&gt;</tt> and <tt>&lt;max&gt;</tt> itself can be defined as input values. This code uses as reference the value of course-error-deg, scaled by two and an offset applied which is calculated as the product of the bank-angle-de and the property some/property which itself is limited within the range of -1.5 .. +1.5.
 <reference>
   <property>/autopilot/internal/course-error-deg</property>
   <scale>2.0</scale>
   <offset>
     <property>orientation/bank-angle-deg</property>
     <scale>
       <property>some/property
       <min>-1.5</min>
       <max>1.5</max>
     </scale>
   </offset>
 </reference>

==== Conditional input values ====
The direct inputs of controller and filter elements support so called input value lists. This is useful, if the input should be connected to one of many separate inputs like autopilots connected to NAV1, NAV2 or the GPS. The well known <tt>&lt;condition&gt;</tt> element is allowed within an input value element. The input value list will be traversed until the first input value with a successful condition is found. The behavior is much like the switch statement in programming languages.
 <reference>
   <condition>
     <property>/autopilot/coupled-to-gps</property>
   </condition>
   <property>instrumentation/gps/desired-track-deg</property>
 </reference>
 <reference>
   <condition>
     <property>/autopilot/coupled-to-nav2</property>
   </condition>
   <property>instrumentation/nav[1]/radials/selected-deg</property>
 </reference>
 <reference>instrumentation/nav[0]/radials/selected-deg</reference>
Note the unconditional last <tt>&lt;reference<&gt;</tt> element which acts as an "if all others fail, use NAV1" anchor. If no input value return with a successful condition, the input value is undefined.<br />
The <tt>&lt;scale&gt;</tt>, <tt>&lt;offset&gt;</tt>, <tt>&lt;min&gt;</tt> and <tt>&lt;max&gt;</tt> elements of input values itself currently don't support input value lists.

=== Output Values ===
After processing of a component, the resulting value passes a transformation stage where it can be clipped or normalized into a given period. Periodic values such as angular properties may be normalized into a given period by adding a &lt;period&gt; element, defining the lower and upper bounds of the period. Additionally, a maximun and a minimum value may be given which will guarantee that the output value will ever exceed a defined value. 

'''Note:''' Both, periodical normalization and clipping may be defined. If both are given, the value will be normalized first and the clipping will be applied to the normalized value.

The following example shifts the computed value into the interval of [-180..180] thereafter being limited into the interval of [-30..30]. The following table contains some computed values and the resulting written value:
{| class="prettytable"
!computed
!written
|-
|-
| -350
|10
|-
| -270
|30
|-
| -90
| -30
|-
| -29
| -29
|-
|29
|29
|-
|90
|30
|-
|350
| -10
|}

 <output>/some/property</output>
 <period>
   <min>-180</min>
   <max>180</max>
 </period>
 <min>-30</min>
 <max>30</max>

== filter ==

=== gain ===
=== exponential ===
=== double-exponential ===
=== moving-average ===
=== noise-spike ===
=== reciprocal ===

== pid-controller ==
The [http://en.wikipedia.org/wiki/PID_controller PID controller] is the swiss army knife of automation and this implementation is suitable for most situations. It has a builtin anti-windup logic, and usage of <max> and <min> elements for clamping the output is mandatory. The most important thing to know is that this controller 'does not' compute absolute output values but an offset from the current value of the output property. This can lead to unexpected behavior if the current value of the output property is unknown when the controller is enabled. This behavior is different to that of the pi-simple-controller.
The xml element creating a pid controller is <tt><pid-controller></tt>.

Legal elements are:

{| class="prettytable"
!Kp
|the overall gain for the proportional, integral and derivative part
|-
!Ti
|integrator time
|-
!Td
|derivator time
|-
!Ts
|sampling interval (default: sample at frame rate)
|-
!alpha
|scaling factor for Td (defaults to 0.1)
|-
!beta
|reference weighing factor for the proportional component (defaults to 1.0)
|-
!gamma
|reference weighing factor for the derivate component (defaults to 0.0)
|}

== pi-simple-controller ==
This controller implements a PI controller. Other than the PID controller, it computes absolute output values, regardless of the value of the output property. It can by configured as an I-only, P-only or PI-controller. It has anti windup logic if <min> and <max> elements are present.
The xml element creating a PI controller is <tt><pi-simple-controller></tt>
Legal elements are:

{| class="prettytable"
!Kp
|gain of the proportional component
|-
!Ki
|gain of the integrator component
|}

== predict-simple ==

== logic ==