API-Dokumentation

Vorab: Ändere nicht die vorhandenen Endpunkte der API im Backend, weder für HTTP noch für MQTT, da z.B. die App darauf zugreift und evtl. nicht mehr richtig funtkionieren würde! Hinzufügen eigener Endpunkte stellt allerdings kein Problem dar.

Einleitung

Diese Dokumentation beschreibt die verschiedenen API-Endpunkte und ihre Funktionen für die Steuerung von Relais, Dimmerschaltungen, Heizsystemen und weiteren Komponenten.

HTTP API

Funktionsweise

Die HTTP-API basiert auf RESTful-Methoden (GET, PUT). Sie ermöglicht die Steuerung und Überwachung von verschiedenen Geräten über einfache HTTP-Anfragen.

• GET-Anfragen werden verwendet, um den aktuellen Zustand von Geräten abzufragen.

• PUT-Anfragen werden verwendet, um den Zustand eines Geräts zu ändern.

Werkzeuge zum Testen

Um die HTTP-API zu testen, können verschiedene Tools verwendet werden:

• Postman: Ermöglicht das einfache Testen von API-Endpunkten durch eine grafische Benutzeroberfläche.

• cURL: Ein Befehlszeilentool, um HTTP-Anfragen zu senden.

• RESTer (Browser-Erweiterung): Eine API-Client-Erweiterung für Browser wie Firefox und Chrome.

Allgemeine Endpunkte

Names:

• GET /names - Zeigt alle Namen (wie im Dashboard zu sehen) und die dazugehörigen globalen Variablen (wie im Backend verwendet)

• PUT /names/<device>/<input>/<value> - Setzen von neuen Namen für das Frontend, mit <device> als das entsprechende device, <input> die Nummer des device und <value> als neuer Name.

  • Als device können "relay", "wrelay", "dimmer", "level" oder "temp" genutzt werden, device Nummer ( = <input>) kann 1-10 sein

  • Beispiel: PUT http://RPI-IP:1880/names/relay/3/Lights Kitchen - Der Name des 3. Relais wird geändert zu Lights Kitchen im Dashboard.

Batterie:

• GET /batt - Zeigt den aktuellen Batteriestatus

Wasserlevel:

• GET /level - Zeigt die aktuellen Wasserlevel

Temperatur:

• GET /temp - Zeigt die aktuellen Temperaturwerte

Heizung:

• GET /heater - Zeigt den aktuellen Status der Heizung(en)

• PUT /heater/<truefalse> - Schaltet die Heizung an/aus, wobei truefalse entweder true oder false ist

• PUT /heater/<truefalse>/<temp> - Schaltet die Heizung an/aus mit einer Zieltemperatur (°C), <temp> muss eine Nummer zwischen 12 und 35 sein

• PUT /heater/<truefalse>/<temp>/<time> - Schaltet die Heizung an/aus mit einer Zieltemperatur und einem Timer in Minuten, <time> muss eine Nummer zwischen 1 und 600 sein. Bitte beachte, dass der Timer nur im Backend läuft und nicht einsehbar ist im Frontend.

Relais:

• GET /relay/<input> - Zeigt den aktuellen Status des ausgewählten Relais, <input> kann "one" bis "eight", 1 bis 8 oder "all" sein

• GET /relay - Zeigt alle Relais, genauso wie GET /relay/all

• PUT /relay/<input>/<value> - Das gewählte Relais umschalten, <input> kann "one" bis "eight", oder 1 bis 10 sein und <value> muss entweder "true" (an) oder "false" (aus) sein

• PUT /toggle/relay/<input> - Schaltet das gewählte Relais um, <input> kann "one" bis "eight" oder 1 bis 10 sein, basierend auf dem aktuellen Status schaltet das Relais an oder aus

Wifi-Relays:

• GET /wrelay/<input> - Zeigt den aktuellen Status des ausgewählten Wifi-Relais, <input> kann "one" bis "eight", 1 bis 8 oder "all" sein

• GET /wrelay - Zeigt alle Wifi-Relais, genauso wie GET /wrelay/all

• PUT /wrelay/<input>/<value> - Das gewählte Wifi-Relais umschalten, <input> kann "one" bis "eight", oder 1 bis 10 sein und <value> muss entweder "true" (an) oder "false" (aus) sein

• PUT /toggle/wrelay/<input> - Schaltet das gewählte Wifi-Relais um, <input> kann "one" bis "eight" oder 1 bis 10 sein, basierend auf dem aktuellen Status schaltet das Relais an oder aus

Dimmers:

• GET /dimmer/<input> - Zeigt den aktuellen Dimmerstatus von 0 bis 100 an, <input> kann "one" bis "eight", 1 bis 8 oder "all" sein

• GET /dimmer - Zeigt alle Dimmer, genauso wie GET /dimmer/all

• PUT /dimmer/<input>/<value> - Ändert den Dimmerstatus, <input> kann "one" bis "eight", oder 1 bis 8 sein und <value> muss eine Nummer zwischen 0-100 sein (in Prozent)

Alles ausschalten:

• PUT /switchall/false - Schaltet alle Relais, Wifi-Relais und Dimmer aus

Zeit und Datum setzen:

• PUT /attime?date=YY/MM/DD&time=hh:mm:ss&gmt=+04 - Damit werden Datum und Uhrzeit des Servers festgelegt, wobei GMT in 15-Minuten-Schritten zur Greenwich Mean Time angegeben wird. Der Bereich reicht von -48 bis +48.

  • („Content-Type: text/html; charset=utf-8“ → „Inhaltstyp: text/html; Zeichensatz: UTF-8“)

  • Denk daran, die Zeitsynchronisation über das Netzwerk (systemd-timesyncd.service) zu deaktivieren, da sonst die Uhrzeit ständig überschrieben wird

Viele weitere Endpunkte zum Abfragen und Steuern der verschiedenen Integrationen sind im Backend ersichtlich.

MQTT API

Funktionsweise

Die MQTT-API basiert auf dem Message Queuing Telemetry Transport (MQTT)-Protokoll und ermöglicht eine asynchrone Kommunikation zwischen Geräten.

• Topics: MQTT-Themen werden zur Steuerung und Statusabfrage genutzt.

• QoS-Stufen: Definiert, ob Nachrichten einmal, mindestens einmal oder genau einmal zugestellt werden.

Werkzeuge zum Testen

Für die MQTT-API gibt es mehrere nützliche Tools:

• MQTT Explorer: Eine grafische Oberfläche zur Überwachung und Steuerung von MQTT-Nachrichten.

• Mosquitto (CLI-Tools): Ermöglicht das Testen von MQTT-Nachrichten über die Befehlszeile.

• Node-RED: Kann als visuelle Umgebung genutzt werden, um MQTT-Flows zu simulieren.

MQTT-Topics für Relais

home/cmnd/relayX/POWER

Beschreibung: Setzt den Zustand eines Relais (X ist die Relais-Nummer). Mögliche Werte: ON, OFF

home/stat/relayX/POWER

Beschreibung: Gibt den aktuellen Zustand eines Relais zurück. Antwortwerte: ON, OFF

MQTT-Topics für Dimmer

home/cmnd/dimmerX/SET

Beschreibung: Setzt die Helligkeit eines Dimmers. Wertebereich: 0-100

home/stat/dimmerX/STATUS

Beschreibung: Gibt den aktuellen Helligkeitswert eines Dimmers zurück.

MQTT-Topics für Heizungssteuerung

home/cmnd/heater/POWER

Beschreibung: Schaltet die Heizung ein oder aus. Werte: ON, OFF

home/cmnd/heater/TEMP

Beschreibung: Setzt die gewünschte Temperatur. Wertebereich: 10-30 Grad Celsius

Weitere MQTT-Topics

home/stat/batt

Beschreibung: Gibt den aktuellen Batterie-Status zurück. Veröffentlichungsintervall: Alle 5 Minuten. Daten:

{
    "voltage": 12.5,
    "current": 3.2,
    "soc": 80
}

home/stat/level

Beschreibung: Gibt den Füllstand von Tanks zurück. Veröffentlichungsintervall: Alle 5 Minuten.

home/stat/info

Beschreibung: Systeminformationen wie Firmware-Version und Netzwerkeinstellungen. Veröffentlichungsintervall: Alle 5 Minuten.

Fazit

Diese Dokumentation beschreibt die HTTP- und MQTT-Schnittstellen für die Steuerung der Smart-Home- und IoT-Komponenten. Die HTTP-API eignet sich für direkte API-Aufrufe, während die MQTT-API für eine ereignisgesteuerte Kommunikation verwendet wird. Die Nutzung von Tools wie Postman, MQTT Explorer und Mosquitto erleichtert das Testen und Debugging der Schnittstellen.