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

    All Methods Instance Methods Concrete Methods
    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`.
    `void` | `initTable(NetworkTable table)` Initializes a table for this `Sendable` object.
    `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(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

          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`

    - #### 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(NetworkTable 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.

    - #### 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`