Package com.crossbotics.ftchelper.control

Class PidController

java.lang.Object
com.crossbotics.ftchelper.control.PidController
public class PidController extends Object
A PID controller: it works out how much power to give so a value reaches a target.

PID stands for Proportional, Integral, Derivative:

  • P pushes harder when you are far from the target.
  • I adds up small errors that last a long time (for example gravity on a lift).
  • D slows the push when you move toward the target fast, so you do not overshoot.
  • F (feedforward) is a fixed extra push, for example to hold an arm up.

The "error" is how far you still have to go: target minus where you are now. The "gains" (kP, kI, kD, kF) are the numbers you tune: how strongly each part pushes. 


 PidController liftPid = new PidController(0.005, 0, 0.0002)
         .setOutputLimits(-0.6, 1.0)
         .setTolerance(15);
 // every loop:
 double power = liftPid.calculate(targetTicks, lift.getCurrentPosition());
 lift.setPower(power);
 if (liftPid.atTarget()) { ... }
Tuning steps are in docs/modules/control.md. Tutorial 07 (docs/tutorials/07-pid-lift.md) explains PID step by step on a lift.

  • Constructor Details

    • PidController

      public PidController(double kP, double kI, double kD)
      Makes a controller with no feedforward.
      Parameters:
      kP - proportional gain (start small, e.g. 0.01)
      kI - integral gain (start at 0)
      kD - derivative gain (start at 0)

    • PidController

      public PidController(double kP, double kI, double kD, double kF)
      Makes a controller with a fixed feedforward push.
      Parameters:
      kP - proportional gain
      kI - integral gain
      kD - derivative gain
      kF - power added every time (same sign always), e.g. 0.1 to hold up a lift

    • PidController

      public PidController(double kP, double kI, double kD, double kF, LongSupplier clockNanos)
      Makes a controller with your own clock. Used by tests.
      Parameters:
      clockNanos - gives the current time in nanoseconds

  • Method Details

    • setGains

      public PidController setGains(double kP, double kI, double kD, double kF)
      Changes the gains (for live tuning). Does not reset the controller.
      Returns:
      this controller, so you can chain more settings

    • setOutputLimits

      public PidController setOutputLimits(double min, double max)
      Limits the output. Default -1 to 1 (motor power range). Example: setOutputLimits(-0.5, 1) lets a lift go down at half power only.
      Parameters:
      min - the lowest output (power), e.g. -1
      max - the highest output (power), e.g. 1
      Returns:
      this controller, so you can chain more settings

    • setIntegralLimit

      public PidController setIntegralLimit(double maxIntegralOutput)
      Limits how big the I part can grow. Stops "integral windup": a big build-up that makes the mechanism overshoot after it was stuck. Default: no limit.
      Parameters:
      maxIntegralOutput - the largest power the I part can add, e.g. 0.3
      Returns:
      this controller, so you can chain more settings

    • setTolerance

      public PidController setTolerance(double tolerance)
      How close counts as "at target" for atTarget(). Same units as your measurement.
      Parameters:
      tolerance - for example 15 (encoder ticks) or 2 (degrees)
      Returns:
      this controller, so you can chain more settings

    • setAngleMode

      public PidController setAngleMode(boolean degrees)
      Turn on for headings in degrees. The error then takes the short way around the circle (from 170 to -170 is +20, not -340).
      Parameters:
      degrees - true for headings in degrees, false for normal values (the default)
      Returns:
      this controller, so you can chain more settings

    • calculate

      public double calculate(double target, double measured)
      Works out the output. Call once per loop.
      Parameters:
      target - where you want to be
      measured - where you are now
      Returns:
      the power to apply, inside the output limits

    • getLastError

      public double getLastError()
      The error from the last calculate(double, double) call (target minus measured). NaN before the first call.

    • atTarget

      public boolean atTarget()
      True if the last error was within the tolerance. False before the first call.

    • reset

      public void reset()
      Clears the memory (I and D). Call when you set a new target or start the mechanism again. Without this, the I total built up for the old target would push the mechanism the wrong way.

    • getKP

      public double getKP()
      The P gain now in use.

    • getKI

      public double getKI()
      The I gain now in use.

    • getKD

      public double getKD()
      The D gain now in use.

    • getKF

      public double getKF()
      The feedforward (F) now in use.