EasyPIDControllerEx
EasyPIDControllerEx
EasyStack Control Guide
A PID controller uses feedback to help a mechanism reach a desired position or velocity. EasyPIDControllerEx compares a measurement with a target and calculates a correction using proportional, integral, and derivative control.
This guide explains how to configure the controller, calculate motor commands, check tolerances, and manage integral accumulation. It describes the supplied version that measures elapsed time automatically.
Creating a PID Controller
Provide the proportional, integral, and derivative coefficients in that order. Create the controller once and reuse it during the control loop so its history is preserved.
EasyPIDControllerEx controller =
new EasyPIDControllerEx(0.005, 0.0, 0.0001);These values are examples and must be tuned for your mechanism. The constructor rejects negative coefficients.
| Parameter | Description |
|---|---|
| kP | Responds to the current error. |
| kI | Responds to accumulated error over time. |
| kD | Responds to the rate of change of error. |
Setting the Target
Use setSetpoint() to select the desired position or velocity. The target and measurement must use the same units, such as encoder ticks for position.
= controller.getSetpoint();Changing the target does not clear the accumulated integral error. Start with proportional control and add integral or derivative control as needed.
Calculating and Applying the Output
Call calculate() once per control-loop iteration with a fresh sensor measurement. The controller returns an output; your application applies it to the actuator.
double position motor.getCurrentPosition();
= controller.calculate(position);You can supply the target in the same call. This overload stores the target and then calculates the output.
double output = controller.calculate(position, 1000.0);| Parameter | Description |
|---|---|
| measurement | Current position or velocity from the sensor. |
| setpoint | Desired position or velocity in matching units. |
Limiting Motor Power
The controller does not clamp the total PID output. Limit the returned command to the range accepted by the actuator before applying it.
double power = Math.max(-1.0, Math.min(output, 1.0));
motor.setPower(power);For a lower power limit, use a smaller range. The following command allows up to 50 percent power in either direction.
= Math.max(-0.5, Math.min(output, 0.5));Automatic Timing
The controller measures the interval between calculations using ElapsedTime. This interval is used by the integral and derivative terms, so no fixed period is required in the constructor.
= controller.getPeriod();The first calculation uses 0.0001 seconds. Subsequent calculations use the measured elapsed time. Continue updating regularly; short intervals and abrupt changes in error can produce large derivative contributions.
Adjusting Gains and Tolerances
Use setPID() to update all three coefficients, or use the individual setters to change one gain at a time.
controller. .006,
controller.setP(0.006);
controller.
controller.Keep the gains nonnegative. Unlike the constructor, these setters do not validate them. Read the configured values with the corresponding getters.
= controller.getP();
= controller.getl();
= controller.getD();Setting the Tolerance
The single-argument overload sets the acceptable error and restores the derivative tolerance to positive infinity. The two-argument overload also sets the acceptable rate of change of error.
controller.setTolerance(10.0);
// Error below 10 ticks and error rate below 20 ticks/s.
controller.setTolerance(10.0, 20.0);Use positive tolerances in units matching your measurement. For position in ticks, the derivative tolerance is in ticks per second. The defaults are 0.05 for error and positive infinity for its derivative.
double errorTolerance = controller.getErrorTolerance();
double rateTolerance
controller.getErrorDerivativeTolerance();Checking the Target
After calculate(), call atSetpoint(). It requires a supplied target and measurement, and both absolute errors must be strictly below their tolerances.
= controller.calculate(position, target);
= controller.atSetpoint();This check reports status only. It does not stop the motor or change the output. Decide whether your mechanism should keep holding the target or finish the movement.
Managing Integral Control
The integral term accumulates error over time. Configure its output contribution and integration zone to prevent persistent error from building an unnecessarily large correction.
Integral Contribution Limits
Use setIntegratorRange() to limit the integral term's contribution to the output. With a positive kI, the following range limits that contribution to between minus 0.2 and plus 0.2.
controller.setIntegratorRange(-@.2, 0.2);The default contribution range is minus 1 to plus 1. These limits do not clamp the complete PID output. Keep the minimum less than or equal to the maximum.
controller.setIntegratorRange(-1.@, 1.0);
= controller.getAccumulatedError();getAccumulatedError() returns the stored error integral before multiplication by kI.
Integration Zone
Use setIZone() to allow integration only when the measurement is sufficiently close to the target. The zone uses the same units as the controlled measurement.
If the absolute error exceeds 100 units, accumulated error is cleared. Within the zone, error accumulates when kI is nonzero. Negative zone values are rejected.
To allow integration regardless of error size, use positive infinity. This is the default setting.
contr011er.setIZone(Doub1e.POSITIVE INFINITY);
= controller.getIZone();Setting kI to zero stops accumulation within the integration zone, but does not itself clear an existing integral. Use reset() when you need to discard the stored history.
Continuous Input and Controller State
Continuous input is useful for values that wrap around, such as a robot heading. Enable it using the bounds of your measurement convention.
// Headings measured in degrees.
controller.enableContinuousInput(-180.0, 180.0);
// Alternatively, headings measured in radians.
controller.enableContinuousInput(-Math.PI, Math.PI);Choose one range that matches your units. With a degree range of minus 180 to 180, a measurement of 179 degrees and a target of minus 179 degrees produce a wrapped error of plus 2 degrees. Use continuous input only when crossing the boundary is valid for the mechanism.
= controller.isContinuousInputEnabled();
controller.disableContinuousInput();Reading the Error
Without continuous input, error equals setpoint minus measurement. The derivative represents changes in error, so changing the target can also affect it.
= controller.getError();
= controller.getErrorDerivative();Read these diagnostics after calculate(). Before the first calculation, setSetpoint() can temporarily produce a nonfinite derivative because the stored period initially equals zero.
Resetting the Controller
Call reset() to clear the stored errors and integral accumulation. This also clears the measurement flag, making atSetpoint() false until another calculation supplies a measurement.
controller.reset();The target, gains, tolerances, integration settings, and continuous-input configuration remain unchanged. This implementation also preserves its timing history: after a pause, the next calculation uses the elapsed time since the previous calculation.
Complete FTC Example
This example controls a motor's encoder position. Press A to select 1000 ticks or B to select zero. Motor commands are limited to 50 percent power. Start with proportional control and tune the gains for your mechanism.
The example uses the encoder's existing zero reference. Verify that positive motor power increases the measured position and that both targets are within the mechanism's allowed travel.
import com.qualcomm.robotcore.eventloop.opmode.LinearOpMode;
import com.qualcomm.robotcore.eventloop.opmode.TeleOp;
import com.qualcomm.robotcore.hardware.DcMotor;
import dev.easyfamily.easystack.control.wpiLibControllers
.EasyPIDControllerEx;
@TeleOp(name = "EasyPIDControllerEx Example")
public class PIDControllerExample extends LinearOpMode {
@Override
public void runOpMode() {
DcMotor motor = hardwareMap.get(
DcMotor.class, "motor");
motor.setMode(DcMotor.RunMode.RUN_WITHOUT_ENCODER);
EasyPIDControllerEx controller =
new EasyPIDControllerEx(0.005, 0.0, 0.0);
controller.setTolerance(10.0);
double target = motor.getCurrentPosition();
waitForStart();The controller and motor are initialized once. The control loop on the next page continues inside the same runOpMode() method. Configure a motor named motor in the FTC robot configuration.
Complete FTC Example Continued
Each iteration reads the encoder, calculates one PID output, limits the command, and updates telemetry. The finally block stops the motor when control ends.
try {
while (opModeIsActive()) {
if (gamepad1.a) {
target = 1000.0;
} else if (gamepad1.b) {
target = 0.0;
}
double position = motor.getCurrentPosition();
double output = controller.calculate(
position, target);
double power = Math.max(
-0.5, Math.min(output, 0.5));
motor.setPower(power); telemetry.addData("Target", Target);
telemetry.addData("position", position);
telemetry.addData("Errors", controller.getError());
telemetry.addData("At Target", controller.atSetpoint ());
telemetry.addData("Period", controller.getPeriod());
telemetry.update();
} finally {
motor.setPower(@ .O);The controller continues holding the target even when atSetpoint() becomes true. Adjust that behavior to match the mechanism's needs.
Source and scope: Based on the supplied EasyPIDControllerEx.java in dev.easyfamily.EasyStack.control.wpiLibControllers. Examples illustrate integration and have not been tested on robot hardware.
Última actualización 2026-11-16