upd

GyverLibs · GyverLibs · commit 7000d6a97eba · 2025-06-15T18:17:42.000+03:00
diff --git a/README.md b/README.md
@@ -1,2 +1,201 @@
+[![latest](https://img.shields.io/github/v/release/GyverLibs/uPID.svg?color=brightgreen)](https://github.com/GyverLibs/uPID/releases/latest/download/uPID.zip)
+[![PIO](https://badges.registry.platformio.org/packages/gyverlibs/library/uPID.svg)](https://registry.platformio.org/libraries/gyverlibs/uPID)
+[![Foo](https://img.shields.io/badge/Website-AlexGyver.ru-blue.svg?style=flat-square)](https://alexgyver.ru/)
+[![Foo](https://img.shields.io/badge/%E2%82%BD%24%E2%82%AC%20%D0%9F%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D1%82%D1%8C-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B0-orange.svg?style=flat-square)](https://alexgyver.ru/support_alex/)
+[![Foo](https://img.shields.io/badge/README-ENGLISH-blueviolet.svg?style=flat-square)](https://github-com.translate.goog/GyverLibs/uPID?_x_tr_sl=ru&_x_tr_tl=en)  
+
+[![Foo](https://img.shields.io/badge/ПОДПИСАТЬСЯ-НА%20ОБНОВЛЕНИЯ-brightgreen.svg?style=social&logo=telegram&color=blue)](https://t.me/GyverLibs)
+
 # uPID
 Лёгкая универсальная библиотека ПИД-регулятора с опциональными надстройками над алгоритмом
+- Ограничение выхода
+- Выбор направления регулирования
+- Пропорционально ошибке или изменению входа
+- Дифференциально ошибке или входу
+- Интегральная составляющая:
+  - Ограничение интеграла Back Calculation
+  - Ограничение интегрирования по насыщению выхода
+  - Сброс интеграла при достижении уставки
+
+### Совместимость
+Совместима со всеми платформами
+
+## Содержание
+- [Использование](#usage)
+- [Версии](#versions)
+- [Установка](#install)
+- [Баги и обратная связь](#feedback)
+
+<a id="usage"></a>
+
+## Использование
+### uPID
+Стандартный класс. Режимы можно менять во время работы программы, коэффициенты можно писать и читать напрямую в переменные `Kp`, `Ki`, `Kd`.
+
+```cpp
+uPID(uint8_t cfg = 0, uint16_t dt = 30);
+
+float Kp = 0, Ki = 0, Kd = 0;
+float Kbc = 0;
+float setpoint = 0;
+float integral = 0;
+float outMax = 255;
+float outMin = 0;
+
+float getKp();
+float getKi();
+float getKd();
+
+void setKp(float p);
+void setKi(float i);
+void setKd(float d);
+
+// установить конфиг
+void setConfig(uint8_t ncfg);
+
+// включить флаг
+void setMode(uPID_cfg mode);
+
+// выключить флаг
+void clearMode(uPID_cfg mode);
+
+// установить период работы в мс
+void setDt(uint16_t ms);
+
+// вычислить (вызывать с заданным периодом). Вернёт выход
+float compute(float input);
+```
+
+### uPIDfast
+Быстрая и лёгкая версия: режим задаётся в шаблоне на этапе компиляции, а коэффициенты можно менять только через set-get. Эта версия на 20 мкс быстрее считается - 67 против 87 мкс (AVR 16 MHz, стандартные настройки).
+
+```cpp
+uPIDfast<uint8_t cfg = 0>(uint16_t dt = 30);
+
+float Kbc = 0;
+float setpoint = 0;
+float integral = 0;
+float outMax = 255;
+float outMin = 0;
+
+float getKp();
+float getKi();
+float getKd();
+
+void setKp(float p);
+void setKi(float i);
+void setKd(float d);
+
+// установить период работы в мс
+void setDt(uint16_t ms);
+
+// вычислить (вызывать с заданным периодом). Вернёт выход
+float compute(float input);
+```
+
+### Настройка
+Режим работы регулятора строится из констант, разделённых `|`, например:
+
+```cpp
+uPID pid(D_INPUT | P_MEASURE | PID_REVERSE);
+pid.setConfig(D_INPUT | P_MEASURE);
+pid.clearMode(P_MEASURE);
+
+uPIDfast<D_INPUT | P_MEASURE | PID_REVERSE> pidfast;
+```
+
+### Пропорциональная
+Один вариант из двух:
+
+- `P_ERROR` (по умолчанию) - пропорционально ошибке. Классический вариант П-составляющей
+- `P_MEASURE` - пропорционально входу (зависит от `D_INPUT`) или ошибке (зависит от `D_ERROR`). Меняет логику работы регулятора, хорошо подходит для интегрирующих процессов - например регулятор управляет скоростью (сигналом на мотор), а на вход подаётся позиция (энкодер на этом моторе)
+
+### Интегральная
+Можно выбирать в любом сочетании, но `I_BACK_CALC` является аналогом `I_SATURATE` и включать их вместе не имеет смысла:
+
+- `I_SATURATE` - *Conditional Integration*, отключение интегрирования при насыщении выхода
+- `I_BACK_CALC` - *Back Calculation*, умное ограничение интегрирования при насыщении выхода. Работает медленнее, чем `I_SATURATE`. Интенсивность регулируется коэф-м `Kbc` - для начала нужно выбрать его равным `Ki`, далее менять и смотреть за реакцией системы
+- `I_RESET` - автоматический сброс интеграла при достижении уставки
+
+> Под "насыщением выхода" имеется в виду его уход из диапазона `(outMin.. outMax)`, в этом случае в обычном ПИДе интегральная сумма начинает бесконтрольно расти в одну сторону и потом долго возвращается обратно - т.н. *windup*. Библиотека предлагает несколько вариантов решения этой проблемы
+
+### Дифференциальная
+Один вариант из двух:
+
+- `D_ERROR` (по умолчанию) - дифференцирование ошибки. Классический вариант Д-составляющей
+- `D_INPUT` - дифференцирование входа. Меньшее влияние шума, полное отсутствие заброса по Д при изменении уставки. Если уставка часто меняется и нужно более динамичное поведение системы в ответ на это - лучше использовать `D_ERROR`
+
+### Направление
+Один вариант из двух:
+
+- `PID_FORWARD` (по умолчанию) - прямой регулятор, выход регулятора должен увеличивать вход (например управление мощностью нагрева, температура на вход регулятора)
+- `PID_REVERSE` - обратный регулятор, выход регулятора должен уменьшать вход (например управление мощностью охлаждения, температура на вход регулятора)
+
+### Примеры
+```cpp
+#include <uPID.h>
+
+const int dt = 30;
+uPID pid(D_INPUT | I_SATURATE);
+// uPIDfast<D_INPUT | I_SATURATE> pid;
+
+void setup() {
+  // pid.Kp = 10;
+  // pid.Ki = 20;
+  // pid.Kd = 5;
+
+  pid.setKp(10);
+  pid.setKi(20);
+  pid.setKd(5);
+
+  // pid.Kbc = 0.1;
+  pid.setDt(dt);
+  pid.outMax = 255;
+  pid.outMin = -255;
+
+  pid.setpoint = уставка;
+}
+
+void loop() {
+  float result = pid.compute(показания_датчика);
+  применить(result);
+  delay(dt);
+}
+```
+
+<a id="versions"></a>
+
+## Версии
+- v1.0
+
+<a id="install"></a>
+## Установка
+- Библиотеку можно найти по названию **uPID** и установить через менеджер библиотек в:
+    - Arduino IDE
+    - Arduino IDE v2
+    - PlatformIO
+- [Скачать библиотеку](https://github.com/GyverLibs/uPID/archive/refs/heads/main.zip) .zip архивом для ручной установки:
+    - Распаковать и положить в *C:\Program Files (x86)\Arduino\libraries* (Windows x64)
+    - Распаковать и положить в *C:\Program Files\Arduino\libraries* (Windows x32)
+    - Распаковать и положить в *Документы/Arduino/libraries/*
+    - (Arduino IDE) автоматическая установка из .zip: *Скетч/Подключить библиотеку/Добавить .ZIP библиотеку…* и указать скачанный архив
+- Читай более подробную инструкцию по установке библиотек [здесь](https://alexgyver.ru/arduino-first/#%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0_%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA)
+### Обновление
+- Рекомендую всегда обновлять библиотеку: в новых версиях исправляются ошибки и баги, а также проводится оптимизация и добавляются новые фичи
+- Через менеджер библиотек IDE: найти библиотеку как при установке и нажать "Обновить"
+- Вручную: **удалить папку со старой версией**, а затем положить на её место новую. "Замену" делать нельзя: иногда в новых версиях удаляются файлы, которые останутся при замене и могут привести к ошибкам!
+
+<a id="feedback"></a>
+
+## Баги и обратная связь
+При нахождении багов создавайте **Issue**, а лучше сразу пишите на почту [alex@alexgyver.ru](mailto:alex@alexgyver.ru)  
+Библиотека открыта для доработки и ваших **Pull Request**'ов!
+
+При сообщении о багах или некорректной работе библиотеки нужно обязательно указывать:
+- Версия библиотеки
+- Какой используется МК
+- Версия SDK (для ESP)
+- Версия Arduino IDE
+- Корректно ли работают ли встроенные примеры, в которых используются функции и конструкции, приводящие к багу в вашем коде
+- Какой код загружался, какая работа от него ожидалась и как он работает в реальности
+- В идеале приложить минимальный код, в котором наблюдается баг. Не полотно из тысячи строк, а минимальный код
diff --git a/keywords.txt b/keywords.txt
@@ -0,0 +1,31 @@
+#######################################
+# Syntax Coloring Map For uPID
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+uPID	KEYWORD1
+uPIDfast	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+
+setDt	KEYWORD2
+compute	KEYWORD2
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+
+P_ERROR	LITERAL1
+P_MEASURE	LITERAL1
+I_BACK_CALC	LITERAL1
+I_SATURATE	LITERAL1
+I_RESET	LITERAL1
+D_INPUT	LITERAL1
+D_ERROR	LITERAL1
+PID_FORWARD	LITERAL1
+PID_REVERSE	LITERAL1
diff --git a/library.properties b/library.properties
@@ -0,0 +1,9 @@
+name=uPID
+version=1.0.0
+author=AlexGyver <alex@alexgyver.ru>
+maintainer=AlexGyver <alex@alexgyver.ru>
+sentence=Light and universal PID implementation
+paragraph=Light and universal PID implementation
+category=Data Processing
+url=https://github.com/GyverLibs/uPID
+architectures=*
diff --git a/uPID.h b/uPID.h
