Hi fellow wiki editors!

To help newly registered users get more familiar with the wiki (and maybe older users too) there is now a {{Welcome to the wiki}} template. Have a look at it and feel free to add it to new users discussion pages (and perhaps your own).

I have tried to keep the template short, but meaningful. /Johan G

Difference between revisions of "Autopilot configuration reference"

From FlightGear wiki
Jump to: navigation, search
(pid-controller: Chang formatting to use a definition list.)
(Input Values)
Line 52: Line 52:
  
 
=== Input Values ===
 
=== 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 properties 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 no &lt;property&gt; '''and''' no &lt;value&gt; element exist.
 +
 +
=== 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>
 +
 +
=== 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 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>
  
 
=== Output Values ===
 
=== Output Values ===

Revision as of 05:48, 5 May 2010

WIP.png Work in progress
This article or section will be worked on in the upcoming hours or days.
See history for the latest developments.

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 extern file using <params include="my-params.xml"/> 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 developer 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>.

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

There is no restriction regarding the top level nodes under the PropertyList root node. Nodes, that create instances of filters and controllers are

  • <pid-controller>
  • <pi-simple-controller>
  • <filter>
  • <predict-simple>

Common Elements Used By All Filters

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 reference element as an example but it may be substituted by any other input element like Kp, gain 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 strtod() 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 properties 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 no <property> and no <value> element exist.

Linear transformation of the input value

Input values may be scaled and shifted before they are processed by the controller using the formula y = value * scale + offset 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>

Input clamping

To clamp the input to a minimum value, maximum value or both, the tags <min> and <max> 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 value of the input, add <abs type="bool">true</abs>.

<reference>
  <property>/autopilot/internal/course-error-deg</property>
  <abs type="bool">true</abs>
</reference>

Recursive definition

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

Output Values

filter

gain

exponential

double-exponential

moving-average

noise-spike

reciprocal

pid-controller

The [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 calmping 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 <pid-controller>. Legal elements are:

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 <pi-simple-controller> Legal elements are:

Kp
gain of the proportional component
Ki
gain of the integrator component

predict-simple

logic