edu.wpi.first.wpilibj

Class PIDController

java.lang.Object

edu.wpi.first.wpilibj.PIDController

All Implemented Interfaces:

LiveWindowSendable, PIDInterface, Sendable

public class PIDController
extends java.lang.Object
implements PIDInterface, LiveWindowSendable

Class implements a PID Control Loop.

Creates a separate thread which reads the given PIDSource and takes care of the integral calculations, as well as writing the given PIDOutput.

This feedback controller runs in discrete time, so time deltas are not used in the integral and derivative calculations. Therefore, the sample rate affects the controller's behavior for a given set of PID constants.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PIDController.AbsoluteTolerance
class	PIDController.NullTolerance Used internally for when Tolerance hasn't been set.
class	PIDController.PercentageTolerance
static interface	PIDController.Tolerance Tolerance is the type of tolerance used to specify if the PID controller is on target.

Field Summary

Fields

Modifier and Type	Field and Description
static double	kDefaultPeriod
protected PIDSource	m_pidInput
protected PIDOutput	m_pidOutput

Constructor Summary

Constructors

Constructor and Description
PIDController(double Kp, double Ki, double Kd, double Kf, PIDSource source, PIDOutput output) Allocate a PID object with the given constants for P, I, D, using a 50ms period.
PIDController(double Kp, double Ki, double Kd, double Kf, PIDSource source, PIDOutput output, double period) Allocate a PID object with the given constants for P, I, D, and F
PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output) Allocate a PID object with the given constants for P, I, D, using a 50ms period.
PIDController(double Kp, double Ki, double Kd, PIDSource source, PIDOutput output, double period) Allocate a PID object with the given constants for P, I, D and period

Method Summary

Modifier and Type	Method and Description
protected void	calculate() Read the input, calculate the output accordingly, and write to the output.
protected double	calculateFeedForward() Calculate the feed forward term.
void	disable() Stop running the PIDController, this sets the output to zero before stopping.
void	enable() Begin running the PIDController.
void	free() Free the PID object.
double	get() Return the current PID result This is always centered on zero and constrained the the max and min outs.
double	getAvgError() Returns the current difference of the error over the past few iterations.
protected double	getContinuousError(double error) Wraps error around for continuous inputs.
double	getD() Get the Differential coefficient.
double	getDeltaSetpoint() Returns the change in setpoint over time of the PIDController.
double	getError() Returns the current difference of the input from the setpoint.
double	getF() Get the Feed forward coefficient.
double	getI() Get the Integral coefficient.
double	getP() Get the Proportional coefficient.
double	getSetpoint() Returns the current setpoint of the PIDController.
java.lang.String	getSmartDashboardType() The string representation of the named data type that will be used by the smart dashboard for this Sendable.
ITable	getTable() The table that is associated with this Sendable.
void	initTable(ITable table) Initializes a table for this Sendable object.
boolean	isEnable() Deprecated. Call isEnabled() instead.
boolean	isEnabled() Return true if PIDController is enabled.
boolean	onTarget() Return true if the error is within the percentage of the total input range, determined by setTolerance.
void	reset() Reset the previous error,, the integral term, and disable the controller.
void	setAbsoluteTolerance(double absvalue) Set the absolute error which is considered tolerable for use with OnTarget.
void	setContinuous() Set the PID controller to consider the input to be continuous, Rather then using the max and min in as constraints, it considers them to be the same point and automatically calculates the shortest route to the setpoint.
void	setContinuous(boolean continuous) Set the PID controller to consider the input to be continuous, Rather then using the max and min in as constraints, it considers them to be the same point and automatically calculates the shortest route to the setpoint.
void	setInputRange(double minimumInput, double maximumInput) Sets the maximum and minimum values expected from the input and setpoint.
void	setOutputRange(double minimumOutput, double maximumOutput) Sets the minimum and maximum values to write.
void	setPercentTolerance(double percentage) Set the percentage error which is considered tolerable for use with OnTarget.
void	setPID(double p, double i, double d) Set the PID Controller gain parameters.
void	setPID(double p, double i, double d, double f) Set the PID Controller gain parameters.
void	setSetpoint(double setpoint) Set the setpoint for the PIDController Clears the queue for GetAvgError().
void	setTolerance(double percent) Deprecated. Use setPercentTolerance(double) or setAbsoluteTolerance(double) instead.
void	setTolerance(PIDController.Tolerance tolerance) Set the PID tolerance using a Tolerance object.
void	setToleranceBuffer(int bufLength) Set the number of previous error samples to average for tolerancing.
void	startLiveWindowMode() Start having this sendable object automatically respond to value changes reflect the value on the table.
void	stopLiveWindowMode() Stop having this sendable object automatically respond to value changes.
void	updateTable() Update the table for this sendable object with the latest values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

kDefaultPeriod

public static final double kDefaultPeriod

See Also:

Constant Field Values

m_pidInput

protected PIDSource m_pidInput

m_pidOutput

protected PIDOutput m_pidOutput

Constructor Detail

PIDController

public PIDController(double Kp,
                     double Ki,
                     double Kd,
                     double Kf,
                     PIDSource source,
                     PIDOutput output,
                     double period)

Allocate a PID object with the given constants for P, I, D, and F

Parameters:

Kp - the proportional coefficient

Ki - the integral coefficient

Kd - the derivative coefficient

Kf - the feed forward term

source - The PIDSource object that is used to get values

output - The PIDOutput object that is set to the output percentage

period - the loop time for doing calculations. This particularly effects calculations of the integral and differential terms. The default is 50ms.

PIDController

public PIDController(double Kp,
                     double Ki,
                     double Kd,
                     PIDSource source,
                     PIDOutput output,
                     double period)

Allocate a PID object with the given constants for P, I, D and period

Parameters:

Kp - the proportional coefficient

Ki - the integral coefficient

Kd - the derivative coefficient

source - the PIDSource object that is used to get values

output - the PIDOutput object that is set to the output percentage

period - the loop time for doing calculations. This particularly effects calculations of the integral and differential terms. The default is 50ms.

PIDController

public PIDController(double Kp,
                     double Ki,
                     double Kd,
                     PIDSource source,
                     PIDOutput output)

Allocate a PID object with the given constants for P, I, D, using a 50ms period.

Parameters:

Kp - the proportional coefficient

Ki - the integral coefficient

Kd - the derivative coefficient

source - The PIDSource object that is used to get values

output - The PIDOutput object that is set to the output percentage

PIDController

public PIDController(double Kp,
                     double Ki,
                     double Kd,
                     double Kf,
                     PIDSource source,
                     PIDOutput output)

Allocate a PID object with the given constants for P, I, D, using a 50ms period.

Parameters:

Kp - the proportional coefficient

Ki - the integral coefficient

Kd - the derivative coefficient

Kf - the feed forward term

source - The PIDSource object that is used to get values

output - The PIDOutput object that is set to the output percentage

Method Detail

free

public void free()

Free the PID object.

calculate

protected void calculate()

Read the input, calculate the output accordingly, and write to the output. This should only be called by the PIDTask and is created during initialization.

calculateFeedForward

protected double calculateFeedForward()

Calculate the feed forward term.

Both of the provided feed forward calculations are velocity feed forwards. If a different feed forward calculation is desired, the user can override this function and provide his or her own. This function does no synchronization because the PIDController class only calls it in synchronized code, so be careful if calling it oneself.

If a velocity PID controller is being used, the F term should be set to 1 over the maximum setpoint for the output. If a position PID controller is being used, the F term should be set to 1 over the maximum speed for the output measured in setpoint units per this controller's update period (see the default period in this class's constructor).

setPID

public void setPID(double p,
                   double i,
                   double d)

Set the PID Controller gain parameters. Set the proportional, integral, and differential coefficients.

Specified by:

setPID in interface PIDInterface

Parameters:

p - Proportional coefficient

i - Integral coefficient

d - Differential coefficient

setPID

public void setPID(double p,
                   double i,
                   double d,
                   double f)

Set the PID Controller gain parameters. Set the proportional, integral, and differential coefficients.

Parameters:

p - Proportional coefficient

i - Integral coefficient

d - Differential coefficient

f - Feed forward coefficient

getP

public double getP()

Get the Proportional coefficient.

Specified by:

getP in interface PIDInterface

Returns:

proportional coefficient

getI

public double getI()

Get the Integral coefficient.

Specified by:

getI in interface PIDInterface

Returns:

integral coefficient

getD

public double getD()

Get the Differential coefficient.

Specified by:

getD in interface PIDInterface

Returns:

differential coefficient

getF

public double getF()

Get the Feed forward coefficient.

Returns:

feed forward coefficient

get

public double get()

Return the current PID result This is always centered on zero and constrained the the max and min outs.

Returns:

the latest calculated output

setContinuous

public void setContinuous(boolean continuous)

Set the PID controller to consider the input to be continuous, Rather then using the max and min in as constraints, it considers them to be the same point and automatically calculates the shortest route to the setpoint.

Parameters:

continuous - Set to true turns on continuous, false turns off continuous

setContinuous

public void setContinuous()

Set the PID controller to consider the input to be continuous, Rather then using the max and min in as constraints, it considers them to be the same point and automatically calculates the shortest route to the setpoint.

setInputRange

public void setInputRange(double minimumInput,
                          double maximumInput)

Sets the maximum and minimum values expected from the input and setpoint.

Parameters:

minimumInput - the minimum value expected from the input

maximumInput - the maximum value expected from the input

setOutputRange

public void setOutputRange(double minimumOutput,
                           double maximumOutput)

Sets the minimum and maximum values to write.

Parameters:

minimumOutput - the minimum percentage to write to the output

maximumOutput - the maximum percentage to write to the output

setSetpoint

public void setSetpoint(double setpoint)

Set the setpoint for the PIDController Clears the queue for GetAvgError().

Specified by:

setSetpoint in interface PIDInterface

Parameters:

setpoint - the desired setpoint

getSetpoint

public double getSetpoint()

Returns the current setpoint of the PIDController.

Specified by:

getSetpoint in interface PIDInterface

Returns:

the current setpoint

getDeltaSetpoint

public double getDeltaSetpoint()

Returns the change in setpoint over time of the PIDController.

Returns:

the change in setpoint over time

getError

public double getError()

Returns the current difference of the input from the setpoint.

Specified by:

getError in interface PIDInterface

Returns:

the current error

getAvgError

public double getAvgError()

Returns the current difference of the error over the past few iterations. You can specify the number of iterations to average with setToleranceBuffer() (defaults to 1). getAvgError() is used for the onTarget() function.

Returns:

the current average of the error

setTolerance

@Deprecated
public void setTolerance(double percent)

Deprecated. Use setPercentTolerance(double) or setAbsoluteTolerance(double) instead.

Set the percentage error which is considered tolerable for use with OnTarget. (Input of 15.0 = 15 percent).

Parameters:

percent - error which is tolerable

setTolerance

public void setTolerance(PIDController.Tolerance tolerance)

Set the PID tolerance using a Tolerance object. Tolerance can be specified as a percentage of the range or as an absolute value. The Tolerance object encapsulates those options in an object. Use it by creating the type of tolerance that you want to use: setTolerance(new PIDController.AbsoluteTolerance(0.1))

Parameters:

tolerance - a tolerance object of the right type, e.g. PercentTolerance or AbsoluteTolerance

setAbsoluteTolerance

public void setAbsoluteTolerance(double absvalue)

Set the absolute error which is considered tolerable for use with OnTarget.

Parameters:

absvalue - absolute error which is tolerable in the units of the input object

setPercentTolerance

public void setPercentTolerance(double percentage)

Set the percentage error which is considered tolerable for use with OnTarget. (Input of 15.0 = 15 percent)

Parameters:

percentage - percent error which is tolerable

setToleranceBuffer

public void setToleranceBuffer(int bufLength)

Set the number of previous error samples to average for tolerancing. When determining whether a mechanism is on target, the user may want to use a rolling average of previous measurements instead of a precise position or velocity. This is useful for noisy sensors which return a few erroneous measurements when the mechanism is on target. However, the mechanism will not register as on target for at least the specified bufLength cycles.

Parameters:

bufLength - Number of previous cycles to average.

onTarget

public boolean onTarget()

Return true if the error is within the percentage of the total input range, determined by setTolerance. This assumes that the maximum and minimum input were set using setInput.

Returns:

true if the error is less than the tolerance

enable

public void enable()

Begin running the PIDController.

Specified by:

enable in interface PIDInterface

disable

public void disable()

Stop running the PIDController, this sets the output to zero before stopping.

Specified by:

disable in interface PIDInterface

isEnable

@Deprecated
public boolean isEnable()

Deprecated. Call isEnabled() instead.

Return true if PIDController is enabled.

isEnabled

public boolean isEnabled()

Return true if PIDController is enabled.

Specified by:

isEnabled in interface PIDInterface

reset

public void reset()

Reset the previous error,, the integral term, and disable the controller.

Specified by:

reset in interface PIDInterface

getSmartDashboardType

public java.lang.String getSmartDashboardType()

Description copied from interface: Sendable

The string representation of the named data type that will be used by the smart dashboard for this Sendable.

Specified by:

getSmartDashboardType in interface Sendable

Returns:

The type of this Sendable.

initTable

public void initTable(ITable table)

Description copied from interface: Sendable

Initializes a table for this Sendable object.

Specified by:

initTable in interface Sendable

Parameters:

table - The table to put the values in.

getContinuousError

protected double getContinuousError(double error)

Wraps error around for continuous inputs. The original error is returned if continuous mode is disabled. This is an unsynchronized function.

Parameters:

error - The current error of the PID controller.

Returns:

Error for continuous inputs.

getTable

public ITable getTable()

Description copied from interface: Sendable

The table that is associated with this Sendable.

Specified by:

getTable in interface Sendable

Returns:

the table that is currently associated with the Sendable.

updateTable

public void updateTable()

Description copied from interface: LiveWindowSendable

Update the table for this sendable object with the latest values.

Specified by:

updateTable in interface LiveWindowSendable

startLiveWindowMode

public void startLiveWindowMode()

Description copied from interface: LiveWindowSendable

Start having this sendable object automatically respond to value changes reflect the value on the table.

Specified by:

startLiveWindowMode in interface LiveWindowSendable

stopLiveWindowMode

public void stopLiveWindowMode()

Description copied from interface: LiveWindowSendable

Stop having this sendable object automatically respond to value changes.

Specified by:

stopLiveWindowMode in interface LiveWindowSendable