mcm4iob / iobroker.pid

Configurable PID Controller for ioBroker

ioBroker.pid

Version:

Tests:

Sentry

This adapter uses Sentry libraries to automatically report exceptions and code errors to the developers. For more details and for information how to disable the error reporting see Sentry-Plugin Documentation! Sentry reporting is used starting with js-controller 3.0.

PID Adapter for ioBroker

This adapter provides a configurable PID Controller.

General Information

This adapter provides the functionality of a PID controller.

In practical terms, a PID controller automatically calculates a correction value for a system based on an actual value and a setpoint. The behavior is controller by parameters. An everyday example is the cruise control on a car, where ascending a hill would lower speed if constant engine power were applied. The controller's PID algorithm restores the measured speed to the desired speed with minimal delay and overshoot by increasing the power output of the engine in a controlled manner. [(c) Wikipedia]

Within one adapter instance there could be more than one controller configured. The adpter supports configuring the paramaters (P, I, D components) and the cycle time used for calculation. In addition caclulation can be suspended and resumed and the controlelr can be reset at all. As convinient server a manual mode can be switches on to directly set the output. Output can be limited to a minimum/maximum value and contain a fixes offset.

All relevant values including internal data are availbale as states for diagnose purposes.

Documentation

english documentation
deutsche Dokumentation

Credits

Providing this adapter would not have been possible without the great work of @Philmod (https://github.com/Philmod) who developed node-pid-controller (https://github.com/Philmod/node-pid-controller).

How to report issues and feature requests

Please use GitHub issues for this.

Best is to set the adapter to Debug log mode (Instances -> Expert mode -> Column Log level). Then please get the logfile from disk (subdirectory "log" in ioBroker installation directory and not from Admin because Admin cuts the lines). If you do not like providing it in GitHub issue you can also send it to me via email ([email protected]). Please add a reference to the relevant GitHub issue AND also describe what I see in the log at which time. "title": "lblCtrlInvert",

Changelog

1.1.3 (2024-03-22)

• (mcm1957) Adapter uses sentry to report errors now.

1.0.0 (2024-03-11)

• (mcm1957) BREAKING: Adapter requires node.js 18 or newer now
• (mcm1957) BREAKING: Adapter requires js-controller 5.x.x and admin 6.x.x or newer now
• (mcm1957) BREAKING: Adapter requires node.js 18 or newer now
• (mcm1957) Incorrect error message whenever no controllers have been defied has been removed. [#68]
• (mcm1957) State roles have been reviewed and adapted. [#88]
• (mcm1957) Dependencies have been updated.

0.0.8 (2023-07-13)

• (mcm1957) changed: Overall stability during state updates has been increased
• (mcm1957) changed: Dependencies have been updated

0.0.7 (2023-04-24)

• (mcm1957) changed: Cycle time is now required to be at least 100ms
• (mcm1957) changed: Recalculations are now controlled by cycle timer only, no extra updates are performed (#62)
• (mcm1957) changed: Several dependencies have been updated

0.0.6 (2023-04-14)

• (mcm1957) solved: Calculation of sumerr in case of hitting max/min Limits has been corrected

0.0.5 (2023-04-14)

• (mcm1957) new: npm/npmjs support has been added

0.0.4 (2023-04-14)

• (mcm1957) changed: State last_upd_str has been removed
• (mcm1957) changed: Some roles have been updated
• (mcm1957) changed: Translations have been updated

0.0.3-alpha.1 (2023-04-13)

• (mcm1957) changed: Setting rst state does no longer trigger a recalculation
• (mcm1957) changed: State diff now displays error value even if sup is active
• (mcm1957) changed: Calculation of I-part has been changed, changing Tn effects future calculations only now

0.0.3-alpha.0 (2023-04-12)

• (mcm1957) new: optionally use folder structure for states
• (mcm1957) changed: reset timer at restart after pausing calculation
• (mcm1957) changed: use values stored for ack and set when starting adapter
• (mcm1957) changed: log state changes with unexpected ack=true
• (mcm1957) changed: fix incorrect updates occuring whenever act is written
• (mcm1957) changed: fix invert flag not working at all
• (mcm1957) changed: remove error display whenever adapter is hitting the limits
• (mcm1957) changed: fix q flag handling
• (mcm1957) changed: fix unexpected bahavior of sup parameter
• (mcm1957) changed: rename run state to hold

0.0.2-alpha.2 (2023-04-06)

• (mcm1957) changed: values of 'kp', 'xp' and 'sup' are now verified if set using states
• (mcm1957) changed: values of 'min' and 'max' are now verified if set using states
• (mcm1957) changed: activation of 'man' updates output 'y' with current value of 'man_inp' now
• (mcm1957) changed: 'min' value is now conserved when restarting the instance
• (mcm1957) changed: conversion between and xp has been fixed at several places
• (mcm1957) changed: 'kp' or 'xp' are writepotected now depending on 'useXp' parameter

0.0.2-alpha.1 (2023-04-04)

• (mcm1957) changed: some small fixes

0.0.2-alpha.0 (2023-04-04)

• (mcm1957) THIS IS AN ALPHA RELEASE ONLY
• (mcm1957) major changes after discussion in forum
• (mcm1957) new initial release

License

MIT License

Copyright (c) 2023-2024 mcm1957 [email protected]

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.

iobroker.pid's Issues

[BUG] Regler fängt nicht an, ohne auf den set zu schreiben

Ich starte den Regler neu und y wird erst geschrieben, wenn set einmal geschrieben wird.

[DOCU] fix badges at README.md

[BUG] updates occure more often than cycle time specifies

die Regler zykluszeit änderungen haben bei mir keinen Einfluss.
Ich habe gerade die Zykluszeit einmal auf 10000ms gestellt.
Der Ist wert kommt natürlich trotzdem alle 2000ms rein (in meinem Fall jetzt).
der Regler aktualisiert sich dann im 2000ms zyklus.

0.0.2-alpha.2

[QA] activate sentry

activate sentry once a key is provided
-) adapt io-package.json
-) adapt test-and-release.yml

[BUG] q flags inappropiate set

The q flags are set at states where they are not appropiate, i.e.

• act should not be set to offline if adapter is stopped

• man / man_inp should not be set to offline if adapter is stopped

• review handling of all states in respect to q flag

[Feature] use folder structure

(Optionally ?) use a folder structure to store states.

[Docu] finalize Documentation

Documentation must be finalized and translated to german once paramters are final.

[QA] log ack=true writes

Check writes to states with ack=true.
If this is an input only state log a warning if value is ignored.
If this is an i/o state update state to (old) value as soon as possible

[FEATURE] Evaluate I controller mode

Evaluate additional mode "I" only, i.e. by handling kp/xp == 0 specially

[BUG ?] Errors logged during shutdown

Errors have been loggeed during shutdown

Release 0.0.7
cycle time 1000ms
shutdown triggered by paramater change

pid.0 | 2023-04-24 12:28:30.482 | error | DB closed
pid.0 | 2023-04-24 12:28:30.481 | error | Error: DB closed at Redis.sendCommand (/opt/iobroker/node_modules/ioredis/built/redis/index.js:636:24) at Redis.get (/opt/iobroker/node_modules/ioredis/built/commander.js:122:25) at StateRedisClient.setState (/opt/iobroker/node_modules/@iobroker/db-states-redis/lib/states/statesInRedisClient.js:657:40) at Pid.setState (/opt/iobroker/node_modules/@iobroker/js-controller-adapter/build/lib/adapter/adapter.js:5886:35)
pid.0 | 2023-04-24 12:28:30.477 | error | unhandled promise rejection: DB closed
pid.0 | 2023-04-24 12:28:30.476 | error | Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().
pid.0 | 2023-04-24 12:28:30.472 | warn | get state error: Connection is closed.
host.pi4 | 2023-04-24 12:28:29.939 | info | stopInstance system.adapter.pid.0 send kill signal
pid.0 | 2023-04-24 12:28:29.898 | info | Terminated (ADAPTER_REQUESTED_TERMINATION): Without reason
pid.0 | 2023-04-24 12:28:29.897 | info | terminating
pid.0 | 2023-04-24 12:28:29.894 | info | Got terminate signal TERMINATE_YOURSELF
host.pi4 | 2023-04-24 12:28:29.886 | info | stopInstance system.adapter.pid.0 (force=false, process=true)
pid.0 | 2023-04-24 12:27:33.387 | info | processing started for 1 controller(s)

[QA] incorrect error message if no controller configured

After installing pid controller no contrioller is configured. There shoudl be some error message related to the fact that a controlelr must be added instead of the current message stating that the controller id is incorrect:

Release 0.0.7

Update stable version in repo from 0.0.0 to 0.0.8

Think about adding version 0.0.8 to stable repository.

Version: stable=0.0.0 (0 days old) => latest=0.0.8 (67 days old)
Installs: stable=0 (0%), latest=29 (69.05%), total=42
Click to edit

[QA] Parameters of setXxx functions should be checked

pid Module should check the paramaters for i.e. tn, tv, kp, xp, ... to be vslid numbers and ignore (and log) invalid input.

[BUG] columns not always visible (too small)

Columns are to small for data to be visible.

https://forum.iobroker.net/topic/64250/test-neuer-adapter-pid-pid-regler-v0-0-1-alpha-x/96

Configuration offset is ignored

Der Offset aus der Konfiguration wird nicht in para.off übernommen, sondern ein vorhandener Wert wird bei Instanz-Start mit 0 überschrieben.

[TESTING] add node 18

Extend testing to include node 18

Parameter sup does not work as expected

sup funktioniert irgendwie nur bei Instanzstart, wird sup dann verändert, verliert es seine Funktion und der Regler arbeitet weiter, auch wenn der Betrag der Abweichung< sup ist.

0.0.2-alpha.2

https://forum.iobroker.net/topic/64250/test-neuer-adapter-pid-pid-regler-v0-0-1-alpha-x/79?_=1680809532027

Update stable version in repo from 0.0.0 to 1.1.3

Think about adding version 1.1.3 to stable repository.

Version: stable=0.0.0 (0 days old) => latest=1.1.3 (30 days old)
Installs: stable=0 (0%), latest=35 (36.08%), total=97

Click to use developer portal
Click to edit

Do not close this issue manually as a new issue will be created if condition for update still exists.

Please drop a comment if any reason exists which blocks updating to version 1.1.3 at this time.

Note: This is an automatically generated message and not personally authored by bluefox!
@mcm1957 for evidence

[Feature] remove red exclamation sign if controller has limits exceeded

Im LIM is active no read exclamation sign should be visible.

Open Tasks for v0.0.1

• manual mode missing

• check io-package and remove/add config parameters

• check io-package and check states

• check controller id to be unique

• check controller id for valid characters

• README.md add information

• write documentation (en, de)

[QA] check adaptions for new roles

New roles have been accepted.
Check whether adaptsion should be done

[BUG] output jumps after hold / man

When resuming operation after pausing a controller ths output might perform big jumps even if act and set have not been chaged at all.

Reason seems to be that calculation of the integral part is not suspended during the time the controller is on-hold.

The same error occures when using manual mode.

Feature / Change Requests für V0.0.1

• all Parameters (P, I, D, MIN, MAX) should be controllable using states.
• reset should reset I store (sumErr) only
• sumErr and diffErr should not be compted if I/D Term is disabled. null should be returnd in this case.

Invertieren des Reglerausgangs sollte beschreibbar sein

Hallo mal wieder, ich habe den nächsten Einsatz für den Regler: Wärme-/ Kälterückgewinnung über die Drehzahl der Wärmeräder in der Lüftung. Dazu muss ich den inv mit true oder false aus einem Skript beschreiben können, das geht aktuell nicht. Alternativ könnte ich kp auf einen negativen Wert setzen, der Adapter lässt aber nur positive Werte zu. Bei tn, tv, xp lassen sich negative Werte setzen.

Hintergrund: wenn die Außenluft kälter ist, als die Raumluft, kann ich über die Erhöhung der Drehzahl die Zuluft mit der Abluft erwärmen. Im Sommer ist die Außenluft wärmer, als die Raumluft, d.h. ich kann über die Erhöhung der Drehzahl die Zuluft mit der Abluft kühlen. D.h. wenn Temperatur Außenluft < Raumluft, dann inv = 0 und wenn Temperatur Außenluft > Raumluft, dann inv = 1 . Kannst du inv beschreibbar machen? Dann kannst du auch bei tn, tv, xp nur pos. Werte zulassen.

Danke vorab!

Buglist 0.0.2-alpha.x

• Kp kann in den Objekten auch negativ angegeben werden
• wird "man" aktiviert, bleibt der Reglerausgang stehen, es wird nicht "man_inp" auf den Ausgang geschrieben
• aktiviert man "man" ermittelt der Regler im Hintergrund weiter einen neuen Wert für "y", auf den der Regler dann springt, sobald man "man" wieder deaktiviert
• beim pausieren des Reglers über "run" = "false" passiert das gleiche, wie bei "man" = "true"
• Bei Neustart der Adapter-Instanz bleibt das eingestellte "max" erhalten, während "min" auf 0 gesetzt wird, auch "off" wird genullt.
• Wenn man Kp eingibt, wird ein Xp berechnet (unter Berücksichtigung von min und max) und angezeigt. Wenn man Xp eingibt, wird das entsprechende Kp dazu berechnet und der Regler macht einen Sprung basierend auf dem neuen Kp, auch wenn "UseXp" "false" ist.
• Xp wird nur bei Änderung von Kp ermittelt, wird nur min oder max verändert, wird Xp nicht automatisch neu ermittelt, erst wenn man Kp noch mal bestätigt.
• Aktuell wird aber bei MaxOut von 100 und MinOut von 0 bei einem Xp von 100 ein Kp von 10000 berechnet. Hier hätte ich ein Kp von 1 erwartet (100-0)/100.

[BUG] Changing parameters causes extra calculation

Whenever new parameters are set the cycle time is aborted and an extra calculation is performed.
https://forum.iobroker.net/topic/64250/test-neuer-adapter-pid-pid-regler-v0-0-x/224

Release 0.0.6

[BUG] Typos in gui

• bei dao ist noch ein Schreibfehler: deriative act only (v fehlt)
• bei lim: contoller mit zwei "l"

0.0.2-alpha.2

Update stable version in repo from 0.0.0 to 0.0.8

Think about adding version 0.0.8 to stable repository.

Version: stable=0.0.0 (0 days old) => latest=0.0.8 (67 days old)
Installs: stable=0 (0%), latest=29 (69.05%), total=42

Click to use developer portal
Click to edit

Note: This is an automatically generated message and not personally authored by bluefox!

[Feature] remove outdated states

States belonging to controller-ids which do no longer exist should be removed at startup.

This does NOT apply to controlers only disabled.

Übersetzungen

I-Anteil wird als "ich schätze" angezeigt
"ermöglicht" sollte wohl eher "aktiviert" heißen

[QA] verify uniqueness of controller-id

The controller-id should be verified to be unique within adapter startup code

[BUG] RST should NOT trigger reculculation

Activating RST should not result in reculculation if the adapter is not running or is running at fixed intervals.
Otehrwise unexpected integral calculations are calculated.

Eventually other states cause this incorrect recalculation too - to be checked.

[BUG] Incorrect infotext for Xp mode

Infotext for xp Mode states using Kp instead of Xp (at least when using german language)

[FEATURE] State diff should always contain difference

The state DIFF should contain the true difference even if supression is active.
Suppression is marke using state supr anyway.

Invertieren ohne Funktion

Sobald man in den Einstellungen auf "Invertieren" drück, bekommt man keine Ausgabe mehr.

[BUG] descriptive text for state supr missing

The descriptive text for state supr missing

[FEATURE] Evaluate change in I part calculation

https://forum.iobroker.net/topic/64250/test-neuer-adapter-pid-pid-regler-v0-0-3-alpha-x/169

Changing the paramater Tn of a running system results in a jump of y.

It should be evaluated whether ist would be besster to integrate the wighted factor so that no jump is visible.

INT(diff) / Tn change to INT(diff/Tn) should do the magic

[BUG] Invert does not work

The invert flag does not work as expected.

[BUG] handling of run state causes warnings

warn: pid.0 (15601) Read-only state "pid.0.C-1.xtra.run" has been written without ack-flag with value "false"

Update stable version in repo from 0.0.0 to 0.0.8

Think about adding version 0.0.8 to stable repository.

Version: stable=0.0.0 (0 days old) => latest=0.0.8 (39 days old)
Installs: stable=0 (0%), latest=16 (44.44%), total=36
Click to edit

[QA] last_upd / last_upd_str states

a) last_upd should get role date. This should reult in admin to show a textual date/time
b) IF a) works, state last_upd_str should be removed as it is obsolete

[BUG] states written with ack=true are not reset

If some state is written with ack=tru the change is ignored and a warning is logged. But the state value is not reset to the correct value in use.

[Feature] link input / output to other states

Add a possibility to get input datat ('act') directly from another state.

Consider adding the some for output.

Optionally add offset / factor to those links to allow some scaling of values.

[Feature]: Ideen / Diskussion

Hallo, echt stark, dass du da dran gehst! Mit dem PID von Philmod habe ich auch schon rumgespielt, da fehlt mir aber die Stellwert-Begrenzung, es kann nur der I-Anteil limitiert werden (Anti-Wind-Up).

Nachdem ich jetzt mit dem npm PI-Controller Erfahrung gesammelt habe und meine berufliche Heimat die Prozessleittechnik ist, würde ich hier gerne ein paar Ideen einfließen lassen - für die Punkte unten wäre jeweils ein Objekt hilfreich, das auch dynamisch aus einem anderen Skript oder vis verändert werden kann:

1. Parametrierbares Totband: Der Betrag der Regelabweichung w-x muss mindestens so groß sein, dass der Regler die Stellgröße neu berechnet. Z.B.: Raumsollwert = 20°, Totzone: 0.5° => sind 19.5° erreicht, bleibt der Regler stehen, die Stellgröße für's Heizen hält den letzten Wert. Überschreitet dann die Raumtemperatur z.B. durch Sonneneinstrahlung die 20.5°, wird die Stellgröße vom Regler neu berechnet. Beim PI-Controller habe ich das mit Javascript aktuell so gelöst:

if (Math.abs(w - x) < 0.2 { // Regelabweichung mindestens 0.2°, um neuen Stellwert zu berechnen = Totband
        var y = pi.Control(0); // Stellwert nicht verändern
}

2. Bool-Eingang, um die Stellgröße temporär unverändert zu lassen/ den Regler zu pausieren, z.B. bei einer Sprungantwort. Das ist z.B. ein Thema beim PV-Überschussladen. Beim Umschalten der Wallbox (goE-Charger) von 1 auf 3 Phasen springt die Ladeleistung von 3.7 auf 4.2 kW. Der P-Anteil arbeitet sofort gegen den Sprung und es wird auf 1 Phase zurückgeschaltet. Beim PI-Controller habe ich das mit Javascript aktuell so gelöst:

if getState('mqtt.0.go-eCharger.modelStatus').val == 23) { // bei Phasenumschaltung Regler pausiern
        var y = pi.Control(0); // Stellwert nicht verändern
}

3. Stellgröße begrenzen. Z.B.: abhängig von der Außentemperatur soll eine Ventilstellung auf 30, 50, 70% begrenzt werden. Selbst wenn es im Raum zu kalt bleibt, wird die Stellgröße auf max. diesen Wert geschoben. im PI-Controller gibt es dafür
   pi.setOutputMax(100); // Begrenzung auf 100

Ist das okay, wenn ich Anforderungen, Ideen hier als "Issue" einbringe?

Danke für deine Mühe!