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.  Defaults to enabled if unspecified.
 114
 115 <type> The type of filter. This can be exponential, double-exponential,
 116 moving-average, noise-spike, gain or reciprocal.
 117
 118 <input> The input property to be filtered. This should of course be a
 119 numerical property, filtering a text string or a boolean value does not make
 120 sense.
 121
 122 <output> The filtered value. You can make up any new property.
 123
 124 <u_min> The minimum output value from the filter.  Defaults to -infinity.
 125
 126 <u_max> The maximum output value from the filter.  Defaults to +infinity.
 127
 128 These are the tags that are applicable to all filter types. The following tags
 129 are filter specific.
 130
 131 <filter-time> This tag is only applicable for the exponential and
 132 double-exponential filter types. It controls the bandwidth of the filter. The
 133 bandwidth in Hz of the filter is: 1/filter-time. So a low-pass filter with a
 134 bandwidth of 10Hz would have a filter time of 1/10 = 0.1
 135
 136 <samples> This tag only makes sense for the moving-average filter. It says how
 137 many past samples to average.
 138
 139 <max-rate-of-change> This tag is applicable for the noise-spike filter. Is
 140 says how much the value is allowed to change per second.
 141
 142 <gain>  This, and it's enclosed <prop> and <value> tags, are only applicable to
 143 the gain and reciprocal filter types.  The <prop> tag specifies a property node
 144 to hold the gain value and the <value> tag specifies an initial default value.
 145 The gain defaults to 1.0 if unspecified.
 146
 147 The output from the gain filter type is: input * gain.
 148 The output from the reciprocal filter type is: gain / input.
 149
 150 The gain can be changed during run-time by updating the value in the property
 151 node.