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