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