| Name | PID-Py JSON |
| Version |
1.2.2
JSON |
| download |
| home_page | None |
| Summary | Simple (but complete) PID controller in Python |
| upload_time | 2024-05-28 00:00:42 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2023 ThunderTecke Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
pid
controller
pid-controller
control
pid-control
python
raspberry
raspberrypi
raspberry-pi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://github.com/ThunderTecke/PID_Py/blob/develop/LICENSE)
[](https://github.com/ThunderTecke/PID_Py/releases)
[](https://github.com/ThunderTecke/PID_Py/releases)
[](https://github.com/ThunderTecke/PID_Py/commits)
[](https://github.com/ThunderTecke/PID_Py/issues)
# PID_Py <!-- omit in toc -->
`PID_Py` provide a PID controller written in Python. This PID controller is simple to use, but it's complete.
## :bangbang: Non-responsability :bangbang: <!-- omit in toc -->
***<span style="color:red">I am not responsible for any material or personal damages in case of failure. Use at your own risk.</span>***
## Table of content <!-- omit in toc -->
- [Installation](#installation)
- [Usage](#usage)
- [Minimum usage](#minimum-usage)
- [Indirect action PID](#indirect-action-pid)
- [Integral limitation](#integral-limitation)
- [Limiting output](#limiting-output)
- [Proportionnal on measurement](#proportionnal-on-measurement)
- [Derivative on measurement](#derivative-on-measurement)
- [Integral freezing](#integral-freezing)
- [Deadband](#deadband)
- [Setpoint ramp](#setpoint-ramp)
- [Setpoint reached by the process value](#setpoint-reached-by-the-process-value)
- [Process value stabilized indicator](#process-value-stabilized-indicator)
- [Historian](#historian)
- [Historian parameters list](#historian-parameters-list)
- [Manual mode](#manual-mode)
- [Logging](#logging)
- [Time simulation](#time-simulation)
- [Threaded PID](#threaded-pid)
- [Simulation](#simulation)
- [SetupTool](#setuptool)
- [Usage](#usage-1)
- [Read-only and read-write mode](#read-only-and-read-write-mode)
- [Control on PID](#control-on-pid)
## Installation
```
python3 -m pip install PID_Py
```
## Usage
### Minimum usage
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 10.0, ki = 5.0, kd = 0.0)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In this usage the PID as no limitation, no history and the PID is in direct action (Error increasing -> Increase output).
### Indirect action PID
If you have a system that required to decrease command to increase feedback, you can use `indirectAction` parameters.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 10.0, ki = 5.0, kd = 0.0, indirectAction = True)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
### Integral limitation
The integral part of the PID can be limit to avoid overshoot of the output when the error is too high (When the setpoint variation is too high, or when the system have trouble to reach setpoint).
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 10.0, ki = 5.0, kd = 0.0, integralLimit = 20.0)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, the integral part of the PID is clamped between -20 and 20.
### Limiting output
If your command must be limit you can use `outputLimits` parameters.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 10.0, ki = 5.0, kd = 0.0, outputLimits = (-20, 20))
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
By default the value is `(None, None)`, which implies that there is no limits. You can activate just the maximum limit with `(None, 100)`. The same for the minimum limit `(-100, None)`.
### Proportionnal on measurement
This avoid a strong response of proportionnal part when the setpoint is suddenly changed.
This change the P equation as follow :
- False : P = error * kp
- True : P = -(processValue * kp)
This result in an augmentation of the stabilization time of the system, but there is no bump on the output when the setpoint change suddenly. There is no difference on the reponds to process disturbance.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 3.0, ki = 5.0, kd = 0.0, proportionnalOnMeasurement=True)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
### Derivative on measurement
This avoid a strong response of derivate part when the setpoint is suddenly changed.
This change the D equation as follow :
- False : D = ((error - lastError) / dt) * kd
- True : D = -(((processValue - lastProcessValue) / dt) * kd)
The effect is there is no bump when the setpoint change suddenly, and there is no difference on the responds to process disturbance.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 10.0, ki = 5.0, kd = 0.2, derivativeOnMeasurement=True)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
### Integral freezing
When a known disturbance occur, the integral part can be freezed to avoid increasing of its value during the perturbance.
For example, in a oven. When temperature is stable, and the door is opened the temperature drops quickly. And when the door is closed again, the temperature will rise to the previous temperature. So integral part value don't need to be increased to reach temperature setpoint.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0)
...
pid.integralFreezing = doorIsOpened
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, the integral part value is freezed when the door is open. When the door is closed the integral part value resumes its calculation.
The door is opened between 5 and 7 second. For the example, the setpoint is increase during the freezing.
### Deadband
A deadband can be set, by default its deactivated. It can be activated by entering a value to `deadband`. When the error is between [-`deadband`, `deadband`] for `deadbandActivationTime` (in second) the integral is no longer calculated. If the error exceed `deadband` the integral part is recalculated.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, deadband=1.0, deadbandActivationTime = 10.0)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, the PID behaves normally until the error is lower than 1 for 10 seconds. The integral part stops. Then when the error is higher than 1.0 the integral is recalculated.
### Setpoint ramp
The setpoint variation can be limited with `setpointRamp` option.
This option allow to make a ramp with the setpoint when this one change.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, setpointRamp=10.0)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, the setpoint has a maximal ramp of 10 units per second.
If the setpoint is change to 10 from 0, the real setpoint used will change for 1 second to 10.0.
The same behavior in negative, but with `-setpointRamp`.
### Setpoint reached by the process value
The PID can return that the process value is stable on the setpoint. To configure it use `setpointStableLimit` to define the maximum difference between the process value and the setpoint (error) to considered the setpoint reached. And use `setpointStableTime` to define an amount of time to considered the setpoint reached
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, setpointStableLimit=0.1, setpointStableTime=1.0)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example abose, the output `setpointReached` is set to `True` when the error is between -0.1 and +0.1 for 1.0 second. If the error exceed +/- 0.1, the output is reset.
### Process value stabilized indicator
The PID can return that the process value is stabilized, to configure it use `processValueStableLimit` to define the maximum variation when the process value is stable, and `processValueStableTime` to define the amount of time when the variation is below the limit.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, processValueStableLimit=0.1, processValueStableTime=1.0)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, the output `processValueStabilized` is set to `True` when the process value variation do not exceed +/- 0.1 unit/s for 1.0 second. If the process value variation exceed +/- 0.1 unit/s the output `processValueStabilized` is set to `False`.
### Historian
If you want to historize PID values, you can configure the historian to record values.
```Python
from PID_Py.PID import PID
from PID_Py.PID import HistorianParams
# Initialization
HistorianParams = HistorianParams.SETPOINT | HistorianParams.PROCESS_VALUE
pid = PID(kp = 10.0, ki = 5.0, kd = 0.0, HistorianParams = HistorianParams)
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
...
# PID Historian
import matplotlib.pyplot as plt
plt.plot(pid.historian["TIME"], pid.historian["SETPOINT"], label="Setpoint")
plt.plot(pid.historian["TIME"], pid.historian["PROCESS_VALUE"], label="Process value")
plt.legend()
plt.show()
```
In the example above, the PID historian records `setpoint`, `processValue`. `time` is also recorded when at least one parameter is recorded. Time is the elapsed time from the start. After that a graphic is draw with `matplotlib`.
#### Historian parameters list
- `P` : proportionnal part
- `I` : integral part
- `D` : derivative part
- `ERROR` : PID error
- `SETPOINT` : PID setpoint
- `PROCESS_VALUE` : PID process value
- `OUTPUT` : PID output
The maximum lenght of the historian can be choose. By default it is set to 100 000 record per parameter. Take care about your memory.
In example for one parameters. A `float` value take 24 bytes in memory. So `100 000` floats take `2 400 000` bytes (~2.3MB).
For all parameters it takes `16 800 000` bytes (~16MB).
It's not big for a computer, but if PID is executed each millisecond (0.001s), 100 000 record represent only 100 seconds of recording.
If you want to save 1 hour at 1 millisecond you will need 3 600 000 records (~82.4MB) for one parameter, and for all parameters it will takes ~576.8MB.
For a raspberry pi 3 B+ it's the half of the RAM capacity (1GB)
### Manual mode
The PID can be switch in manual mode, this allow to operate output directly through `manualValue`.
```Python
from PID_Py.PID import PID
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0)
...
# Manual mode
pid.manualMode = True
pid.manualValue = 12.7
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, command will be always equal to 12.7. The PID calculation is no longer executed. The integral part is keep equal to output minus proportionnal part, this allow a smooth switching to automatic.
To avoid bump when switching in manual there is `bumplessSwitching` attribute. This attributes keep `manualValue` equal to `output`.
If you disable this function you will have bump when you switch in manual mode with `manualValue` different of `output`. If this case you can **destabilise** (:heavy_exclamation_mark:) your system. Be careful
### Logging
The PID can use a logger (logging.Logger built-in class) to log event. Logging configuration can be set outside of the PID.
See [logging.Logger](https://docs.python.org/3/library/logging.html#logger-objects) documentation.
```Python
from PID_Py.PID import PID
import logging
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, logger = logging.getLogger("PID"))
...
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback)
```
In the example above, the PID will send event on the logger. The logger can also get with the name.
```Python
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, logger = "PID")
```
### Time simulation
The time can be simulated by passing current time to the PID. This feature must not be used with a real application. It's only for simulation purpose.
This allows to view the PID reaction quickly.
```Python
from PID_Py.PID import PID
import numpy as np
# Initialization
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0)
timeValues = np.arange(0, 20.0, 0.001)
...
for t in timeValues:
# PID execution (call it as fast as you can)
command = pid(setpoint = targetValue, processValue = feedback, t = t)
```
In the example above `timeValues` is a numpy array that contain [0.0, 0.001, 0.002, 0.003, ..., 19.999]. And with the for loop, we can calculate 20 seconds very quickly.
And then use the historian to view the PID reaction.
### Threaded PID
With the threaded PID you don't have to call `pid(processValue, setpoint)`. It's call as fast as possible or with a constant cycle time. When you want to stop the PID use `quit` attribute to finish the current execution and exit.
```Python
from PID_Py.PID import ThreadedPID
# Initialization
pid = ThreadedPID(kp = 2.0, ki = 5.0, kd = 0.0, cycleTime = 0.01)
pid.start()
...
# PID inputs
pid.setpoint = targetValue
pid.processValue = feedback
# PID output
command = pid.output
...
# Stop PID
pid.quit = True
pid.join()
```
In the example above the threaded PID is created with 10ms (0.01s) of cyclic time. It means that the calculation is executed each 10ms.
### Simulation
A simulation can be activate to simulate a real application.
```Python
from PID_Py.PID import PID
from PID_Py.Simulation import Simulation
# Initialization
simulation = Simulation(K = 1.0, tau = 0.1)
pid = PID(kp = 2.0, ki = 5.0, kd = 0.0, simulation=simulation)
...
command = pid(setpoint = targetValue)
```
## SetupTool
SetupTool is a tool to help you to configure the PID's parameters.
A trend with the historian values is displayed to show the PID behaviour.
### Usage
To use SetupTool you need to import QApplication from PySide6.QtWidgets, then create an application and instantiate SetupTool.
After the SetupTool is open, you can see real-time chart updated every second, and on the right all PID's parameters you can adjust in read-write mode.
After having taken control on the setpoint, you can also send a new setpoint to the PID.
```Python
# PID imports
from PID_Py.PID import PID, ThreadedPID, HistorianParams
from PID_Py.SetupTool import SetupToolApp
from PID_Py.Simulation import Simulation
# PySide6 (PyQt) imports
from PySide6.QtWidgets import QApplication
import sys
# Threaded PID creation
pid = ThreadedPID(kp=1, ki=0, kd=0.0,
cycleTime=0.01,
historianParams=HistorianParams.SETPOINT | HistorianParams.PROCESS_VALUE,
simulation=Simulation(1, 1))
pid.start()
# PyQt application creation
app = QApplication(sys.argv)
# SetupTool instantiation
setupToolApp = SetupToolApp(pid)
setupToolApp.show()
# Application execution
app.exec()
# Application ended, stop the PID
pid.quit = True
pid.join()
```
In the example above, a threaded PId is created and gave to SetupTool constructor.
If have a not threaded PID, you can execute PyQt application in a parallel thread.
### Read-only and read-write mode
When SetupTool is instantiate the read-only mode is activated. This mode prevent any modification on the PID's parameters.
If you want to modify PID's parameters you need to switch on read-write mode. Then all parameters are unlocked.
### Control on PID
When SetulTool is instantiate, you don't have the control on the setpoint.
If you want to override setpoint, you need to take the control. Then the setpoint is unlocked. Write the new setpoint and then click on "apply".
Raw data
{
"_id": null,
"home_page": null,
"name": "PID-Py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "ThunderTecke <thunder.tecke@gmail.com>",
"keywords": "pid, controller, pid-controller, control, pid-control, python, raspberry, raspberrypi, raspberry-pi",
"author": null,
"author_email": "ThunderTecke <thunder.tecke@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ae/c8/25f2fa34ec187d4ffef5a691ccc325e5ce17290e4ac500689f6d589b9c03/pid_py-1.2.2.tar.gz",
"platform": null,
"description": "[](https://github.com/ThunderTecke/PID_Py/blob/develop/LICENSE)\r\n[](https://github.com/ThunderTecke/PID_Py/releases)\r\n[](https://github.com/ThunderTecke/PID_Py/releases)\r\n[](https://github.com/ThunderTecke/PID_Py/commits)\r\n[](https://github.com/ThunderTecke/PID_Py/issues)\r\n\r\n\r\n# PID_Py <!-- omit in toc -->\r\n`PID_Py` provide a PID controller written in Python. This PID controller is simple to use, but it's complete.\r\n\r\n## :bangbang: Non-responsability :bangbang: <!-- omit in toc -->\r\n***<span style=\"color:red\">I am not responsible for any material or personal damages in case of failure. Use at your own risk.</span>***\r\n\r\n## Table of content <!-- omit in toc -->\r\n- [Installation](#installation)\r\n- [Usage](#usage)\r\n - [Minimum usage](#minimum-usage)\r\n - [Indirect action PID](#indirect-action-pid)\r\n - [Integral limitation](#integral-limitation)\r\n - [Limiting output](#limiting-output)\r\n - [Proportionnal on measurement](#proportionnal-on-measurement)\r\n - [Derivative on measurement](#derivative-on-measurement)\r\n - [Integral freezing](#integral-freezing)\r\n - [Deadband](#deadband)\r\n - [Setpoint ramp](#setpoint-ramp)\r\n - [Setpoint reached by the process value](#setpoint-reached-by-the-process-value)\r\n - [Process value stabilized indicator](#process-value-stabilized-indicator)\r\n - [Historian](#historian)\r\n - [Historian parameters list](#historian-parameters-list)\r\n - [Manual mode](#manual-mode)\r\n - [Logging](#logging)\r\n - [Time simulation](#time-simulation)\r\n - [Threaded PID](#threaded-pid)\r\n - [Simulation](#simulation)\r\n- [SetupTool](#setuptool)\r\n - [Usage](#usage-1)\r\n - [Read-only and read-write mode](#read-only-and-read-write-mode)\r\n - [Control on PID](#control-on-pid)\r\n\r\n## Installation\r\n```\r\npython3 -m pip install PID_Py\r\n```\r\n\r\n## Usage\r\n### Minimum usage\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 10.0, ki = 5.0, kd = 0.0)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\nIn this usage the PID as no limitation, no history and the PID is in direct action (Error increasing -> Increase output).\r\n\r\n### Indirect action PID\r\nIf you have a system that required to decrease command to increase feedback, you can use `indirectAction` parameters.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 10.0, ki = 5.0, kd = 0.0, indirectAction = True)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\n### Integral limitation\r\nThe integral part of the PID can be limit to avoid overshoot of the output when the error is too high (When the setpoint variation is too high, or when the system have trouble to reach setpoint).\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 10.0, ki = 5.0, kd = 0.0, integralLimit = 20.0)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\nIn the example above, the integral part of the PID is clamped between -20 and 20.\r\n\r\n### Limiting output\r\nIf your command must be limit you can use `outputLimits` parameters.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 10.0, ki = 5.0, kd = 0.0, outputLimits = (-20, 20))\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\nBy default the value is `(None, None)`, which implies that there is no limits. You can activate just the maximum limit with `(None, 100)`. The same for the minimum limit `(-100, None)`.\r\n\r\n### Proportionnal on measurement\r\nThis avoid a strong response of proportionnal part when the setpoint is suddenly changed. \r\n\r\nThis change the P equation as follow :\r\n- False : P = error * kp\r\n- True : P = -(processValue * kp)\r\n\r\nThis result in an augmentation of the stabilization time of the system, but there is no bump on the output when the setpoint change suddenly. There is no difference on the reponds to process disturbance.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 3.0, ki = 5.0, kd = 0.0, proportionnalOnMeasurement=True)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\n### Derivative on measurement\r\nThis avoid a strong response of derivate part when the setpoint is suddenly changed. \r\n\r\nThis change the D equation as follow :\r\n- False : D = ((error - lastError) / dt) * kd\r\n- True : D = -(((processValue - lastProcessValue) / dt) * kd)\r\n\r\nThe effect is there is no bump when the setpoint change suddenly, and there is no difference on the responds to process disturbance.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 10.0, ki = 5.0, kd = 0.2, derivativeOnMeasurement=True)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\n### Integral freezing\r\nWhen a known disturbance occur, the integral part can be freezed to avoid increasing of its value during the perturbance.\r\nFor example, in a oven. When temperature is stable, and the door is opened the temperature drops quickly. And when the door is closed again, the temperature will rise to the previous temperature. So integral part value don't need to be increased to reach temperature setpoint.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0)\r\n\r\n...\r\n\r\npid.integralFreezing = doorIsOpened\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\nIn the example above, the integral part value is freezed when the door is open. When the door is closed the integral part value resumes its calculation.\r\nThe door is opened between 5 and 7 second. For the example, the setpoint is increase during the freezing.\r\n\r\n### Deadband\r\nA deadband can be set, by default its deactivated. It can be activated by entering a value to `deadband`. When the error is between [-`deadband`, `deadband`] for `deadbandActivationTime` (in second) the integral is no longer calculated. If the error exceed `deadband` the integral part is recalculated.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, deadband=1.0, deadbandActivationTime = 10.0)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\nIn the example above, the PID behaves normally until the error is lower than 1 for 10 seconds. The integral part stops. Then when the error is higher than 1.0 the integral is recalculated.\r\n\r\n### Setpoint ramp\r\nThe setpoint variation can be limited with `setpointRamp` option.\r\nThis option allow to make a ramp with the setpoint when this one change.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, setpointRamp=10.0)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\n\r\n\r\nIn the example above, the setpoint has a maximal ramp of 10 units per second.\r\nIf the setpoint is change to 10 from 0, the real setpoint used will change for 1 second to 10.0.\r\nThe same behavior in negative, but with `-setpointRamp`.\r\n\r\n### Setpoint reached by the process value\r\nThe PID can return that the process value is stable on the setpoint. To configure it use `setpointStableLimit` to define the maximum difference between the process value and the setpoint (error) to considered the setpoint reached. And use `setpointStableTime` to define an amount of time to considered the setpoint reached\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, setpointStableLimit=0.1, setpointStableTime=1.0)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\nIn the example abose, the output `setpointReached` is set to `True` when the error is between -0.1 and +0.1 for 1.0 second. If the error exceed +/- 0.1, the output is reset.\r\n\r\n### Process value stabilized indicator\r\nThe PID can return that the process value is stabilized, to configure it use `processValueStableLimit` to define the maximum variation when the process value is stable, and `processValueStableTime` to define the amount of time when the variation is below the limit.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, processValueStableLimit=0.1, processValueStableTime=1.0)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\nIn the example above, the output `processValueStabilized` is set to `True` when the process value variation do not exceed +/- 0.1 unit/s for 1.0 second. If the process value variation exceed +/- 0.1 unit/s the output `processValueStabilized` is set to `False`.\r\n\r\n\r\n### Historian\r\nIf you want to historize PID values, you can configure the historian to record values.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\nfrom PID_Py.PID import HistorianParams\r\n\r\n# Initialization\r\nHistorianParams = HistorianParams.SETPOINT | HistorianParams.PROCESS_VALUE\r\npid = PID(kp = 10.0, ki = 5.0, kd = 0.0, HistorianParams = HistorianParams)\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n\r\n...\r\n\r\n# PID Historian\r\nimport matplotlib.pyplot as plt\r\n\r\nplt.plot(pid.historian[\"TIME\"], pid.historian[\"SETPOINT\"], label=\"Setpoint\")\r\n\r\nplt.plot(pid.historian[\"TIME\"], pid.historian[\"PROCESS_VALUE\"], label=\"Process value\")\r\n\r\nplt.legend()\r\nplt.show()\r\n```\r\nIn the example above, the PID historian records `setpoint`, `processValue`. `time` is also recorded when at least one parameter is recorded. Time is the elapsed time from the start. After that a graphic is draw with `matplotlib`.\r\n\r\n#### Historian parameters list\r\n- `P` : proportionnal part\r\n- `I` : integral part\r\n- `D` : derivative part\r\n- `ERROR` : PID error\r\n- `SETPOINT` : PID setpoint\r\n- `PROCESS_VALUE` : PID process value\r\n- `OUTPUT` : PID output\r\n\r\nThe maximum lenght of the historian can be choose. By default it is set to 100 000 record per parameter. Take care about your memory.\r\n\r\nIn example for one parameters. A `float` value take 24 bytes in memory. So `100 000` floats take `2 400 000` bytes (~2.3MB).\r\n\r\nFor all parameters it takes `16 800 000` bytes (~16MB).\r\nIt's not big for a computer, but if PID is executed each millisecond (0.001s), 100 000 record represent only 100 seconds of recording. \r\n\r\nIf you want to save 1 hour at 1 millisecond you will need 3 600 000 records (~82.4MB) for one parameter, and for all parameters it will takes ~576.8MB.\r\n\r\nFor a raspberry pi 3 B+ it's the half of the RAM capacity (1GB)\r\n\r\n\r\n### Manual mode\r\nThe PID can be switch in manual mode, this allow to operate output directly through `manualValue`.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0)\r\n\r\n...\r\n\r\n# Manual mode\r\npid.manualMode = True\r\npid.manualValue = 12.7\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\nIn the example above, command will be always equal to 12.7. The PID calculation is no longer executed. The integral part is keep equal to output minus proportionnal part, this allow a smooth switching to automatic.\r\n\r\nTo avoid bump when switching in manual there is `bumplessSwitching` attribute. This attributes keep `manualValue` equal to `output`. \r\n\r\nIf you disable this function you will have bump when you switch in manual mode with `manualValue` different of `output`. If this case you can **destabilise** (:heavy_exclamation_mark:) your system. Be careful\r\n\r\n### Logging\r\nThe PID can use a logger (logging.Logger built-in class) to log event. Logging configuration can be set outside of the PID.\r\nSee [logging.Logger](https://docs.python.org/3/library/logging.html#logger-objects) documentation.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\nimport logging\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, logger = logging.getLogger(\"PID\"))\r\n\r\n...\r\n\r\n# PID execution (call it as fast as you can)\r\ncommand = pid(setpoint = targetValue, processValue = feedback)\r\n```\r\n\r\nIn the example above, the PID will send event on the logger. The logger can also get with the name.\r\n\r\n```Python\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, logger = \"PID\")\r\n```\r\n\r\n### Time simulation\r\nThe time can be simulated by passing current time to the PID. This feature must not be used with a real application. It's only for simulation purpose.\r\nThis allows to view the PID reaction quickly.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\nimport numpy as np\r\n\r\n# Initialization\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0)\r\ntimeValues = np.arange(0, 20.0, 0.001)\r\n\r\n...\r\n\r\nfor t in timeValues:\r\n # PID execution (call it as fast as you can)\r\n command = pid(setpoint = targetValue, processValue = feedback, t = t)\r\n```\r\n\r\nIn the example above `timeValues` is a numpy array that contain [0.0, 0.001, 0.002, 0.003, ..., 19.999]. And with the for loop, we can calculate 20 seconds very quickly.\r\nAnd then use the historian to view the PID reaction.\r\n\r\n### Threaded PID\r\nWith the threaded PID you don't have to call `pid(processValue, setpoint)`. It's call as fast as possible or with a constant cycle time. When you want to stop the PID use `quit` attribute to finish the current execution and exit. \r\n\r\n```Python\r\nfrom PID_Py.PID import ThreadedPID\r\n\r\n# Initialization\r\npid = ThreadedPID(kp = 2.0, ki = 5.0, kd = 0.0, cycleTime = 0.01)\r\npid.start()\r\n\r\n...\r\n\r\n# PID inputs\r\npid.setpoint = targetValue\r\npid.processValue = feedback\r\n\r\n# PID output\r\ncommand = pid.output\r\n\r\n...\r\n\r\n# Stop PID\r\npid.quit = True\r\npid.join()\r\n```\r\n\r\nIn the example above the threaded PID is created with 10ms (0.01s) of cyclic time. It means that the calculation is executed each 10ms.\r\n\r\n### Simulation\r\nA simulation can be activate to simulate a real application.\r\n\r\n```Python\r\nfrom PID_Py.PID import PID\r\nfrom PID_Py.Simulation import Simulation\r\n\r\n# Initialization\r\nsimulation = Simulation(K = 1.0, tau = 0.1)\r\npid = PID(kp = 2.0, ki = 5.0, kd = 0.0, simulation=simulation)\r\n\r\n...\r\n\r\ncommand = pid(setpoint = targetValue)\r\n```\r\n\r\n## SetupTool\r\nSetupTool is a tool to help you to configure the PID's parameters.\r\nA trend with the historian values is displayed to show the PID behaviour.\r\n\r\n### Usage\r\nTo use SetupTool you need to import QApplication from PySide6.QtWidgets, then create an application and instantiate SetupTool.\r\n\r\nAfter the SetupTool is open, you can see real-time chart updated every second, and on the right all PID's parameters you can adjust in read-write mode.\r\n\r\nAfter having taken control on the setpoint, you can also send a new setpoint to the PID.\r\n\r\n```Python\r\n# PID imports\r\nfrom PID_Py.PID import PID, ThreadedPID, HistorianParams\r\nfrom PID_Py.SetupTool import SetupToolApp\r\nfrom PID_Py.Simulation import Simulation\r\n\r\n# PySide6 (PyQt) imports\r\nfrom PySide6.QtWidgets import QApplication\r\n\r\nimport sys\r\n\r\n# Threaded PID creation\r\npid = ThreadedPID(kp=1, ki=0, kd=0.0, \r\n cycleTime=0.01, \r\n historianParams=HistorianParams.SETPOINT | HistorianParams.PROCESS_VALUE, \r\n simulation=Simulation(1, 1))\r\npid.start()\r\n\r\n# PyQt application creation\r\napp = QApplication(sys.argv)\r\n\r\n# SetupTool instantiation\r\nsetupToolApp = SetupToolApp(pid)\r\nsetupToolApp.show()\r\n\r\n# Application execution\r\napp.exec()\r\n\r\n# Application ended, stop the PID\r\npid.quit = True\r\npid.join()\r\n```\r\n\r\nIn the example above, a threaded PId is created and gave to SetupTool constructor.\r\n\r\nIf have a not threaded PID, you can execute PyQt application in a parallel thread.\r\n\r\n### Read-only and read-write mode\r\nWhen SetupTool is instantiate the read-only mode is activated. This mode prevent any modification on the PID's parameters.\r\n\r\nIf you want to modify PID's parameters you need to switch on read-write mode. Then all parameters are unlocked.\r\n\r\n### Control on PID\r\nWhen SetulTool is instantiate, you don't have the control on the setpoint.\r\n\r\nIf you want to override setpoint, you need to take the control. Then the setpoint is unlocked. Write the new setpoint and then click on \"apply\".\r\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 ThunderTecke Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Simple (but complete) PID controller in Python",
"version": "1.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/ThunderTecke/PID_Py/issues",
"Change log": "https://github.com/ThunderTecke/PID_Py/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/ThunderTecke/PID_Py"
},
"split_keywords": [
"pid",
" controller",
" pid-controller",
" control",
" pid-control",
" python",
" raspberry",
" raspberrypi",
" raspberry-pi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2e4de7aa4189c4a226b5699c71d7f9bbdad4b44e4f448de165126bc17007fee4",
"md5": "fe4a26b6dcd849291be4736956098503",
"sha256": "9447072c6eb59850ef3fc2b2012d0ae62b19848f7a1c1b824bedc0865ea56bff"
},
"downloads": -1,
"filename": "PID_Py-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe4a26b6dcd849291be4736956098503",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19725,
"upload_time": "2024-05-28T00:00:41",
"upload_time_iso_8601": "2024-05-28T00:00:41.040233Z",
"url": "https://files.pythonhosted.org/packages/2e/4d/e7aa4189c4a226b5699c71d7f9bbdad4b44e4f448de165126bc17007fee4/PID_Py-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aec825f2fa34ec187d4ffef5a691ccc325e5ce17290e4ac500689f6d589b9c03",
"md5": "5bb35eb7fafb9e7646c91ba7e8908084",
"sha256": "56bbd3f89de85ff403ac449742cbf7907ffdd4936005e0f7e3de058037bc6614"
},
"downloads": -1,
"filename": "pid_py-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "5bb35eb7fafb9e7646c91ba7e8908084",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19607,
"upload_time": "2024-05-28T00:00:42",
"upload_time_iso_8601": "2024-05-28T00:00:42.804747Z",
"url": "https://files.pythonhosted.org/packages/ae/c8/25f2fa34ec187d4ffef5a691ccc325e5ce17290e4ac500689f6d589b9c03/pid_py-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-28 00:00:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ThunderTecke",
"github_project": "PID_Py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pid-py"
}
