docs-mini/README.digitalfilters

   1 Six different types of digital filter can be configured inside the autopilot
   2 configuration file. There are four low-pass filter types and two gain filter
   3 types.
   4
   5 The low-pass filter types are:
   6
   7 * Exponential
   8 * Double exponential
   9 * Moving average
  10 * Noise spike filter
  11
  12 The gain filter types are:
  13
  14 * gain
  15 * reciprocal
  16
  17 Example 1:
  18
  19   <filter>
  20     <name>pressure-rate-filter</name>
  21     <debug>false</debug>
  22     <type>double-exponential</type>
  23     <enable>
  24       <prop>/autopilot/locks/pressure-rate-filter</prop>
  25       <value>true</value>
  26     </enable>
  27     <input>/autopilot/internal/pressure-rate</input>
  28     <output>/autopilot/internal/filtered-pressure-rate</output>
  29     <filter-time>0.1</filter-time>
  30   </filter>
  31
  32 This will filter the pressure-rate property. The output will be to a new
  33 property called filtered-pressure-rate. You can select any numerical property
  34 from the property tree. The input property will not be affected by the filter,
  35 it will stay the same as it would if no filter was configured.
  36
  37 Example 2:
  38
  39   <filter>
  40     <name>airspeed elevator-trim gain reciprocal filter</name>
  41     <debug>false</debug>
  42     <enable>
  43       <prop>/autopilot/locks/airspeed-elevator-trim-gain</prop>
  44       <value>true</value>
  45     </enable>
  46     <type>reciprocal</type>
  47     <gain>
  48       <prop>/autopilot/settings/elevator-trim-airspeed-reciprocal-gain</prop>
  49       <value>7</value>
  50     </gain>
  51     <input>/velocities/airspeed-kt</input>
  52     <output>/autopilot/internal/elevator-trim-gain</output>
  53     <u_min>0.005</u_min>
  54     <u_max>0.02</u_max>
  55   </filter>
  56
  57 This will use the /velocities/airspeed-kt property to produce a gain factor
  58 that reduces as airspeed increases.  At airspeeds up to 350kt the gain will
  59 be clamped to 0.02, at 700kt the gain will be 0.01 and at 1400kt the gain will
  60 be 0.005.  The gain will be clamped to 0.005 for airspeeds > 1400kt.
  61
  62 The output from this filter could then be used to control the gain in a PID
  63 controller:
  64
  65   <pid-controller>
  66     <name>Pitch hold</name>
  67     <debug>false</debug>
  68     <enable>
  69       <prop>/autopilot/locks/pitch</prop>
  70       <value>true</value>
  71     </enable>
  72     <input>
  73       <prop>/orientation/pitch-deg</prop>
  74     </input>
  75     <reference>
  76       <prop>/autopilot/settings/target-pitch-deg</prop>
  77     </reference>
  78     <output>
  79       <prop>/autopilot/internal/target-elevator-trim-norm</prop>
  80     </output>
  81     <config>
  82       <Ts>0.05</Ts>
  83       <Kp>
  84         <prop>/autopilot/internal/elevator-trim-gain</prop>
  85         <value>0.02</value>
  86       </Kp>
  87       <beta>1.0</beta>
  88       <alpha>0.1</alpha>
  89       <gamma>0.0</gamma>
  90       <Ti>2.0</Ti>
  91       <Td>0.2</Td>
  92       <u_min>-1.0</u_min>
  93       <u_max>1.0</u_max>
  94     </config>
  95   </pid-controller>
  96
  97 IMPORTANT NOTE: The <Kp> tag in PID controllers has been revised to operate in
  98 the same way as the <gain> elements in filters.  However, the original format
  99 of <Kp> will continue to function as before i.e. <Kp>0.02</Kp> will specify a
 100 fixed and unalterable gain factor, but a warning message will be output.
 101
 102 The gain type filter is similar to the reciprocal filter except that the gain
 103 is applied as a simple factor to the input.
 104 -------------------------------------------------------------------------------
 105 Parameters
 106
 107 <name> The name of the filter. Give it a sensible name!
 108
 109 <debug> If this tag is set to true debugging info will be printed on the
 110 console.
 111
 112 <enable> Encloses the <prop> and <value> tags which are used to enable or
 113 disable the filter. Instead of the <prop> and <value> tags, a <condition>
 114 tag may be used to define a condition. Check README.conditions for more
 115 details about conditions.  Defaults to enabled if unspecified.
 116
 117 <type> The type of filter. This can be exponential, double-exponential,
 118 moving-average, noise-spike, gain or reciprocal.
 119
 120 <input> The input property to be filtered. This should of course be a
 121 numerical property, filtering a text string or a boolean value does not make
 122 sense.
 123
 124 <output> The filtered value. You can make up any new property.
 125
 126 <u_min> The minimum output value from the filter.  Defaults to -infinity.
 127
 128 <u_max> The maximum output value from the filter.  Defaults to +infinity.
 129
 130 These are the tags that are applicable to all filter types. The following tags
 131 are filter specific.
 132
 133 <filter-time> This tag is only applicable for the exponential and
 134 double-exponential filter types. It controls the bandwidth of the filter. The
 135 bandwidth in Hz of the filter is: 1/filter-time. So a low-pass filter with a
 136 bandwidth of 10Hz would have a filter time of 1/10 = 0.1
 137
 138 <samples> This tag only makes sense for the moving-average filter. It says how
 139 many past samples to average.
 140
 141 <max-rate-of-change> This tag is applicable for the noise-spike filter. Is
 142 says how much the value is allowed to change per second.
 143
 144 <gain>  This, and it's enclosed <prop> and <value> tags, are only applicable to
 145 the gain and reciprocal filter types.  The <prop> tag specifies a property node
 146 to hold the gain value and the <value> tag specifies an initial default value.
 147 The gain defaults to 1.0 if unspecified.
 148
 149 The output from the gain filter type is: input * gain.
 150 The output from the reciprocal filter type is: gain / input.
 151
 152 The gain can be changed during run-time by updating the value in the property
 153 node.