2 ==============================================================================
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
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.
17 The complete XML syntax for a InputValue is
21 <!-- any condition as defined in README.conditions -->
23 <property>/some/property/name</property>
31 The enclosing element <some-element> is the element defined in each filter, like <input>, <u_min>,
32 <reference> etc. These elements will be described later.
33 The value of the input is calculated based on the given value, scale and offset as
34 value * scale + offset
35 and the result is clipped to min/max, if given.
36 With the full set of given elements, the InputValue will initialize the named property to the value
37 given, reduced by the given offset and reverse scaled by the given scale.
41 <property>/controls/flight/rudder</property>
47 Will use the property /controls/flight/rudder as the input of the filter. The property will be initialized
48 at a value of zero and since the property usually is in the range [-1..+1], the the value of <input> will
49 be in the range (-1)*0.5+0.5 to (+1)*0.5+0.5 which is [0..1].
51 The default values for elements not given are:
61 <property>/position/altitude-ft</property>
64 Gives the altitude in meters. No initialization of the property is performed, no offset applied.
69 A constant reference of zero.
71 A abbreviated method of defining values exist for using a just constant or a property. The above
72 example may be written as
73 <reference>0.0</reference>
74 Or if the reference is defined in a property
75 <reference>/some/property/name</reference>
76 No initialization, scaling or offsetting is performed here.
77 The logic behind this is: If the text node in the element (the text between the opening and closing tag)
78 can be converted to a double value, it will be interpreted as a double value. Otherwise the text will
79 be interpreted as a property name.
81 <reference>3.1415927</reference> - The constant of PI (roughly)
82 <reference>/position/altitude-ft</reference> - The property /position/altitude-ft
83 <reference>3kings</reference> - The constant 3. The word kings is ignored
84 <reference>food4less</reference> - The property food4less
86 The <property> element may also be written as <prop> for backward compatibility.
88 There may be one or more InputValues for the same input of a filter which may be bound to conditions.
89 Each InputValue will have its condition checked in the order of InputValues given in the configuration
90 file. The first InputValue that returns true for its condition will be evaluated. Chaining a number
91 of InputValues with conditions and an unconditioned InputValue works like the C language equivalent
93 // compute value of first element
94 } else if( condition2 ) {
95 // compute value of second element
96 } else if( condition3 ) {
97 // compute value of third element
99 // compute value of last element
102 Example: Set the gain to 3.0 if /autopilot/locks/heading equals dg-heading-hold or 2.0 otherwise.
107 <property>/autopilot/locks/heading</property>
108 <value>dg-heading-hold</value>
113 <!-- Hint: omit a condition here as a fallthru else condition -->
120 ==============================================================================
121 Each filter drives one to many output properties. No scaling of offsetting is implemented
122 for the output value, these should be done in the filter itself.
123 The output properties are defined in the <output/> element by adding <property/> elements
124 within the <output/> element. For just a single output property, the <property/> element
125 may be ommited. For backward compatibility, <property/> may be replaced by <prop/>.
126 Nonexisting properties will be created with type double.
128 Example: (Multiple output properties)
130 <property>/some/output/property</property>
131 <property>/some/other/output/property</property>
132 <property>/and/another/output/property</property>
135 Example: a single output property
136 <output>/just/a/single/property</output>
138 Other Common Settings
139 ==============================================================================
140 <name> String The name of the filter. Used for debug purpose.
142 <name>pressure rate filter</name>
144 <debug> Boolean If true, this filter puts out debug information when updated.
148 <input> InputValue The input property driving the filter.
149 Refer to InputValue for details.
151 <reference> InputValue The reference property for filter that need one.
152 Refer to InputValue for details.
154 <output> Complex Each filter can drive one to many output properties.
155 Refer to OutputValue for details.
157 <u_min> InputValue This defines the optional minimum and maximum value the output
158 <u_max> is clamped to. If neither <u_min> nor <u_max> exists, the output
159 is only limited by the internal limit of double precision float computation.
160 If either <u_min> or <u_max> is given, clamping is activated. A missing
161 min or max value defaults to 0 (zero).
162 Note: <u_min> and <u_max> may also occour within a <config> element.
163 <min> and <max> may be used as a substitude for the corresponding u_xxx element.
165 Example: Limit the pilot's body temperature to a constant minimum of 36 and a maximum defined in
166 /pilots/max-body-temperature-degc, initialized to 40.0
168 <prop>/pilots/max-body-temperature-degc</prop>
175 Implicit definition of the minimum value of 0 (zero) and defining a maximum of 100.0
180 <enable> Complex Define a condition to enable or disable the filter. For disabled
181 filters, no output computations are performed. Only enabled
182 filters fill the output properties. The default for undefined
183 conditions is enabled.
184 Several way exist to define a condition. The most simple case
185 is checking a boolean property. For this, just a <prop> element
186 naming this boolean property is needed. The boolean value of the
187 named property defines the enabled state of the filter.
188 To compare the value of a property with a constant, a <prop> and
189 a <value> element define the property name and the value to be
190 compared. The filter is enabled, if the value of the property
191 equals the given value. A case sensitive string compare is
193 To define more complex conditions, a <condition> element may be
194 used to define any condition described in README.conditions.
195 If a <condition> element is present and if it contains a valid
196 condition, this conditions has precedence over a given <prop>/
198 The child element <honor-passive>, a boolean flag, may be present
199 within the <enable> element. If this element is true, the property
200 /autopilot/locks/passive-mode is checked and if it is true, the
201 filter output is computed, but the output properties are not set.
202 The default for honor-passive is false
203 Example: Check a boolean property, only compute this filter if gear-down is true and
204 /autopilot/locks/passive-mode is false
206 <prop>/gear/gear-down</prop>
207 <honor-passive>true</honor-passive>
210 Check a property for equality, only compute this filter if the autopilot is locked in heading mode.
212 <prop>/autopilot/locks/heading</prop>
213 <value>dg-heading-hold</value>
216 Use a complex condition, only compute this filter if the autopilot is serviceable and the lock
217 is either dg-heading-hold or nav1-heading-hold
220 <property>/autopilo/serviceable</property>
223 <property>/autopilot/locks/heading</property>
224 <value>dg-heading-hold</value>
227 <property>/autopilot/locks/heading</property>
228 <value>nav1-heading-hold</value>
234 INDIVIDUAL FILTER CONFIGURATION
235 ==============================================================================
239 Six different types of digital filter can be configured inside the autopilot
240 configuration file. There are four low-pass filter types and two gain filter
243 The low-pass filter types are:
250 The gain filter types are:
255 To add a digital filter, place a <filter> element under the root element. Next to
256 the global configuration elements described above, the following elements configure
258 <filter-time> InputValue This tag is only applicable for the exponential and
259 double-exponential filter types. It controls the bandwidth
260 of the filter. The bandwidth in Hz of the filter is:
261 1/filter-time. So a low-pass filter with a bandwidth of
262 10Hz would have a filter time of 1/10 = 0.1
264 <samples> InputValue This tag only makes sense for the moving-average filter.
265 It says how many past samples to average.
268 InputValue This tag is applicable for the noise-spike filter.
269 It says how much the value is allowed to change per second.
271 <gain> InputValue This is only applicable to the gain and reciprocal filter types.
272 The output for gain filter is computed as input*gain while
273 the reciprocal filter computes output as gain/input for input
274 values != 0 (zero). Gain may be a constant, a property name
275 defined by a <prop> element within the <gain> element or a
276 property name initialized to a value by using a <prop> and
279 Example: a pressure-rate-filter implemented as a double exponential low pass filter
280 with a bandwith of 10Hz
283 <name>pressure-rate-filter</name>
285 <type>double-exponential</type>
287 <prop>/autopilot/locks/pressure-rate-filter</prop>
290 <input>/autopilot/internal/pressure-rate</input>
291 <output>/autopilot/internal/filtered-pressure-rate</output>
292 <filter-time>0.1</filter-time>
295 This will filter the pressure-rate property. The output will be to a new
296 property called filtered-pressure-rate. You can select any numerical property
297 from the property tree. The input property will not be affected by the filter,
298 it will stay the same as it would if no filter was configured.
303 <name>airspeed elevator-trim gain reciprocal filter</name>
306 <prop>/autopilot/locks/airspeed-elevator-trim-gain</prop>
309 <type>reciprocal</type>
311 <prop>/autopilot/settings/elevator-trim-airspeed-reciprocal-gain</prop>
314 <input>/velocities/airspeed-kt</input>
315 <output>/autopilot/internal/elevator-trim-gain</output>
320 This will use the /velocities/airspeed-kt property to produce a gain factor
321 that reduces as airspeed increases. At airspeeds up to 350kt the gain will
322 be clamped to 0.02, at 700kt the gain will be 0.01 and at 1400kt the gain will
323 be 0.005. The gain will be clamped to 0.005 for airspeeds > 1400kt.
325 The output from this filter could then be used to control the gain in a PID
329 <name>Pitch hold</name>
332 <prop>/autopilot/locks/pitch</prop>
336 <prop>/orientation/pitch-deg</prop>
339 <prop>/autopilot/settings/target-pitch-deg</prop>
342 <prop>/autopilot/internal/target-elevator-trim-norm</prop>
347 <prop>/autopilot/internal/elevator-trim-gain</prop>
360 IMPORTANT NOTE: The <Kp> tag in PID controllers has been revised to operate in
361 the same way as the <gain> elements in filters. However, the original format
362 of <Kp> will continue to function as before i.e. <Kp>0.02</Kp> will specify a
363 fixed and unalterable gain factor, but a warning message will be output.
365 The gain type filter is similar to the reciprocal filter except that the gain
366 is applied as a simple factor to the input.
367 -------------------------------------------------------------------------------
370 <name> The name of the filter. Give it a sensible name!
372 <debug> If this tag is set to true debugging info will be printed on the
375 <enable> Encloses the <prop> and <value> tags which are used to enable or
376 disable the filter. Instead of the <prop> and <value> tags, a <condition>
377 tag may be used to define a condition. Check README.conditions for more
378 details about conditions. Defaults to enabled if unspecified.
380 <type> The type of filter. This can be exponential, double-exponential,
381 moving-average, noise-spike, gain or reciprocal.
383 <input> The input property to be filtered. This should of course be a
384 numerical property, filtering a text string or a boolean value does not make
387 <output> The filtered value. You can make up any new property.
389 <u_min> The minimum output value from the filter. Defaults to -infinity.
391 <u_max> The maximum output value from the filter. Defaults to +infinity.
393 These are the tags that are applicable to all filter types. The following tags
396 <filter-time> This tag is only applicable for the exponential and
397 double-exponential filter types. It controls the bandwidth of the filter. The
398 bandwidth in Hz of the filter is: 1/filter-time. So a low-pass filter with a
399 bandwidth of 10Hz would have a filter time of 1/10 = 0.1
401 <samples> This tag only makes sense for the moving-average filter. It says how
402 many past samples to average.
404 <max-rate-of-change> This tag is applicable for the noise-spike filter. Is
405 says how much the value is allowed to change per second.
407 <gain> This, and it's enclosed <prop> and <value> tags, are only applicable to
408 the gain and reciprocal filter types. The <prop> tag specifies a property node
409 to hold the gain value and the <value> tag specifies an initial default value.
410 The gain defaults to 1.0 if unspecified.
412 The output from the gain filter type is: input * gain.
413 The output from the reciprocal filter type is: gain / input.
415 The gain can be changed during run-time by updating the value in the property