Dokumentation

MQTT Anwendungsgebiete

MQTT ist ein Internetprotokoll mit einem zentralen Message-Broker. Bei diesem Message-Broker können Teilnehmer bestimmte "topics" abonnieren und Nachrichten zu topics versenden. Der cFos Charging Manager kann auf Nachrichten zu bestimmten topics hören und somit via MQTT gesteuert werden. Er kann auch den Zustand der von ihm verwalteten Geräte übermitteln. Die cFos Power Brain Wallbox kann ebenfalls via MQTT gesteuert werden und ihren Zustand übermitteln. Dies ist nützlich bei der Anbindung an ein Hausautomatisierungssystem, zur industriellen Steuerung (M2M) und zur Überwachung und Aufzeichnung. Alle topics beginnen mit cfos_mqtt. Wenn Sie mehrere cFos MQTT Geräte mit einem MQTT-Broker verbinden möchten, kann optional das topic mit cfos_mqtt_<Seriennummer>/ beginnen, einstellbar unter Konfiguration. In der Konfiguration können Sie außerdem eine URL für den Standard MQTT-Broker festlegen. URLs können optional mit mqtt:// und mqtts:// beginnen. Bei mqtts:// baut der cFos Charging Manager oder die cFos Power Brain Wallbox eine TLS Verbindung auf. Es werden die Standardports 1883 für unverschlüsselte Verbindungen und 8883 für TLS Verbindungen verwendet. Sie können aber auch einen Port in der URL angeben. Benutzernamen und Passwort können Sie in der üblichen URL Schreibweise angeben, z.B. mqtt://user:[email protected]. Wenn Sie in der cFos Charging Manager Konfiguration einen MQTT-Broker angeben, können Sie wahlweise einen individuellen broker angeben oder einfach mqtt schreiben. Dann wird der in der Konfiguration hinterlegte Standard broker verwendet.

Der cFos Charging Manager unterstüzt sowohl MQTT 3.1.1 und MQTT 5. Wenn Sie die URL mit mqtt3:// oder mqtt5:// beginnen lassen (mqtts3:// und mqtts5:// für verschlüsselte Verbindung), bestimmen Sie damit die Protokollversion. Default ist MQTT 3.1.1. Bei MQTT 5 versucht der cFos Charging Manager bei entsprechender Fehlermeldung auf MQTT 3.1.1 zurück zu schalten. Das klappt mit älteren Mosquitto brokern, aber nicht unbedingt mit anderen brokern.

Hinweis: Da die Einrichtung von MQTT das Admin Passwort erfordert, behandelt der Charging Manager die Daten entsprechend. Es werden also bewusst Daten versendet, auf die man nur mit Admin Passwort zugreifen kann.

Hinweis zu MQTT brokern: Dank Stefan G. (#diebestenuserderwelt) konnten wir gegen den in ioBroker eingebauten MQTT broker testen. Dieser MQTT 3.1.1 broker verhält sich (Stand Feb. 2023) in mehrerer Hinsicht nicht standardkonform: Connect-Versuche werden ohne Fehlermeldung stillschweigend beendet, in PUBLISH packets fehlt teilweise die payload, PUBLISH packets werden anscheinend doppelt versendet (kann man das durch ein config setting abstellen?). Damit ist dieser broker nicht zur Steuerung des Charging Manager APIs geeignet, da ggf. API requests mehrfach ausgeführt werden. Auch wenn wir daran interessiert sind, dass unsere MQTT Implementation mit möglichst vielen brokern kompatibel ist, empfehlen wir momentan für ioBroker den Einsatz von Mosquitto.

Einbindung von Zählern und Wallboxen mittels Gerätetyp "HTTP Input".

Statt diese Geräte mittels HTTP zu versorgen (s. HTTP API -> HTTP Zähler und Wallboxen), können diese Geräte auch auf MQTT hören. Geben Sie als Geräte-Adresse mqtt oder eine MQTT-Broker URL ein. Dann hört der entsprechende Zähler oder die Wallbox auf das topic cfos_mqtt/set/<Geräte-ID>, z.B. bei einem Zähler mit der Geräte ID M1 auf cfos_mqtt/set/M1. Als Nachricht erwartet das HTTP Input Zähler dann einen JSON string, wie im HTTP API unter "HTTP Zähler und Wallboxen" beschrieben. Ihre MQTT Quelle muss also die Daten in diesem Format anliefern. So können Sie Geräte, die der cFos Charging Manager nicht unterstützt, einbinden, indem Sie die Daten aus einer anderen Quelle beziehen (z.B. ein Hausautomatisierungssystem) und dann dem Charging Manager einspielen.
Hinweis: Wenn die Daten der Quelle in einem anderen Format vorliegen, als der HTTP Zähler sie erwartet,können Sie auch einen benutzerdefinierten Zähler anlegen. Für MQTT ist dies weiter unten beschrieben.

Beispiel:
Sie haben einen HTTP Input Zähler angelegt und dieser hat M3 als Geräte ID. Als Adresse haben Sie die Adresse des Mosquitto Brokers angegeben, z.B. mqtt://192.168.2.30. Wenn Sie auf dem Rechner, auf dem Mosquitto läuft, folgenden Befehl auf der Kommandozeile eingeben:
mosquitto_pub -h localhost -t cfos_mqtt/set/M3 -m '{ "model": "TestModell", "import_wh": 12345, "export_wh": 23456, "voltage": [231, 232, 233], "current": [10001, 10002, 10003] }'
sollte der Zähler dann die obigen Werte enthalten.

Zustand der Charging Manager Geräte übertragen

In der Charging Manager Konfiguration können Sie eine MQTT-Broker URL angeben (oder mqtt für Standard broker), unter der der Charging Manager dann unter dem topic cfos_mqtt/get/dev_info den Zustand aller Geräte veröffentlicht. Er überträgt diesen im vom HTTP get_dev_info bekannten Format. Damit erhalten Sie alle Werte der Geräte, wie sie auch im UI sichtbar sind, z.B. Leistungswerte der Zähler oder Zustand der Wallboxen. Wenn Sie nur einzelne Geräte abonnieren möchten, können Sie die Checkbox "Infos über MQTT veröffentlichen" deaktivieren und statt dessen in den Einstellungen der einzelnen Geräte unter "Anzeige" die Option "Infos über MQTT veröffentlichen" anhaken. Dann wird unter dem topic cfos_mqtt/get/<Geräte-ID> ein entsprechender JSON string über das jeweilige Gerät veröffentlicht. Außerdem können Sie unter dem topic cfos_mqtt/get/params alle globalen Werte abonnieren, wie sie im HTTP get_dev_info bekannten Format unter "params" ausgegeben werden.

cFos Charging Manager API über MQTT ansteuern

In der cFos Charging Manager Konfiguration können Sie unter "Broker für API Zugriff via MQTT" eine MQTT-Broker URL angeben (oder mqtt für Standard-Broker). Ist dieser Wert nicht leer, abonniert der cFos Charging Manager alle topics, die mit cfos_mqtt/api/ beginnen. Er interpretiert dann Nachrichten unter solchen topic so als wäre der topic Name eine HTTP URL, die mit /cnf? beginnt und leitet diese an das HTTP API weiter. Die Antwort des HTTP APIs veröffentlicht der Charging Manager dann unter dem topic cfos_mqtt/api_res als JSON. So haben Sie via MQTT nahezu das gesamte HTTP API unter Ihrer Kontrolle. Ausnahme sind API Aufrufe, die lange JSON Anworten liefern. Beispiel: cfos_mqtt/api/cmd=set_cm_vars&name=x&val=1 setzt mit der API Funktion set_cm_var die Charging Manager Variable x auf 1. Eine Nachricht unter cfos_mqtt/api/cmd=enter_rfid&rfid=5678&dev_id=E1 gibt die RFID 5678 für die Wallbox mit der Geräte-ID E1 ein (s. auch unsere erweiterten RFID Funktionen).
Daten, die per HTTP POST übertragen werden, können Sie in die Nachricht unter dem topic setzen.

Beispiel: Maximalen Gesamtstrom, den der Charging Manager zur Verfügung hat, periodisch verändern:
Tragen Sie unter den allg. Charging Manager Einstellungen unter "Brokere für API Zugriff via MQTT" Ihren Broker (oder einfach mqtt, wenn der unter "Konfiguration" hinterlegte Standard-Broker verwendet werden soll). Dann veröffentlichen Sie mittels MQTT an das topic
cfos_mqtt/api/cmd=set_params
ein JSON Object mit folgendem Inhalt:
{ "max_total_cur_prc": p }
wobei p eine Angabe in Prozent ist, welcher Anteil des voreingestellten maximalen Gesamtstroms genommen werden soll.
Hinweis: Einige der HTTP API Aufrufe führen dazu, dass der Charging Manager die Konfiguration speichert. Wenn Sie die zu häufig ausführen, verschleißt das Flash (im cFos Power Brain oder cFos Wallbox Booster) bzw. die SD-Karte im Raspberry. Der API Aufruf "set_params" mit dem einzelnen Parameter "max_total_cur_prc" führt deswegen extra nicht zum Speichern der Parameter.

Wallboxen über MQTT steuern

Wenn der cFos Charging Manager nicht im Modus "Lastmanagement" ist, sondern im Modus "Beobachten", können Sie mittels MQTT die Steuerung aller Wallboxen selbst übernehmen. Die gilt insbesondere für cFos Power Brain Wallboxen, die im Modus "Beobachten" als slave betrieben werden. Hierzu müssen Sie in Charging Manager Einstellungen unter MQTT die Option "Steuerung der Wallboxen aktivieren" anhaken. Dann hört der cFos Charging Manager auf das MQTT topic cfos_mqtt/ctl und erwartet Nachrichten mit einem JSON Objekt. Dieses Objekt hat als Eigenschaften Unterobjekte mit der Geräte-ID als Namen. Die Unterobjekte sehen so aus: { "cur": c, "ena": b, "wke": b, "phs": p }, wobei c der Ladestrom im mA ist, und b jeweils true oder false sein können. "ena": false deaktiviert das Laden an der Wallbox, "wke": true versucht an die Wallbox einen "Auto aufwecken"-Befehl zu senden (derzeit nur bei cFos Power Brain Wallboxen möglich). p kann 1 oder 3 sein, um zwischen 1-phasigem und 3-phasigem Laden umzuschalten. Sie können "cur", "ena", "wke" und "phs" auch weglassen und so nur bestimmte Steuerungsfunktionen ausführen. Beispiel:
{"E1":
{cur: 8000, ena: true, wke: true},
"E2":
{ cur: 10000, phs: 3 }}

Setzt den Ladestrom der Wallbox mit der Geräte-ID auf 8A, aktiviert das Laden und versucht das Auto aufzuwecken. Weiterhin wird für Wallbox E2 der Ladestrom auf 10A gesetzt und auf 3-phasiges Laden geschaltet.

Logging und Transaktionlog via MQTT senden

Sie können für die Übertragung von Log-Einträgen im System-Log unter "Konfiguration" eine MQTT-Broker URL angeben. Dann veröffentlicht der cFos Charging Manager alle Log-Einträge unter dem topic cfos_mqtt/log. Dies erlaubt Ihnen zur Überwachung des Charging Managers logs aus der Ferne auszuwerten. Ebenfalls können Sie unter "Konfiguration" eine MQTT-Broker URL für Einträge des Transaktionslogs angeben. Dann werden alle Lade-Transaktionen unter dem topic cfos_mqtt/ta_log versendet. Dies erlaubt Abrechnungsdaten der Lade-Transaktionen aus der Ferne auszuwerten und auf einem anderen System Sicherungen der Lade-Transaktionen anzulegen. Eine Lade-Transaktion beginnt mit dem Einstecken des Ladesteckers und endet mit dem Ausstecken.

Benutzerdefinierte Zähler mit MQTT

Sie können benutzerdefinierte Zähler erstellen und dabei rtype = 2 für MQTT verwenden. Diese Zähler werden ähnlich wie HTTP Zähler (rtype = 1) definiert. Die Adressen sind hier jedoch keine HTTP URLs, sondern MQTT topics. Beispiel:
"power_w": {
"address": "/test_topic3",
"type": "float",
"query": "power_w"
}

Hier abonniert der benutzerdefinierte Zähler das topic /test_topic3 und erwartet ein JSON Objekt mit property "power_w", also z.B. { "power_w": 1234 }. Unterschiedliche Zählervariablen können verschiedene topics haben und werden aktualisiert, sobald eine Nachricht unter dem entsprechenden topic veröffentlicht wird.