Skip to content

Commit

Permalink
Major update
Browse files Browse the repository at this point in the history 
### QuickPID 3.0.0

Many changes:

-  Removed AutoTune in preparation for a new AutoTune library compatible with `QuickPID`, `PID_v1` and others (coming soon)
-  Added a few more controller options, all easily configured using enum named values
- Proportional and Derivative options are also easily configured using enum named values
- New integral ant-windup options include `CONDITION`, `CLAMP` (default) and `OFF`

- Updated documentation and examples
  • Loading branch information
@Dlloydev
Dlloydev committed Dec 12, 2021
1 parent dd773fe commit 576d714
Show file tree
Hide file tree
Showing 17 changed files with 227 additions and 913 deletions.
99 changes: 31 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,78 +1,48 @@
# QuickPID [![arduino-library-badge](https://www.ardu-badge.com/badge/QuickPID.svg?)](https://www.ardu-badge.com/QuickPID)

QuickPID is an updated implementation of the Arduino PID library with a built-in [AutoTune](https://github.com/Dlloydev/QuickPID/wiki/AutoTune) class as a dynamic object to reduce memory if not used, thanks to contributions by [gnalbandian (Gonzalo)](https://github.com/gnalbandian). This controller can automatically determine and set parameters `Kp, Ki, Kd`. Additionally the Ultimate Gain `Ku`, Ultimate Period `Tu`, Dead Time `td` and determine how easy the process is to control. There are 10 tuning rules available to choose from. Also available are POn and DOn settings where POn controls the mix of Proportional on Error to Proportional on Measurement and DOn controls the mix of Derivative on Error to Derivative on Measurement.

#### [QuickPID WiKi ...](https://github.com/Dlloydev/QuickPID/wiki)
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. However, the additional features like integral anti-windup based on conditional-conditioning, clamping, or turning it off completely. Also, the proportional term can be based on error, measurement, or both. The derivative term can be based on error or measurement. The controller modes includes `TIMER`, which allows external timer or ISR timing control.

### Features

Development began with a fork of the Arduino PID Library. Modifications and new features have been added as described in the [change log](https://github.com/Dlloydev/QuickPID/wiki/Change-Log).
Development began with a fork of the Arduino PID Library. Modifications and new features have been added as described in the [releases](https://github.com/Dlloydev/QuickPID/releases).

#### New feature Summary

- [x] Fast PID read-compute-write cycle (Arduino UNO): QuickPID = **51µs**, PID_v1 = **128µs**
- [x] `TIMER` mode for calling PID compute by an external timer function or ISR
- [x] `analogReadFast()` support for AVR (4x faster)
- [x] `analogWrite()` support for ESP32 and ESP32-S2
- [x] Variable Proportional on Error to Proportional on Measurement parameter `POn`
- [x] Variable Derivative on Error to Derivative on Measurement parameter `DOn`
- [x] New PID Query Functions: `GetPterm();` `GetIterm();` `GetDterm();`
- [x] Uses conditional and clamping Integral anti-windup methods
- [x] New REVERSE mode only changes sign of `error` and `dInput`
- [x] Proportional on error `PE`, measurement `PM` or both `PEM` options
- [x] Derivative on error `DE` and measurement `DM` options
- [x] New PID Query Functions `GetPterm`, `GetIterm`, `GetDterm`, `GetPmode`, `GetDmode` and `GetAwMode`
- [x] New integral anti-windup options `CONDITION`, `CLAMP` and `OFF`
- [x] New `REVERSE` mode only changes sign of `error` and `dInput`
- [x] Uses `float` instead of `double`

#### AutoTune Features (to be updated in upcoming version 3.0.0)

- [x] AutoTune class provided as a dynamic object and includes 10 tuning methods
- [x] Compatible with reverse acting controllers
- [x] Fast, non-blocking tuning sequence completes in only 1.5 oscillations
- [x] Determines how easy the process is to control
- [x] Determines ultimate period `Tu`, dead time `td`, ultimate gain `Ku`, and tuning parameters `Kp, Ki, Kd`

### [AutoTune](https://github.com/Dlloydev/QuickPID/wiki/AutoTune)

#### [AutoTune Filter Examples](https://github.com/Dlloydev/QuickPID/wiki/AutoTune-Filter-Examples)

The examples [AutoTune_Filter_DIRECT.ino](https://github.com/Dlloydev/QuickPID/blob/master/examples/AutoTune_Filter_DIRECT/AutoTune_Filter_DIRECT.ino) and [AutoTune_Filter_REVERSE.ino](https://github.com/Dlloydev/QuickPID/blob/master/examples/AutoTune_Filter_REVERSE/AutoTune_Filter_REVERSE.ino) allow you to experiment with the AutoTunePID class, various tuning rules and the POn and DOn controls using ADC and PWM with RC filter. It automatically determines and sets the tuning parameters and works with both `DIRECT` and `REVERSE` acting controllers.

#### Direct and Reverse Controller Action

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).
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).

### Functions

#### QuickPID_Constructor

```c++
QuickPID::QuickPID(float* Input, float* Output, float* Setpoint,
float Kp, float Ki, float Kd, float POn, float DOn, uint8_t ControllerDirection);
float Kp, float Ki, float Kd, uint8_t pMode = PE, uint8_t dMode = DM,
uint8_t awMode = CLAMP, uint8_t Action = DIRECT)
```
- `Input`, `Output`, and `Setpoint` are pointers to the variables holding these values.
- `Kp`, `Ki`, and `Kd` are the PID proportional, integral, and derivative gains.
- `POn` controls the mix of Proportional on Error to Proportional on Measurement. Range is 0.0-1.0, default = 1.0
- `DOn` controls the amount of Derivative on Error and the amount of Derivative on Measurement. Range is 0.0-1.0, default = 0.0. Note that Derivative on Error (at any point in time) is opposite and equal to Derivative on Measurement, so equal mixing of both (DOn =0.5) will result in the derivative term being 0. At this point, the controller becomes PI only.
| DOn Setting | Description |
| ----------- | ---------------------------------------- |
| 0.0 | 100% Derivative on Measurement (default) |
| 0.25 | 50% Derivative on Measurement |
| 0.5 | 0% Derivative (PI control only) |
| 0.75 | 50% Derivative on Error |
| 1.0 | 100% Derivative on Error |
![POnDOn](https://user-images.githubusercontent.com/63488701/120000053-68de3e00-bfa0-11eb-9db2-04c2f4be76a2.png)
- `ControllerDirection` Either DIRECT or REVERSE sets how the controller responds to a change in input. DIRECT action will lead the output to increase when the input is larger than the setpoint (i.e. heating process). REVERSE action will lead the output to decrease when the input is larger than the setpoint (i.e. cooling process).
- `pMode` is the proportional mode parameter with options for `PE` proportional on error (default), `PM` proportional on measurement and `PEM` which is 0.5 `PE` + 0.5 `PM`.
- `dMode` is the derivative mode parameter with options for `DE` derivative on error (default), `DM` derivative on measurement (default).
- `awMode` is the integral anti-windup parameter with options for `CONDITION` which is based on PI terms to provide some integral correction and prevent deep saturation, `CLAMP` (default) which clamps the summation of the pmTerm and iTerm. The `OFF` option turns off all anti-windup.
- `Action` is the controller action parameter which has `DIRECT` (default) and `REVERSE` options. These options set how the controller responds to a change in input. `DIRECT` action will lead the output to increase when the input is larger than the setpoint (i.e. heating process). `REVERSE` action will lead the output to decrease when the input is larger than the setpoint (i.e. cooling process).
```c++
QuickPID::QuickPID(float* Input, float* Output, float* Setpoint,
float Kp, float Ki, float Kd, uint8_t ControllerDirection);
float Kp, float Ki, float Kd, uint8_t Action = DIRECT)
```

This allows you to use Proportional on Error without explicitly saying so.
Expand All @@ -88,7 +58,7 @@ This function contains the PID algorithm and it should be called once every loop
#### SetTunings

```c++
void QuickPID::SetTunings(float Kp, float Ki, float Kd, float POn, float DOn);
void QuickPID::SetTunings(float Kp, float Ki, float Kd, uint8_t pMode = PE, uint8_t dMode = DM, uint8_t awMode = CLAMP)
```
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.
Expand Down Expand Up @@ -118,15 +88,13 @@ The PID controller is designed to vary its output within a given range. By defa
#### SetMode

```c++
void QuickPID::SetMode(uint8_t Mode);
void QuickPID::SetMode(uint8_t Mode)
```
Allows the controller Mode to be set to `MANUAL` (0) 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:
- [AutoTune_AVR_Interrupt_TIMER.ino](https://github.com/Dlloydev/QuickPID/blob/master/examples/AutoTune_AVR_Interrupt_TIMER/AutoTune_AVR_Interrupt_TIMER.ino)
- [AutoTune_AVR_Software_TIMER.ino](https://github.com/Dlloydev/QuickPID/blob/master/examples/AutoTune_AVR_Software_TIMER/AutoTune_AVR_Software_TIMER.ino)
- [PID_AVR_Basic_Interrupt_TIMER.ino](https://github.com/Dlloydev/QuickPID/blob/master/examples/PID_AVR_Basic_Interrupt_TIMER/PID_AVR_Basic_Interrupt_TIMER.ino)
- [PID_AVR_Basic_Software_TIMER.ino](https://github.com/Dlloydev/QuickPID/blob/master/examples/PID_AVR_Basic_Software_TIMER/PID_AVR_Basic_Software_TIMER.ino)
Expand All @@ -141,34 +109,29 @@ Does all the things that need to happen to ensure a bump-less transfer from manu
#### SetControllerDirection

```c++
void QuickPID::SetControllerDirection(uint8_t Direction)
void QuickPID::SetControllerDirection(uint8_t 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.
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.
#### PID Query Functions
```c++
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
mode_t GetMode(); // MANUAL (0) or AUTOMATIC (1) or TIMER (2)
direction_t GetDirection(); // DIRECT (0) or REVERSE (1)
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(); // PE (0), PM (1), PEM (2)
uint8_t GetDmode(); // DE (0), DM (1)
uint8_t GetAwMode(); // CONDITION (0, CLAMP (1), OFF (2)
```

These functions query the internal state of the PID.

#### Utility Functions

```c++
int QuickPID::analogReadFast(int ADCpin)
```
A faster configuration of `analogRead()`where a preset of 32 is used. If the architecture definition isn't found, normal `analogRead()`is used to return a value.
#### [AnalogWrite (PWM and DAC) for ESP32](https://github.com/Dlloydev/ESP32-ESP32S2-AnalogWrite)

Use this link for reference. Note that if you're using QuickPID, there's no need to install the AnalogWrite library as this feature is already included.
Expand All @@ -184,7 +147,7 @@ Use this link for reference. Note that if you're using QuickPID, there's no need
***************************************************************
```

- For an ultra-detailed explanation of why the code is the way it is, please visit:
- For an ultra-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
Expand Down
107 changes: 0 additions & 107 deletions examples/AutoTune_AVR_Interrupt_TIMER/AutoTune_AVR_Interrupt_TIMER.ino
View file

This file was deleted.

Loading

0 comments on commit 576d714

Please sign in to comment.