Autopilot configuration reference: Difference between revisions

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 [[Git]] sources. Some of the elements may not be available in the current release version of FlightGear.

{{Systems_Modeling_Disclaimer}}

For built-in runtime plotting of FlightGear properties (including FDM/Autopilot properties), check out [[FGPlot]] (available in FlightGear 2.11+).

<syntaxhighlight lang="xml">

  <?xml version="1.0" encoding="UTF-8"?>

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.

<syntaxhighlight lang="xml">

   <autopilot>

</syntaxhighlight>

<syntaxhighlight lang="xml">

  <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.

Property-rules can also be used in which case they will run at frame rate. You can use these to process properties so their values can be used by other systems outside of the autopilot scope (for example to create smooth animations for switches that normally have discrete values)

To achieve this load your filters configuration by adding:

<syntaxhighlight lang="xml">

   <property-rule n="100">  <!-- "n" needs to be >= 100 to avoid overwriting other predefined global rules (in particular the environment ones) -->

to the :

<syntaxhighlight lang="xml">

  <sim>

node of your aircraft-set.xml file. Note that you can add multiple <property-rule> elements, similar to the <autopilot> as described above.

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.

* <flipflop>

The <name> 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>

The <feedback-if-disabled> element advises the controller to feed back the output property value to the active input property if the

condition defined in the <enable> 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>

If the <debug> 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>

Example for a simple differential amplifier, computing output = (input-reference)*2

<syntaxhighlight lang="xml">

  <filter>

</syntaxhighlight>

  <output>controls/flight/elevator</output>

   

Controllers can be enabled or disabled using property values. This element <enable> may contain a <prop> and a <value> 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 <condition> element to the <enable> element. This <condition> 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° of bank, use this condition

<syntaxhighlight lang="xml">

  <enable>

</syntaxhighlight>

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 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:

<syntaxhighlight lang="xml">

  <reference>

The shortcut syntax is also valid:

  <reference>/my/property</reference>

{{note|The shortcut syntax is only valid, if neither <property> nor <value> element exists.

{{note|For backward compatibility, the notation <prop> instead of <property> is also valid but considered deprecated and might go away in future releases.}}

Input values may be scaled and shifted before they are processed by the controller using the formula <tt>y = value * scale + offset</tt>

<syntaxhighlight lang="xml">

  <reference>

</syntaxhighlight>

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.

<syntaxhighlight lang="xml">

  <reference>

</syntaxhighlight>

To clamp the input to a minimum value, maximum value or both, the tags <tt><min></tt> and <tt><max></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:

<syntaxhighlight lang="xml">

  <reference>

</syntaxhighlight>

To use the absolute (unsigned) value of the input, add <tt><abs type="bool">true</abs></tt>.

<syntaxhighlight lang="xml">

  <reference>

==== Recursive definition ====

The elements <tt><scale></tt>, <tt><offset></tt>, <tt><min></tt> and <tt><max></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.

<syntaxhighlight lang="xml">

  <reference>

</syntaxhighlight>

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. A standard <tt><condition></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.

<syntaxhighlight lang="xml">

  <reference>

The <tt><scale></tt>, <tt><offset></tt>, <tt><min></tt> and <tt><max></tt> elements of input values itself currently don't support input value lists.

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 <period> 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.  

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"

|-

|-

|-

|-

|-

|-

|-

|}

<syntaxhighlight lang="xml">

  <output>/some/property</output>

</syntaxhighlight>

The logic controller provides a simple way of creating property values from the result of the condition expression in the <input> element. The condition expression is evaluated once per iteration and the result is written as a boolean value to the named output property or properties. An optional <inverted> element inverts the logic. The default is "not inverted".

Example: output = not( ( a is true ) or ( ( b greater than c ) and ( d is true ) )

<syntaxhighlight lang="xml">

  <logic>

</syntaxhighlight>

A flip flop is a controller that has two stable states so it can be used as a one bit memory. Four types of flip flops are implemented: '''RS''', '''JK''', '''D''' and '''T'''. All use positive logic and operate on the raising edge of the clock signal if a clock is used.

All input lines, including the clock line, are encoded as condition constructs.

{{note|Using <code><nowiki><condition></nowiki></code> tags will break the logic.}}

This flip flop sets its output according to the set (S) or reset (R) input lines. If the set line is set, the output gets set. If the reset line is set, the output gets reset. If no line is set, the output stays unchanged. For the special case where set and reset lines are both set, two types of RS flip flops exist: for the RS flip flop (<type>RS</type>), the reset line is dominant and the output is reset. Alternatively, a SR flip flop (<type>SR</type>) has a dominant set line and the output gets set if set and reset line are set.

Example: simple RS flip flop

<syntaxhighlight lang="xml">

  <flipflop>

</syntaxhighlight>

The JK flip flop is an extension of the RS flip flop. In addition to the set and reset lines of the RS flip flop it uses J, K and a clock input.

The J line serves as a clock dependent set input while the K line does the reset job. Optionally, a clock input may be provided. State changes do not occour immediately, but on the next raising edge of the clock signal. The state of J=K=true causes the output to toggle it's current state on the next raising edge of the clock signal.

Example: simple JK flip flop with negative edge clock

<syntaxhighlight lang="xml">

  <flipflop>

</syntaxhighlight>

The D flip flop transfers the state of the input signal '''D''' to the output line at the next raising edge of the clock signal, which is mandatory for this flip flop.

Example: simple D flip flop with inverted output

<syntaxhighlight lang="xml">

  <flipflop>

</syntaxhighlight>

The T flip flop toggles the state of the output signal at the next raising edge of the clock signal, which is mandatory for this flip flop.

Example: simple T flip flop

<syntaxhighlight lang="xml">

  <flipflop>

</syntaxhighlight>

A monostable flip flop has only one stable state which will be reentered after a well defined time. The stable state in current implementation is the output set 'false' or 0. The Monostable is an extension of the JK flip flop. Additionally to the input values defined there, an InputValue for the definition of the pulse time is mandatory.  

In this example the monostable is inverted, which means the stable state is true instead of false. The key idea here is to keep the monostable in its unstable state (false) by keeping the set line true, which is the case when /myflipflop/s is false. Then, when /myflipflop/s becomes true the set line becomes false, which causes the timer to start. When the timer expires (in this case 10 seconds) the monostable will enter its stable state (true). At any time when the set line becomes true (when /myflipflop/s becomes false) the monostable will immediately enter its unstable state (false) again, resulting in /myflipflop/output to become false immediately.

A gain filter multiplies the <input> value by a given factor or gain <gain> and returns the output to <output>. More than one <gain> element formatted as in [[Autopilot Configuration Reference#Input Values|Input Values]] may be present.  Within a <condition> evaluating as true the first <gain> will define the used gain.

</syntaxhighlight>

The exponential filter is a typical [http://en.wikipedia.org/wiki/Low-pass_filter low pass filter]. The magic euler number and the associated mathematical funtion exp() plays a major role here. As the name implies, lower frequencies can pass this filter while higher frequencies are cut. The frequency where only half of the input signal reaches the output is called cutoff frequency. This cutoff frequency is defined by the parameter <filter-time> and resolves as cutoff-frequency = 1/(2*pi*cutoff-frequency).

</syntaxhighlight>

The double exponential filter is a low pass filter like the exponential filter with a steeper slope of the filter diagram. It acts basically like two chained exponential filters and it is some times called second order filter.  

The configuration is the same for exponential and double-exponential filters, just the type entry differs.

<syntaxhighlight lang="xml">

  <filter>

</syntaxhighlight>

Calculates average of specified number of values.

Currently the average length can only be given as number of samples and not time.

<syntaxhighlight lang="xml">

  <filter>

</syntaxhighlight>

A better name for a noise spike filter would probably have been "rate limit filter". This is exactly what it does: limit the rate of change of the output value. The relevant configuration element is <max-rate-of-change> setting the maximum rate of change of the output property per second.

Example: A transition from 0 to 4 at the input property results in a linear increase of the output property over 8 seconds from 0 to 4 at a rate of 0.5/sec.

<syntaxhighlight lang="xml">

  <filter>

</syntaxhighlight>

Compute the reciprocal (1/x) value of the input property. If x is zero, no computation is performed. The optional <gain> element may be used to scale the value. Output computes as gain divided by input.

Example: compute the flight time per pound of burned fuel from the fuel flow

<syntaxhighlight lang="xml">

  <filter>

</syntaxhighlight>

Compute first time derivative of the input property, that is change per unit of time. Time is measured in seconds. A <filter-time> acts as gain and must be given because it has default 0.

Example: compute derivative of static port pressure

<syntaxhighlight lang="xml">

  <filter>

</syntaxhighlight>

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>.

|}

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>

|}

Estimates the future value for a given property based on its current (or averaged) rate of change.

Example: compute estimated speed 5 seconds ahead

<syntaxhighlight lang="xml">

  <predict-simple>