PIDController

The PID Controller class provides proportional-integral-derivative control for robotics applications on the Echo microcontroller. PID control is a feedback mechanism that helps your robot reach and maintain a target value smoothly and accurately.

What is PID Control?

PID control is a method for automatically adjusting a system to reach a desired target. Think of it like a smart thermostat for your robot.

Simple analogy: Imagine you're trying to keep a ball balanced on a platform. You need to tilt the platform just the right amount:

• Too little tilt (P): The ball moves slowly toward center

• Add memory (I): Remember if you've been off-center too long and correct harder

• Predict motion (D): See how fast the ball is rolling and adjust before it overshoots

The Three Components

P - Proportional: Reacts to current error

• "How far am I from the target right now?"

• Larger errors produce larger corrections

• Like pressing the gas pedal harder when you're further from your destination

I - Integral: Reacts to accumulated error over time

• "Have I been consistently off-target?"

• Fixes persistent small errors that P alone can't eliminate

• Like compensating for a constant uphill slope

D - Derivative: Reacts to rate of change

• "How fast am I approaching the target?"

• Slows down to prevent overshooting

• Like applying brakes as you approach your destination

---

Key Features

• Automatic target tracking with configurable tolerance

• Built-in integral windup protection

• Time-based calculation for consistent behavior

• Zero output when within target tolerance

• Pause and resume functionality

• Easy parameter tuning

---

Overview

The PID Controller class implements a proportional-integral-derivative feedback control system for precise control of sensors and actuators.

Method	Description
PIDController(P, I, D, target, maxTol, minTol)	Creates a PID controller with specified gains and target setpoint
getOutput(sensorValue)	Calculates and returns control output based on current sensor reading
pause()	Pauses the controller and resets all error accumulation
setNewTarget(target, maxTol, minTol)	Updates the target setpoint and tolerance range
setNewVals(P, I, D)	Updates the PID gain constants
setIlimit(limit)	Sets the maximum allowed integral accumulation
isOnTarget()	Returns true if sensor value is within tolerance range

---

Quick Start

#include <EchoLib.h>

// PID(P, I, D, target, maxTolerance, minTolerance)
PIDController pid(1.0, 0.1, 0.05, 100, 5, 5);

void setup() {
    Serial.begin(115200);
}

void loop() {
    int sensorValue = analogRead(A0);
    float output = pid.getOutput(sensorValue);
    
    // Use output to control motor, servo, etc.
    analogWrite(MOTOR_PIN, constrain(output, 0, 255));
}

---

API Reference

PIDController(float P, float I, float D, float target, float maxTolerance, float minTolerance)

Creates a PID controller with specified gains and target parameters.

Parameters:

• P: Proportional gain (typically 0.1 - 10.0)

• I: Integral gain (typically 0.0 - 1.0)

• D: Derivative gain (typically 0.0 - 1.0)

• target: Desired setpoint value

• maxTolerance: Upper tolerance from target (considered "on target")

• minTolerance: Lower tolerance from target (considered "on target")

Example:

// Target 500, ±10 tolerance
PIDController motorPID(2.0, 0.5, 0.1, 500, 10, 10);

---

getOutput(float sensorValue)

float getOutput(float sensorValue)

Calculates the PID output based on the current sensor reading.

Parameters:

• sensorValue: Current measurement from sensor

Returns:

• float: Control output (can be positive or negative)

• Returns 0 when within tolerance range

Example:

int encoder = readEncoder();
float motorPower = pid.getOutput(encoder);

// Apply output to motor
if (motorPower > 0) {
    digitalWrite(MOTOR_DIR, HIGH);
    analogWrite(MOTOR_PWM, abs(motorPower));
} else {
    digitalWrite(MOTOR_DIR, LOW);
    analogWrite(MOTOR_PWM, abs(motorPower));
}

---

setNewTarget(float target, float maxTolerance, float minTolerance)

void setNewTarget(float target, float maxTolerance, float minTolerance)

Updates the target setpoint and tolerance values during operation.

Parameters:

• target: New target value

• maxTolerance: New upper tolerance

• minTolerance: New lower tolerance

Example:

// Change target from 100 to 200
pid.setNewTarget(200, 10, 10);

---

setNewVals(float P, float I, float D)

void setNewVals(float P, float I, float D)

Updates the PID gain values during operation. Useful for adaptive control or switching between different tuning profiles.

Parameters:

• P: New proportional gain

• I: New integral gain

• D: New derivative gain

Example:

// Switch to more aggressive tuning
pid.setNewVals(2.5, 0.8, 0.2);

// Switch to gentler tuning
pid.setNewVals(0.5, 0.05, 0.01);

---

setIlimit(float limit)

void setIlimit(float limit)

Sets the integral windup limit. The integral term only accumulates when error is less than this limit.

Parameters:

• limit: Maximum error for integral accumulation

Example:

pid.setIlimit(50);  // Only integrate errors smaller than 50

Note: This prevents the integral term from becoming excessively large when far from target.

---

isOnTarget()

bool isOnTarget()

Returns whether the current sensor value is within the acceptable tolerance range.

Returns:

• true: Sensor value is within target ± tolerance

• false: Sensor value is outside tolerance range

Example:

if (pid.isOnTarget()) {
    Serial.println("Target reached!");
    digitalWrite(LED_PIN, HIGH);
} else {
    digitalWrite(LED_PIN, LOW);
}

---

pause()

void pause()

Pauses the PID controller and resets all accumulated values. Use this when temporarily disabling control.

Example:

if (emergencyStop) {
    pid.pause();
    digitalWrite(MOTOR_PIN, LOW);
}

---

Tuning Your PID Controller

Start with these steps to tune your PID gains:

Step 1: Set I and D to Zero

PIDController pid(1.0, 0.0, 0.0, target, tolerance, tolerance);

Adjust P until the system responds but may oscillate slightly.

Step 2: Add Integral

PIDController pid(1.0, 0.1, 0.0, target, tolerance, tolerance);

Increase I slowly to eliminate steady-state error. Too much will cause instability.

Step 3: Add Derivative

PIDController pid(1.0, 0.1, 0.05, target, tolerance, tolerance);

Add D to reduce overshoot and oscillations. Start small.

Quick Guidelines

Proportional (P):

• Too low: Slow response, never reaches target

• Too high: Oscillates around target

• Start with: 1.0

Integral (I):

• Too low: Persistent small error remains

• Too high: Oscillations increase, instability

• Start with: 0.1

Derivative (D):

• Too low: Overshoots target

• Too high: Sluggish, noise sensitive

• Start with: 0.05

---

Best Practices

Set Appropriate Tolerances

Define a realistic tolerance range where "close enough" is acceptable:

// For position control, ±5 units might be acceptable
PIDController pid(1.0, 0.1, 0.05, 500, 5, 5);

Use Integral Limits

Prevent integral windup by setting a reasonable limit:

pid.setIlimit(50);  // Adjust based on your system

Constrain Output

Always constrain PID output to safe ranges:

float output = pid.getOutput(sensor);
int motorPower = constrain(abs(output), 0, 255);

Reset When Necessary

Pause the PID when stopping or changing modes:

if (modeChange) {
    pid.pause();  // Clear accumulated errors
}

---

Common Issues

Oscillation Around Target

Cause: P gain too high or D gain too low

Solution:

• Reduce P gain by 20-30%

• Slightly increase D gain

Never Reaches Target

Cause: P gain too low or persistent external force

Solution:

• Increase P gain

• Add or increase I gain to handle constant offset

Overshoot and Slow Recovery

Cause: I gain accumulating too much error

Solution:

• Reduce I gain

• Set a lower integral limit with setIlimit()

Unstable or Erratic Behavior

Cause: Gains too high or sensor noise

Solution:

• Reduce all gains by 50% and re-tune

• Filter sensor readings before feeding to PID

---

Technical Details

Update Rate

The PID controller uses time-based calculations, automatically adjusting for varying loop speeds. However, consistent update rates produce better results:

• Recommended: 10-100ms update interval

• Minimum: 1ms (for very fast systems)

• Maximum: 1000ms (for slow systems)

Internal Timer

The PID controller uses the Timer class internally for accurate time-based calculations. You don't need to manage this timer yourself.

Zero Output Zone

When the sensor value is within the tolerance range (target ± tolerance), the PID automatically returns zero output to prevent unnecessary corrections.

---

Integration with Timer Class

The PID controller automatically uses the Timer class for time-based calculations. You can still use separate Timer instances for other timing needs in your code:

#include <EchoLib.h>

PIDController pid(1.0, 0.1, 0.05, 100, 5, 5);
Timer reportTimer;  // Separate timer for status reporting

void setup() {
    Serial.begin(115200);
    reportTimer.start();
}

void loop() {
    float output = pid.getOutput(analogRead(A0));
    
    // PID runs continuously
    analogWrite(MOTOR_PIN, constrain(abs(output), 0, 255));
    
    // Separate timer for periodic reporting
    if (reportTimer.get() >= 1000) {
        Serial.println("Output: " + String(output));
        reportTimer.reset();
        reportTimer.start();
    }
}