WPILibC++  2019.3.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
frc::LinearDigitalFilter Class Reference

This class implements a linear, digital filter. More...

#include <LinearDigitalFilter.h>

Inheritance diagram for frc::LinearDigitalFilter:
frc::Filter frc::PIDSource

Public Member Functions

 LinearDigitalFilter (PIDSource &source, wpi::ArrayRef< double > ffGains, wpi::ArrayRef< double > fbGains)
 Create a linear FIR or IIR filter. More...
 
 LinearDigitalFilter (std::shared_ptr< PIDSource > source, wpi::ArrayRef< double > ffGains, wpi::ArrayRef< double > fbGains)
 Create a linear FIR or IIR filter. More...
 
 LinearDigitalFilter (LinearDigitalFilter &&)=default
 
LinearDigitalFilteroperator= (LinearDigitalFilter &&)=default
 
double Get () const override
 Returns the current filter estimate without also inserting new data as PIDGet() would do. More...
 
void Reset () override
 Reset the filter state.
 
double PIDGet () override
 Calculates the next value of the filter. More...
 
- Public Member Functions inherited from frc::Filter
 Filter (PIDSource &source)
 
 Filter (std::shared_ptr< PIDSource > source)
 
 Filter (Filter &&)=default
 
Filteroperator= (Filter &&)=default
 
void SetPIDSourceType (PIDSourceType pidSource) override
 Set which parameter you are using as a process control variable. More...
 
PIDSourceType GetPIDSourceType () const override
 

Static Public Member Functions

static LinearDigitalFilter SinglePoleIIR (PIDSource &source, double timeConstant, double 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 LinearDigitalFilter HighPass (PIDSource &source, double timeConstant, double 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 LinearDigitalFilter MovingAverage (PIDSource &source, 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...
 
static LinearDigitalFilter SinglePoleIIR (std::shared_ptr< PIDSource > source, double timeConstant, double 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 LinearDigitalFilter HighPass (std::shared_ptr< PIDSource > source, double timeConstant, double 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 LinearDigitalFilter MovingAverage (std::shared_ptr< PIDSource > source, 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...
 

Additional Inherited Members

- Protected Member Functions inherited from frc::Filter
double PIDGetSource ()
 Calls PIDGet() of source. More...
 
- Protected Attributes inherited from frc::PIDSource
PIDSourceType m_pidSource = PIDSourceType::kDisplacement
 

Detailed Description

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:

  • Getting rid of noise from an analog sensor input (note: the roboRIO's FPGA can do this faster in hardware)
  • Smoothing out joystick input to prevent the wheels from slipping or the robot from tipping
  • Smoothing motor commands so that unnecessary strain isn't put on electrical or mechanical components
  • If you use clever gains, you can make a PID controller out of this class!

For more on filters, I highly recommend the following articles:
http://en.wikipedia.org/wiki/Linear_filter
http://en.wikipedia.org/wiki/Iir_filter
http://en.wikipedia.org/wiki/Fir_filter

Note 1: PIDGet() should be called by the user on a known, regular period. You can set up a Notifier to do this (look at the WPILib PIDController class), 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 PIDGet() gets called at the desired, constant frequency!

Constructor & Destructor Documentation

frc::LinearDigitalFilter::LinearDigitalFilter ( PIDSource source,
wpi::ArrayRef< double >  ffGains,
wpi::ArrayRef< double >  fbGains 
)

Create a linear FIR or IIR filter.

Parameters
sourceThe PIDSource object that is used to get values
ffGainsThe "feed forward" or FIR gains
fbGainsThe "feed back" or IIR gains
frc::LinearDigitalFilter::LinearDigitalFilter ( std::shared_ptr< PIDSource source,
wpi::ArrayRef< double >  ffGains,
wpi::ArrayRef< double >  fbGains 
)

Create a linear FIR or IIR filter.

Parameters
sourceThe PIDSource object that is used to get values
ffGainsThe "feed forward" or FIR gains
fbGainsThe "feed back" or IIR gains

Member Function Documentation

double frc::LinearDigitalFilter::Get ( ) const
overridevirtual

Returns the current filter estimate without also inserting new data as PIDGet() would do.

Returns
The current filter estimate

Implements frc::Filter.

static LinearDigitalFilter frc::LinearDigitalFilter::HighPass ( PIDSource source,
double  timeConstant,
double  period 
)
static

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.

Parameters
sourceThe PIDSource object that is used to get values
timeConstantThe discrete-time time constant in seconds
periodThe period in seconds between samples taken by the user
static LinearDigitalFilter frc::LinearDigitalFilter::HighPass ( std::shared_ptr< PIDSource source,
double  timeConstant,
double  period 
)
static

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.

Parameters
sourceThe PIDSource object that is used to get values
timeConstantThe discrete-time time constant in seconds
periodThe period in seconds between samples taken by the user
static LinearDigitalFilter frc::LinearDigitalFilter::MovingAverage ( PIDSource source,
int  taps 
)
static

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.

Parameters
sourceThe PIDSource object that is used to get values
tapsThe number of samples to average over. Higher = smoother but slower
static LinearDigitalFilter frc::LinearDigitalFilter::MovingAverage ( std::shared_ptr< PIDSource source,
int  taps 
)
static

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.

Parameters
sourceThe PIDSource object that is used to get values
tapsThe number of samples to average over. Higher = smoother but slower
double frc::LinearDigitalFilter::PIDGet ( )
overridevirtual

Calculates the next value of the filter.

Returns
The filtered value at this step

Implements frc::Filter.

static LinearDigitalFilter frc::LinearDigitalFilter::SinglePoleIIR ( PIDSource source,
double  timeConstant,
double  period 
)
static

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.

Parameters
sourceThe PIDSource object that is used to get values
timeConstantThe discrete-time time constant in seconds
periodThe period in seconds between samples taken by the user
static LinearDigitalFilter frc::LinearDigitalFilter::SinglePoleIIR ( std::shared_ptr< PIDSource source,
double  timeConstant,
double  period 
)
static

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.

Parameters
sourceThe PIDSource object that is used to get values
timeConstantThe discrete-time time constant in seconds
periodThe period in seconds between samples taken by the user

The documentation for this class was generated from the following file: