Eine API (Application Programming Interface) ist ein Satz von Befehlen, Funktionen, Protokollen und Objekten, die Programmierer verwenden können, um eine Software zu erstellen oder mit einem externen System zu interagieren. Sie stellt Entwicklern Standardbefehle für die Ausführung allgemeiner Operationen zur Verfügung, so dass Codes nicht von Grund auf neu geschrieben werden müssen. (siehe https://www.talend.com/de/resources/was-ist-eine-api/)
Im VanPi OS gibt es eine HTTP-API und eine MQTT-API, über welche von extern (und auch von intern) mit dem System kommuniziert werden kann.
HTTP-API:
Die HTTP-API stellt verschiedene Endpunkte bereit, über die ihr zum Beispiel Relays schalten oder Dimmer dimmen könnt.
Ihr erreicht diese Endpunkte unter <RPI-IP>:1880/, es muss also immer der Node-RED Port mit angegeben werden.
Wir benutzen dafür GET und PUT Requests. Per GET Request können wir Informationen bekommen, einen PUT Request benutzen wir, um Zustände zu verändern. So können wir zum Beispiel mit einer GET Anfrage an den Endpunkt /relay/2 den aktuellen Zustand von Relay 2 und den vergebenen Namen sehen, eine PUT Anfrage an /relay/2/true würde das Relay anschalten.
GET Anfragen kann man einfach in das Browser Adressfeld eingeben und bekommt dann eine Antwort im JSON-Format.
Um die API ausführlich testen zu können, benutzen wir das kostenlose Programm Postman (https://www.postman.com). Damit können wir alle möglichen verschiedenen Anfragen an das System stellen.
Über die API besteht unter anderem auch die Möglichkeit, die Heizung zu starten und dabei die gewünschte Temperatur und einen Timer zu setzen, nach dessen Ablauf die Heizung wieder ausgeht.
Ihr findet die HTTP-API genauer dokumentiert unter https://pekaway.de/docs/communication/#http-api, oder im Node-RED Backend im Flow „HTTP API“. Dort sind auch noch ein paar Endpunkte hinzugekommen, die ihren Weg noch nicht in die Dokumentation geschafft haben.
MQTT-API:
Ähnlich zur HTTP-API funktioniert das Ganze auch über MQTT. Dafür benutzen wir verschiedene Topics:
Unter dem Topic „pkw/cmnd/…“ senden wir zum Anfragen zum z.B. schalten von Relays, unter „pkw/stat/…“ erfragen wir den Status, unter „pkw/tele/…“ bekommen wir die Antwort.
Zum Testen benutzen wir hier das ebenfalls kostenlose Programm MQTT-Explorer (https://mqtt-explorer.com)
Um also unser Relay 2 zu schalten, senden wir die payload „on“ oder “off“ (alternativ geht auch „true“ oder „false“) an das Topic „pkw/cmnd/relay/2/POWER“. Damit wird das Relay entsprechend geschaltet.
Ebenso gibt es auch hier wieder Topics, um z. B. die Heizung steuern zu können. Wenn wir die Payload „on“ an das Topic „pkw/cmnd/heater/POWER/25/300“ senden, wird die Heizung angeschaltet, die Wunschtemperatur auf 25 °C gestellt und der Timer auf 300 Minuten gesetzt, die Heizung geht also nach 5 Stunden wieder aus. Die Timer laufen dabei bei beiden APIs nur im Hintergrund, ihr könnt sie nicht einsehen.
Die Dokumentation zur MQTT-API findet ihr unter https://pekaway.de/docs/communication/#mqtt-api oder wieder im Node-RED Backend im Flow „MQTT API“.
Tipps und Tricks:
Mit den APIs könnte man sich weitere Programme schreiben, die auf einem anderen RPI oder ESP laufen, welche dann wiederum auf die Daten zugreifen können.
Solltet ihr euch eigene Logiken in unseren Node-RED Flows hinzuprogrammiert haben, so bietet es sich an, diese Logiken in einem extra Flow zu schreiben und die Daten einfach intern über die APIs abzugreifen. Damit wäre bei einem Update eine gewisse Grundsicherheit gegeben, da man nur diesen Flow separat speichern müsste und einfach später wieder importieren kann.
Wenn man noch einen Schritt weitergehen will, kann man eine zweite Node_RED Instanz auf einem anderen Port installieren. Dann kommt die eigene Logik dort rein und man kann von dort via API auf die Daten der Basis Instanz zugreifen.
ACHTUNG: Wir greifen selber mit verschiedenen Geräten, zum Beispiel der IoT-Bridge und dem Dimmy, auf diese APIs zu. Also nicht wir, sondern diese Geräte … Ihr versteht, was ich meine. Das heißt jedenfalls, dass ihr diese APIs nicht verändern solltet. Natürlich könnt ihr euch ohne Probleme eigene Endpunkte etc. dazu schreiben.
