From 5c2ee41fa2b323023e95e45282af1554abe93e84 Mon Sep 17 00:00:00 2001 From: Hays Chan <25737801+hayschan@users.noreply.github.com> Date: Sat, 25 May 2024 17:21:45 +0800 Subject: [PATCH] docs: Add link to AutoPID library in README.md --- README.md | 97 ++++++++++++++++--------------------------------------- 1 file changed, 27 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 4a88d68..d801426 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AutoPID-for-ESP-IDF -AutoPID-for-ESP-IDF is a PID controller library adapted from the AutoPID library designed for Arduino, now compatible with the ESP-IDF (Espressif IoT Development Framework) environment. This library provides an easy way to implement PID control in your ESP32 projects, offering flexibility and precision for various control systems. +AutoPID-for-ESP-IDF is a PID controller library adapted from the [AutoPID](https://github.com/r-downing/AutoPID) library designed for Arduino, now compatible with the ESP-IDF (Espressif IoT Development Framework) environment. This library provides an easy way to implement PID control in your ESP32 projects, offering flexibility and precision for various control systems. ## Features @@ -12,94 +12,51 @@ AutoPID-for-ESP-IDF is a PID controller library adapted from the AutoPID library - **Time Step Configuration**: Customizable PID update interval for better control over processing cycles. - **Relay Control**: Includes a relay control extension for on/off switching applications. -## Capabilities +### Time-scaling and Automatic Value Updating +The PID controller’s run() function can be called as often as possible in the main loop, and will automatically only perform the updated calculations at a specified time-interval. The calculations take the length of this time-interval into account, so the interval can be adjusted without needing to recaculate the PID gains. -- **Temperature Control**: Perfect for maintaining a setpoint temperature using sensors and heaters/coolers. -- **Motor Speed Control**: Ideal for controlling the speed of DC motors in various applications. -- **Light Intensity Control**: Can be used to maintain desired light levels with sensors and dimmers. -- **General Process Control**: Suitable for any application requiring precise control over a process variable. +Since the PID object stores pointers to the input, setpoint, and output, it can automatically update those variables without extra assignment statements. + +### Bang-Bang Control +This library includes optional built-in bang-bang control. When the input is outside of a specified range from the setpoint, the PID control is deactivated, and the output is instead driven to max (bang-on) or min (bang-off). + +This can help approach the setpoint faster, and reduce overshooting due to integrator wind-up. + +### PWM (Relay) Control +Since the output of a PID control is an analog value, this can be adapted to control an on-off digital output (such as a relay) using pulse-width modulation. ## Getting Started ### Prerequisites -- **ESP-IDF**: Ensure you have the ESP-IDF installed and set up. Follow the official [ESP-IDF Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for instructions. -- **Hardware**: ESP32 development board, sensors (e.g., temperature sensor), and actuators (e.g., heaters, motors). +- ESP-IDF: Ensure you have the ESP-IDF installed and set up. Follow the official [ESP-IDF Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for instructions. +- Hardware: ESP32 development board, sensors (e.g., temperature sensor), and actuators (e.g., heaters, motors). ### Installation -1. **Clone the Repository**: +#### Using ESP Component Registry (Recommended) + +Head to the ESP component registry for [AutoPID-for-ESP-IDF](https://components.espressif.com/components/hayschan/AutoPID-for-ESP-IDF/) and follow the instructions to add the library to your project. + +#### Using Git (Manual Installation) + +1. Clone the Repository: ```sh - git clone https://github.com/your-username/AutoPID-for-ESP-IDF.git + git clone https://github.com/hayschan/AutoPID-for-ESP-IDF.git cd AutoPID-for-ESP-IDF ``` -2. **Directory Structure**: - Ensure the directory structure looks like this: - ``` - AutoPID-for-ESP-IDF - ├── CMakeLists.txt - ├── Kconfig - ├── include - │ └── AutoPID.h - ├── src - │ └── AutoPID.cpp - └── idf_component.yml - ``` - -3. **Add to Your ESP-IDF Project**: +2. Add to Your ESP-IDF Project: - Add the `AutoPID-for-ESP-IDF` directory to the `components` directory of your ESP-IDF project. - - Modify your project's `CMakeLists.txt` to include the AutoPID component: - ```cmake - list(APPEND EXTRA_COMPONENT_DIRS "path/to/AutoPID-for-ESP-IDF") - ``` + - Modify your project's `CMakeLists.txt` to include the AutoPID component ### Usage -1. **Include the Library**: - ```cpp - #include "AutoPID.h" - ``` - -2. **Initialize and Configure AutoPID**: - ```cpp - double temperature, setPoint, outputVal; - AutoPID myPID(&temperature, &setPoint, &outputVal, OUTPUT_MIN, OUTPUT_MAX, KP, KI, KD); - myPID.setBangBang(4); - myPID.setTimeStep(4000); - ``` - -3. **Main Application Loop**: - ```cpp - void app_main() { - init_adc(); - init_dac(); - init_gpio(); - - temperatureSensors.begin(); - temperatureSensors.requestTemperatures(); - while (!updateTemperature()) { - vTaskDelay(pdMS_TO_TICKS(100)); // Wait until temp sensor updated - } - - while (true) { - updateTemperature(); - setPoint = read_potentiometer(); - myPID.run(); // Call every loop, updates automatically at certain time interval - write_dac(outputVal); - gpio_set_level(LED_PIN, myPID.atSetPoint(1)); // Light up LED when we're at setpoint +-1 degree - vTaskDelay(pdMS_TO_TICKS(100)); // Delay for a short period - } - } - ``` - -### Example Project - An example project demonstrating the use of AutoPID for temperature control can be found in the `examples` directory. The example uses a temperature sensor, potentiometer, and DAC output to maintain a setpoint temperature. -### Contributing - -Contributions are welcome! Please fork the repository, make your changes, and submit a pull request. Ensure your code follows the project's coding standards and includes relevant tests. +Two examples are provided: +- Basic Example: Demonstrates the basic usage of the AutoPID library for temperature control. +- Temperature Control with Relay: Demonstrates the use of the AutoPID library with relay control for on/off temperature control. ### License