QuickPID is an updated implementation of the Arduino PID library with additional features for PID control. By default, this implementation closely follows the method of processing the p,i,d terms as in the PID_v1 library except for using a more advanced anti-windup mode. Integral anti-windup can be based on conditionally using PI terms to provide some integral correction, prevent deep saturation and reduce overshoot. Anti-windup can also be based on clamping only, or it can be turned completely off. Also, the proportional term can be based on error, measurement, or both. The derivative term can be based on error or measurement. PID controller modes include timer, which allows external timer or ISR timing control.
Development began with a fork of the Arduino PID Library. Modifications and new features have been added as described in the releases.
- New functions added:
SetProportionalMode,SetDerivativeModeandSetAntiWindupMode -
timermode for calling PID compute by an external timer function or ISR -
analogWrite()support for ESP32 and ESP32-S2 - Proportional on error
pOnError, measurementpOnMeasor bothpOnErrorMeasoptions - Derivative on error
dOnErrorand measurementdOnMeasoptions - New PID Query Functions
GetPterm,GetIterm,GetDterm,GetPmode,GetDmodeandGetAwMode - New integral anti-windup options
iAwCondition,iAwClampandiAwOff - New
reversemode only changes sign oferroranddInput - Uses
floatinstead ofdouble
Direct controller action leads the output to increase when the input is larger than the setpoint (i.e. heating process). Reverse controller leads the output to decrease when the input is larger than the setpoint (i.e. cooling process).
When the controller is set to reverse acting, the sign of the error and dInput (derivative of Input) is internally changed. All operating ranges and limits remain the same. To simulate a reverse acting process from a process that's direct acting, the Input value needs to be "flipped". That is, if your reading from a 10-bit ADC with 0-1023 range, the input value used is (1023 - reading).
QuickPID::QuickPID(float* Input, float* Output, float* Setpoint, float Kp, float Ki, float Kd,
pMode pMode = pMode::pOnError, dMode dMode = dMode::dOnMeas,
iAwMode iAwMode = iAwMode::iAwCondition, Action action = Action::direct)Input,Output, andSetpointare pointers to the variables holding these values.Kp,Ki, andKdare the PID proportional, integral, and derivative gains.pModeis the proportional mode parameter with options forpOnErrorproportional on error (default),pOnMeasproportional on measurement andpOnErrorMeaswhich is 0.5pOnError+ 0.5pOnMeas.dModeis the derivative mode parameter with options fordOnErrorderivative on error,dOnMeasderivative on measurement (default).awModeis the integral anti-windup parameter with an option foriAwCondition(default) that is based on PI terms to provide some integral correction, prevent deep saturation and reduce overshoot. TheiAwClampoption clamps the summation of the pmTerm and iTerm. TheiAwOffoption turns off all anti-windup.Actionis the controller action parameter which hasdirect(default) andreverseoptions. These options set how the controller responds to a change in input.directaction is used if the input moves in the same direction as the controller output (i.e. heating process).reverseaction is used if the input moves in the opposite direction as the controller output (i.e. cooling process).
QuickPID::QuickPID(float* Input, float* Output, float* Setpoint,
float Kp, float Ki, float Kd, Action action)This allows you to use Proportional on Error without explicitly saying so.
QuickPID::QuickPID(float *Input, float *Output, float *Setpoint)This simplified version allows you to define the remaining parameters later via specific setter functions. By default, Kp, Ki, and Kd will be initialized to zero and should be later set via SetTunings to relevant values.
bool QuickPID::Compute();This function contains the PID algorithm and it should be called once every loop(). Most of the time it will just return false without doing anything. However, at a frequency specified by SetSampleTime it will calculate a new Output and return true.
void QuickPID::Initialize();Does all the things that need to happen to ensure a bump-less transfer from manual to automatic mode.
These functions query the internal state of the PID.
float GetKp(); // proportional gain
float GetKi(); // integral gain
float GetKd(); // derivative gain
float GetPterm(); // proportional component of output
float GetIterm(); // integral component of output
float GetDterm(); // derivative component of output
uint8_t GetMode(); // manual (0), automatic (1) or timer (2)
uint8_t GetDirection(); // direct (0), reverse (1)
uint8_t GetPmode(); // pOnError (0), pOnMeas (1), pOnErrorMeas (2)
uint8_t GetDmode(); // dOnError (0), dOnMeas (1)
uint8_t GetAwMode(); // iAwCondition (0, iAwClamp (1), iAwOff (2)These functions set the internal state of the PID.
void SetMode(Control mode); // Set PID mode to manual, automatic or timer
void SetOutputLimits(float Min, float Max); // Set and clamps the output to (0-255 by default)
void SetTunings(float Kp, float Ki, float Kd, // set pid tunings and all computational modes
pMode pMode, dMode dMode, iAwMode iAwMode);
void SetTunings(float Kp, float Ki, float Kd); // only set pid tunings, other pid modes are unchanged
void SetControllerDirection(Action Action); // Set controller action to direct (default) or reverse
void SetSampleTimeUs(uint32_t NewSampleTimeUs); // Set PID compute sample time, default = 100000 µs
void SetProportionalMode(pMode pMode); // Set pTerm based on error (default), measurement, or both
void SetDerivativeMode(dMode dMode); // Set the dTerm, based error or measurement (default).
void SetAntiWindupMode(iAwMode iAwMode); // Set iTerm anti-windup to iAwCondition, iAwClamp or iAwOffvoid QuickPID::SetMode(Control Mode);Allows the controller Mode to be set to manual (0) (default) or automatic (1) or timer (2). when the transition from manual to automatic or timer occurs, the controller is automatically initialized. timer mode is used when the PID compute is called by an external timer function or ISR. In this mode, the timer function and SetSampleTimeUs use the same time period value. The PID compute and timer will always remain in sync because the sample time variable and calculations remain constant.
See examples: PID_AVR_Basic_Interrupt_TIMER.ino and PID_AVR_Basic_Software_TIMER.ino
void QuickPID::SetOutputLimits(float Min, float Max);The PID controller is designed to vary its output within a given range. By default this range is 0-255, the Arduino PWM range.
void QuickPID::SetTunings(float Kp, float Ki, float Kd, pMode pMode = pMode::pOnError,
dMode dMode = dMode::dOnMeas, iAwMode iAwMode = iAwMode::iAwCondition)This function allows the controller's dynamic performance to be adjusted. It's called automatically from the constructor, but tunings can also be adjusted on the fly during normal operation. The parameters are as described in the constructor.
void QuickPID::SetTunings(float Kp, float Ki, float Kd);Set Tunings using the last remembered pMode, dMode and iAwMode settings. See example PID_AdaptiveTunings.ino
void QuickPID::SetControllerDirection(Action Action);The PID will either be connected to a direct acting process (+Output leads to +Input) or a reverse acting process (+Output leads to -Input.) We need to know which one, because otherwise we may increase the output when we should be decreasing. This is called from the constructor.
void QuickPID::SetSampleTimeUs(uint32_t NewSampleTimeUs);Sets the period, in microseconds, at which the calculation is performed. The default is 100000µs (100ms).
void QuickPID::SetProportionalMode(pMode pMode);Sets the computation method for the proportional term, to compute based either on error (default), on measurement, or the average of both.
void QuickPID::SetDerivativeMode(dMode dMode);Sets the computation method for the derivative term, to compute based either on error or on measurement (default).
void QuickPID::SetAntiWindupMode(iAwMode iAwMode);Sets the integral anti-windup mode to one of iAwClamp, which clamps the output after adding integral and proportional (on measurement) terms, or iAwCondition (default), which provides some integral correction, prevents deep saturation and reduces overshoot. Option iAwOff disables anti-windup altogether.
If you're using QuickPID with an ESP32 and need analogWrite compatibility, there's no need to install a library as this feature is already included. AnalogWrite documentation
***************************************************************
* Arduino PID Library - Version 1.2.1
* by Brett Beauregard <br3ttb@gmail.com> brettbeauregard.com
*
* This Library is licensed under the MIT License
***************************************************************
-
For a detailed explanation of the original code, please visit: http://brettbeauregard.com/blog/2011/04/improving-the-beginners-pid-introduction/
-
For function documentation see: http://playground.arduino.cc/Code/PIDLibrary