WPILibC++
2021.2.2
|
This class implements a linear, digital filter. More...
#include <LinearFilter.h>
Public Member Functions | |
LinearFilter (wpi::ArrayRef< double > ffGains, wpi::ArrayRef< double > fbGains) | |
Create a linear FIR or IIR filter. More... | |
LinearFilter (std::initializer_list< double > ffGains, std::initializer_list< double > fbGains) | |
Create a linear FIR or IIR filter. More... | |
void | Reset () |
Reset the filter state. | |
T | Calculate (T input) |
Calculates the next value of the filter. More... | |
Static Public Member Functions | |
static LinearFilter< T > | SinglePoleIIR (double timeConstant, units::second_t period) |
Creates a one-pole IIR low-pass filter of the form: y[n] = (1 - gain) * x[n] + gain * y[n-1] where gain = e-dt / T, T is the time constant in seconds. More... | |
static LinearFilter< T > | HighPass (double timeConstant, units::second_t period) |
Creates a first-order high-pass filter of the form: y[n] = gain * x[n] + (-gain) * x[n-1] + gain * y[n-1] where gain = e-dt / T, T is the time constant in seconds. More... | |
static LinearFilter< T > | MovingAverage (int taps) |
Creates a K-tap FIR moving average filter of the form: y[n] = 1/k * (x[k] + x[k-1] + … + x[0]) More... | |
This class implements a linear, digital filter.
All types of FIR and IIR filters are supported. Static factory methods are provided to create commonly used types of filters.
Filters are of the form:
y[n] = (b0 * x[n] + b1 * x[n-1] + … + bP * x[n-P]) - (a0 * y[n-1] + a2 * y[n-2] + … + aQ * y[n-Q])
Where:
y[n] is the output at time "n"
x[n] is the input at time "n"
y[n-1] is the output from the LAST time step ("n-1")
x[n-1] is the input from the LAST time step ("n-1")
b0 … bP are the "feedforward" (FIR) gains
a0 … aQ are the "feedback" (IIR) gains
IMPORTANT! Note the "-" sign in front of the feedback term! This is a common convention in signal processing.
What can linear filters do? Basically, they can filter, or diminish, the effects of undesirable input frequencies. High frequencies, or rapid changes, can be indicative of sensor noise or be otherwise undesirable. A "low pass" filter smooths out the signal, reducing the impact of these high frequency components. Likewise, a "high pass" filter gets rid of slow-moving signal components, letting you detect large changes more easily.
Example FRC applications of filters:
For more on filters, we highly recommend the following articles:
https://en.wikipedia.org/wiki/Linear_filter
https://en.wikipedia.org/wiki/Iir_filter
https://en.wikipedia.org/wiki/Fir_filter
Note 1: Calculate() should be called by the user on a known, regular period. You can use a Notifier for this or do it "inline" with code in a periodic function.
Note 2: For ALL filters, gains are necessarily a function of frequency. If you make a filter that works well for you at, say, 100Hz, you will most definitely need to adjust the gains if you then want to run it at 200Hz! Combining this with Note 1 - the impetus is on YOU as a developer to make sure Calculate() gets called at the desired, constant frequency!
|
inline |
Create a linear FIR or IIR filter.
ffGains | The "feed forward" or FIR gains. |
fbGains | The "feed back" or IIR gains. |
|
inline |
Create a linear FIR or IIR filter.
ffGains | The "feed forward" or FIR gains. |
fbGains | The "feed back" or IIR gains. |
|
inline |
Calculates the next value of the filter.
input | Current input value. |
|
inlinestatic |
Creates a first-order high-pass filter of the form:
y[n] = gain * x[n] + (-gain) * x[n-1] + gain * y[n-1]
where gain = e-dt / T, T is the time constant in seconds.
This filter is stable for time constants greater than zero.
timeConstant | The discrete-time time constant in seconds. |
period | The period in seconds between samples taken by the user. |
|
inlinestatic |
Creates a K-tap FIR moving average filter of the form:
y[n] = 1/k * (x[k] + x[k-1] + … + x[0])
This filter is always stable.
taps | The number of samples to average over. Higher = smoother but slower |
|
inlinestatic |
Creates a one-pole IIR low-pass filter of the form:
y[n] = (1 - gain) * x[n] + gain * y[n-1]
where gain = e-dt / T, T is the time constant in seconds.
This filter is stable for time constants greater than zero.
timeConstant | The discrete-time time constant in seconds. |
period | The period in seconds between samples taken by the user. |