docs-mini/README.digitalfilters

   1 COMMON SETTINGS
   2 ==============================================================================
   3
   4 Currently four types of digital filter implementations are supported. They all serve an
   5 individual purpose or are individual implementations of a specific filter type.
   6 Each filter implementation uses the same set of basic configuration tags and individual
   7 configuration elements. These individual elements are described in the section of the
   8 filter.
   9
  10 The InputValue
  11 ==============================================================================
  12 Each filter has several driving values, like the input value itself, sometimes a reference
  13 value, a gain value and others. Most of these input values can bei either a constant value
  14 or the value of a property. They all use the same syntax and will be referred to as InputValue
  15 in the remaining document.
  16
  17 The complete XML syntax for a InputValue is
  18
  19 <some-element>
  20   <property>/some/property/name</property>
  21   <value>0.0</value>
  22   <scale>1.0</value>
  23   <offset>0.0</offset>
  24 </some-element>
  25
  26 The enclosing element <some-element> is the element defined in each filter, like <input>, <u_min>,
  27 <reference> etc. These elements will be described later.
  28 The value of the input is calculated based on the given value, scale and offset as
  29 value * scale + offset.
  30 With the full set of given elements, the InputValue will initialize the named property to the value
  31 given, reduced by the given offset and reverse scaled by the given scale.
  32
  33 Example:
  34 <input>
  35   <property>/controls/flight/rudder</property>
  36   <value>0.0</value>
  37   <scale>0.5</scale>
  38   <offset>0.5</offset>
  39 </input>
  40
  41 Will use the property /controls/flight/rudder as the input of the filter. The property will be initialized
  42 at a value of zero and since the property usually is in the range [-1..+1], the the value of <input> will
  43 be in the range (-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1].
  44
  45 The default values for elements not given are:
  46 <value/> : 0.0
  47 <scale/> : 1.0
  48 <offset/>: 0.0
  49 <property/> : none
  50
  51 Some examples:
  52 <input>
  53   <property>/position/altitude-ft</property>
  54   <scale>0.3048</scale>
  55 </input>
  56 Gives the altitude in meters. No initialization of the property is performed, no offset applied.
  57
  58 <reference>
  59   <value>0.0</value>
  60 </reference>
  61 A constant reference of zero.
  62
  63 A abbreviated method of defining values exist for using a just constant or a property. The above
  64 example may be written as
  65 <reference>0.0</reference>
  66 Or if the reference is defined in a property
  67 <reference>/some/property/name</reference>
  68 No initialization, scaling or offsetting is performed here.
  69 The logic behind this is: If the text node in the element (the text between the opening and closing tag)
  70 can be converted to a double value, it will be interpreted as a double value. Otherwise the text will
  71 be interpreted as a property name.
  72 Examples:
  73 <reference>3.1415927</reference>             - The constant of PI (roughly)
  74 <reference>/position/altitude-ft</reference> - The property /position/altitude-ft
  75 <reference>3kings</reference>                - The constant 3. The word kings is ignored
  76 <reference>food4less</reference>             - The property food4less
  77
  78 The <property> element may also be written as <prop> for backward compatibility.
  79
  80 OutputValue
  81 ==============================================================================
  82 Each filter drives one to many output properties. No scaling of offsetting is implemented
  83 for the output value, these should be done in the filter itself.
  84 The output properties are defined in the <output/> element by adding <property/> elements
  85 within the <output/> element. For just a single output property, the <property/> element
  86 may be ommited. For backward compatibility, <property/> may be replaced by <prop/>.
  87 Nonexisting properties will be created with type double.
  88
  89 Example: (Multiple output properties)
  90 <output>
  91   <property>/some/output/property</property>
  92   <property>/some/other/output/property</property>
  93   <property>/and/another/output/property</property>
  94 </output>
  95
  96 Example: a single output property
  97 <output>/just/a/single/property</output>
  98
  99 Other Common Settings
 100 ==============================================================================
 101 <name>        String      The name of the filter. Used for debug purpose.
 102 Example:
 103 <name>pressure rate filter</name>
 104
 105 <debug>       Boolean     If true, this filter puts out debug information when updated.
 106 Example:
 107 <debug>false</debug>
 108
 109 <input>       InputValue  The input property driving the filter.
 110                           Refer to InputValue for details.
 111
 112 <reference>   InputValue  The reference property for filter that need one.
 113                           Refer to InputValue for details.
 114
 115 <output>      Complex     Each filter can drive one to many output properties.
 116                           Refer to OutputValue for details.
 117
 118 <u_min>       InputValue  This defines the optional minimum and maximum value the output
 119 <u_max>                   is clamped to. If neither <u_min> nor <u_max> exists, the output
 120                           is only limited by the internal limit of double precision float computation.
 121                           If either <u_min> or <u_max> is given, clamping is activated. A missing
 122                           min or max value defaults to 0 (zero).
 123                           Note: <u_min> and <u_max> may also occour within a <config> element.
 124
 125 Example: Limit the pilot's body temperature to a constant minimum of 36 and a maximum defined in
 126          /pilots/max-body-temperature-degc, initialized to 40.0
 127 <u_max>
 128   <prop>/pilots/max-body-temperature-degc</prop>
 129   <value>40.0</
 130 </u_max>
 131 <u_min>
 132   <value>36.0</value>
 133 </u_min
 134
 135 Implicit definition of the minimum value of 0 (zero) and defining a maximum of 100.0
 136 <config>
 137   <u_max>100.0</u_max>
 138 </config>
 139
 140 <enable>      Complex     Define a condition to enable or disable the filter. For disabled
 141                           filters, no output computations are performed. Only enabled
 142                           filters fill the output properties. The default for undefined
 143                           conditions is enabled.
 144                           Several way exist to define a condition. The most simple case
 145                           is checking a boolean property. For this, just a <prop> element
 146                           naming this boolean property is needed. The boolean value of the
 147                           named property defines the enabled state of the filter.
 148                           To compare the value of a property with a constant, a <prop> and
 149                           a <value> element define the property name and the value to be
 150                           compared. The filter is enabled, if the value of the property
 151                           equals the given value. A case sensitive string compare is
 152                           performed here.
 153                           To define more complex conditions, a <condition> element may be
 154                           used to define any condition described in README.conditions.
 155                           If a <condition> element is present and if it contains a valid
 156                           condition, this conditions has precedence over a given <prop>/
 157                           <value> condition.
 158                           The child element <honor-passive>, a boolean flag, may be present
 159                           within the <enable> element. If this element is true, the property
 160                           /autopilot/locks/passive-mode is checked and if it is true, the
 161                           filter output is computed, but the output properties are not set.
 162                           The default for honor-passive is false
 163 Example: Check a boolean property, only compute this filter if gear-down is true and
 164          /autopilot/locks/passive-mode is false
 165 <enable>
 166   <prop>/gear/gear-down</prop>
 167   <honor-passive>true</honor-passive>
 168 </enable>
 169
 170 Check a property for equality, only compute this filter if the autopilot is locked in heading mode.
 171 <enable>
 172   <prop>/autopilot/locks/heading</prop>
 173   <value>dg-heading-hold</value>
 174 </enable>
 175
 176 Use a complex condition, only compute this filter if the autopilot is serviceable and the lock
 177 is either dg-heading-hold or nav1-heading-hold
 178 <enable>
 179   <condition>
 180     <property>/autopilo/serviceable</property>
 181     <or>
 182       <equals>
 183         <property>/autopilot/locks/heading</property>
 184         <value>dg-heading-hold</value>
 185       </equals>
 186       <equals>
 187         <property>/autopilot/locks/heading</property>
 188         <value>nav1-heading-hold</value>
 189       </equals>
 190     </or>
 191   </condition>
 192 </enable>
 193
 194 INDIVIDUAL FILTER CONFIGURATION
 195 ==============================================================================
 196
 197 Digital Filter
 198
 199 Six different types of digital filter can be configured inside the autopilot
 200 configuration file. There are four low-pass filter types and two gain filter
 201 types.
 202
 203 The low-pass filter types are:
 204
 205 * Exponential
 206 * Double exponential
 207 * Moving average
 208 * Noise spike filter
 209
 210 The gain filter types are:
 211
 212 * gain
 213 * reciprocal
 214
 215 To add a digital filter, place a <filter> element under the root element. Next to
 216 the global configuration elements described above, the following elements configure
 217 the digital filter:
 218 <filter-time> InputValue  This tag is only applicable for the exponential and
 219                           double-exponential filter types. It controls the bandwidth
 220                           of the filter. The bandwidth in Hz of the filter is:
 221                           1/filter-time. So a low-pass filter with a bandwidth of
 222                           10Hz would have a filter time of 1/10 = 0.1
 223
 224 <samples>     InputValue  This tag only makes sense for the moving-average filter.
 225                           It says how many past samples to average.
 226
 227 <max-rate-of-change>
 228               InputValue  This tag is applicable for the noise-spike filter.
 229                           It says how much the value is allowed to change per second.
 230
 231 <gain>        InputValue  This is only applicable to the gain and reciprocal filter types.
 232                           The output for gain filter is computed as input*gain while
 233                           the reciprocal filter computes output as gain/input for input
 234                           values != 0 (zero). Gain may be a constant, a property name
 235                           defined by a <prop> element within the <gain> element or a
 236                           property name initialized to a value by using a <prop> and
 237                           <value> element.
 238
 239 Example: a pressure-rate-filter implemented as a double exponential low pass filter
 240          with a bandwith of 10Hz
 241
 242   <filter>
 243     <name>pressure-rate-filter</name>
 244     <debug>false</debug>
 245     <type>double-exponential</type>
 246     <enable>
 247       <prop>/autopilot/locks/pressure-rate-filter</prop>
 248       <value>true</value>
 249     </enable>
 250     <input>/autopilot/internal/pressure-rate</input>
 251     <output>/autopilot/internal/filtered-pressure-rate</output>
 252     <filter-time>0.1</filter-time>
 253   </filter>
 254
 255 This will filter the pressure-rate property. The output will be to a new
 256 property called filtered-pressure-rate. You can select any numerical property
 257 from the property tree. The input property will not be affected by the filter,
 258 it will stay the same as it would if no filter was configured.
 259
 260 Example 2:
 261
 262   <filter>
 263     <name>airspeed elevator-trim gain reciprocal filter</name>
 264     <debug>false</debug>
 265     <enable>
 266       <prop>/autopilot/locks/airspeed-elevator-trim-gain</prop>
 267       <value>true</value>
 268     </enable>
 269     <type>reciprocal</type>
 270     <gain>
 271       <prop>/autopilot/settings/elevator-trim-airspeed-reciprocal-gain</prop>
 272       <value>7</value>
 273     </gain>
 274     <input>/velocities/airspeed-kt</input>
 275     <output>/autopilot/internal/elevator-trim-gain</output>
 276     <u_min>0.005</u_min>
 277     <u_max>0.02</u_max>
 278   </filter>
 279
 280 This will use the /velocities/airspeed-kt property to produce a gain factor
 281 that reduces as airspeed increases.  At airspeeds up to 350kt the gain will
 282 be clamped to 0.02, at 700kt the gain will be 0.01 and at 1400kt the gain will
 283 be 0.005.  The gain will be clamped to 0.005 for airspeeds > 1400kt.
 284
 285 The output from this filter could then be used to control the gain in a PID
 286 controller:
 287
 288   <pid-controller>
 289     <name>Pitch hold</name>
 290     <debug>false</debug>
 291     <enable>
 292       <prop>/autopilot/locks/pitch</prop>
 293       <value>true</value>
 294     </enable>
 295     <input>
 296       <prop>/orientation/pitch-deg</prop>
 297     </input>
 298     <reference>
 299       <prop>/autopilot/settings/target-pitch-deg</prop>
 300     </reference>
 301     <output>
 302       <prop>/autopilot/internal/target-elevator-trim-norm</prop>
 303     </output>
 304     <config>
 305       <Ts>0.05</Ts>
 306       <Kp>
 307         <prop>/autopilot/internal/elevator-trim-gain</prop>
 308         <value>0.02</value>
 309       </Kp>
 310       <beta>1.0</beta>
 311       <alpha>0.1</alpha>
 312       <gamma>0.0</gamma>
 313       <Ti>2.0</Ti>
 314       <Td>0.2</Td>
 315       <u_min>-1.0</u_min>
 316       <u_max>1.0</u_max>
 317     </config>
 318   </pid-controller>
 319
 320 IMPORTANT NOTE: The <Kp> tag in PID controllers has been revised to operate in
 321 the same way as the <gain> elements in filters.  However, the original format
 322 of <Kp> will continue to function as before i.e. <Kp>0.02</Kp> will specify a
 323 fixed and unalterable gain factor, but a warning message will be output.
 324
 325 The gain type filter is similar to the reciprocal filter except that the gain
 326 is applied as a simple factor to the input.
 327 -------------------------------------------------------------------------------
 328 Parameters
 329
 330 <name> The name of the filter. Give it a sensible name!
 331
 332 <debug> If this tag is set to true debugging info will be printed on the
 333 console.
 334
 335 <enable> Encloses the <prop> and <value> tags which are used to enable or
 336 disable the filter. Instead of the <prop> and <value> tags, a <condition>
 337 tag may be used to define a condition. Check README.conditions for more
 338 details about conditions.  Defaults to enabled if unspecified.
 339
 340 <type> The type of filter. This can be exponential, double-exponential,
 341 moving-average, noise-spike, gain or reciprocal.
 342
 343 <input> The input property to be filtered. This should of course be a
 344 numerical property, filtering a text string or a boolean value does not make
 345 sense.
 346
 347 <output> The filtered value. You can make up any new property.
 348
 349 <u_min> The minimum output value from the filter.  Defaults to -infinity.
 350
 351 <u_max> The maximum output value from the filter.  Defaults to +infinity.
 352
 353 These are the tags that are applicable to all filter types. The following tags
 354 are filter specific.
 355
 356 <filter-time> This tag is only applicable for the exponential and
 357 double-exponential filter types. It controls the bandwidth of the filter. The
 358 bandwidth in Hz of the filter is: 1/filter-time. So a low-pass filter with a
 359 bandwidth of 10Hz would have a filter time of 1/10 = 0.1
 360
 361 <samples> This tag only makes sense for the moving-average filter. It says how
 362 many past samples to average.
 363
 364 <max-rate-of-change> This tag is applicable for the noise-spike filter. Is
 365 says how much the value is allowed to change per second.
 366
 367 <gain>  This, and it's enclosed <prop> and <value> tags, are only applicable to
 368 the gain and reciprocal filter types.  The <prop> tag specifies a property node
 369 to hold the gain value and the <value> tag specifies an initial default value.
 370 The gain defaults to 1.0 if unspecified.
 371
 372 The output from the gain filter type is: input * gain.
 373 The output from the reciprocal filter type is: gain / input.
 374
 375 The gain can be changed during run-time by updating the value in the property
 376 node.