Die Varianten WARP Charger Smart und WARP Charger Pro können über MQTT und HTTP den aktuellen Zustand melden und gesteuert werden. Während die MQTT-API zunächst aktiviert und konfiguriert werden muss, kann die HTTP-API sofort verwendet werden, da sie auch vom Webinterface selbst benutzt wird.

Konfiguration

Damit die Wallbox über MQTT kommuniziert, muss zunächst im Webinterface die Verbindung zum MQTT-Broker konfiguriert werden. Folgende Einstellungen können vorgenommen werden:

• Broker-Hostname oder IP-Adresse: Der Hostname oder die IP-Adresse des Brokers zu dem sich die Wallbox verbinden soll.
• Broker-Port: Der Port unter dem der Broker erreichbar ist. Der typische MQTT-Port 1883 ist voreingestellt.
• Broker-Benutzername und Passwort: Manche Broker unterstützen eine Authentifizierung mit Benutzername und Passwort.
• Topic-Präfix: Dieser Präfix wird allen Topics vorangestellt, die die Wallbox verwendet. Voreingestellt ist warp/ABC wobei ABC eine eindeutige Kennung pro Wallbox ist, es sind aber andere Präfixe wie z.B. garage_links möglich. Falls mehrere Wallboxen mit dem selben Broker kommunizieren müssen eindeutige Präfixe pro Box gewählt werden.
• Client-ID: Mit dieser ID registriert sich die Wallbox beim Broker.

Nachdem die Konfiguration gesetzt und der "MQTT aktivieren"-Schalter gesetzt ist, kann die Konfiguration gespeichert werden. Der ESP startet dann neu und verbindet sich zum Broker. Auf der Status-Seite wird angezeigt, ob die Verbindung aufgebaut werden konnte.

MQTT-Konfiguration

Im Folgenden werden die mosquitto_pub und mosquitto_sub-Befehle des Mosquitto-MQTT-Brokers verwendet, um mit dem Broker zu kommunizieren.

Grundlagen

Wenn die Verbindung zum Broker erfolgreich aufgebaut wurde, sollten jetzt bereits erste Nachrichten der Wallbox eintreffen. Sämtliche Nachrichten der Wallbox sind Strings im JSON-Format. Genauso müssen alle Nachrichten, die zur Wallbox geschickt werden, das JSON-Format einhalten.

Mit mosquitto_sub -v -t "warp/ABC/#" können alle Nachrichten der Wallbox angezeigt werden. (Den Präfix warp/ABC gegebenenfalls durch den konfigurierten ersetzen) Es könnte z.B. die folgende Nachricht empfangen werden: warp/ABC/evse/state { "iec61851_state":1, "charger_state":2, "contactor_state":1, "contactor_error":0, "allowed_charging_current":32000, "error_state":0, "lock_state":0, "dc_fault_current_state":0 } Die Nachrichten des Topics evse/state geben einen Überblick über den Zustand des Ladecontrollers. Beispielsweise liegt der erlaubte Ladestrom gerade bei 32000, also 32 Ampere.

Durch Senden der Nachricht {"current":8000} an das Topic warp/ABC/evse/global_current_update kann der Ladestrom auf 8 Ampere begrenzt werden, zum Beispiel so: mosquitto_pub -t "warp/ABC/evse/global_current_update" -m "{\"current\": 8000}' (Damit die Beispiele auch mit cmd.exe von Windows kompatibel sind, werden nur doppelte Anführungszeichen verwendet. Anführungszeichen in JSON-Nachrichten müssen deshalb mit \ escapt werden.) Der Ladestrom ist jetzt auf 8 Ampere begrenzt, was die Wallbox durch eine neue Nachricht anzeigt: warp/ABC/evse/state {"iec61851_state":1, "charger_state":2, "contactor_state":1, "contactor_error":0, "allowed_charging_current":8000, "error_state":0, "lock_state":0, "dc_fault_current_state":0}

Konfiguration

Die HTTP-API kann ohne vorherige Konfiguration verwendet werden.

Grundlagen

Die HTTP-API funktioniert strukturell identisch wie die MQTT-API: Wenn die MQTT-API beispielsweise das Topic warp/ABC/evse/state verwendet, kann die selbe API über die URL http://[IP-Adresse oder Hostname der Wallbox]/evse/state erreicht werden. Die HTTP-API verfügt allerdings über fortgeschrittene Funktionen, die nicht über MQTT verfügbar sind. Es können zusätzlich die WebSockets unter ws://[IP-Adresse oder Hostname der Wallbox]/ws verwendet werden. Über eine WebSocket-Verbindung überträgt die Wallbox (analog zu MQTT) automatisch aktualisierte Werte.

Um Analog zum MQTT-Beispiel alle von der Wallbox gesendeten Nachrichten zu empfangen, kann eine WebSocket-Verbindung benutzt werden. Hierzu und für die weiteren Beispiele werden websocat und cURL verwendet und davon ausgegangen, dass die Wallbox unter der IP-Adresse 10.0.0.1 erreichbar ist.

Mit websocat ws://10.0.0.1/ws könnte unter anderem folgende Nachricht empfangen werden:

{
    "topic":"evse/state",
    "payload":{
        "iec61851_state":1,
        "charger_state":2,
        "contactor_state":1,
        "contactor_error":0,
        "allowed_charging_current":32000,
        "error_state":0,
        "lock_state":0,
        "dc_fault_current_state":0
    }
}

Wenn nur eine Information abgefragt werden soll, kann mit cURL eine einzelne URL aufgerufen werden: curl -s http://10.0.0.1/evse/state liefert äquivalente JSON-Daten: { "iec61851_state":1, "charger_state":2, "contactor_state":1, "contactor_error":0, "allowed_charging_current":32000, "error_state":0, "lock_state":0, "dc_fault_current_state":0 } Mit jq können einzelne Werte aus einem JSON-Objekt extrahiert werden. curl -s http://10.0.0.1/evse/state | jq ".allowed_charging_current" gibt 32000, also den erlaubten Ladestrom von 32 Ampere zurück.

Jetzt soll der Ladestrom auf 8 Ampere begrenzt werden. Dafür wird die Nachricht {"current":8000} an die URL http://10.0.0.1/evse/global_current_update geschickt: curl -H "Content-Type: application/json" -X PUT -d "{\"current\":8000}" 10.0.0.1/evse/global_current_update Wichtig ist hierbei, den Content-Type-Header auf application/json zu setzen, da die Anfrage sonst ignoriert wird. Für alle Anfragen, die Nachrichten an die Wallbox schicken muss HTTP PUT benutzt werden. POST, PATCH usw. werden derzeit nicht akzeptiert.

Zur Kontrolle: curl -s http://10.0.0.1/evse/state | jq ".allowed_charging_current" sollte jetzt 8000, also 8 Ampere zurückgeben.

Authentifizierung

Die HTTP-API und das Webinterface können durch einen Benutzernamen und ein Passwort geschützt werden. Die Authentifizierung kann im System-Abschnitt des Webinterfaces unter Zugangsdaten aktiviert werden. Alle Requests müssen dann mit der Digest access authentication authentisiert werden. Nicht authentifizierte Requests werden von der Wallbox mit dem HTTP-Code 401 beantwortet. Eine Ausnahme bildet die Hauptseite des Webinterfaces, die den meisten Browsern auf einen nicht authentifizierten Request mit der Login-Seite antwortet.

Die Wallbox bietet über MQTT und HTTP drei Arten von Schnittstellen: Zustände, Kommandos und Konfigurationen.

Zustände

Zustände sind Statusinformationen, die die Wallbox kontinuierlich an aktive WebSocket-Verbindungen und den MQTT-Broker schickt. Zustände können nicht direkt geändert werden, es ist aber möglich, dass Kommandos und Konfigurationen auf indirekte Weise Zustände beeinflussen. So kann durch Verwenden des evse/global_current_update-Kommandos der konfigurierte Ladestrom soweit gesenkt werden, dass er den erlaubten Ladestrom des evse/state-Zustands verändert. Zustände können vom Broker durch Subscriptions abgefragt werden: mosquitto_sub -v -t "warp/ABC/evse/state" liefert beispielsweise warp/ABC/evse/state { "iec61851_state":1, "charger_state":2, "contactor_state":1, "contactor_error":0, "allowed_charging_current":32000, "error_state":0, "lock_state":0, "dc_fault_current_state":0 } Für die HTTP-API funktioniert ein GET auf die entsprechende URL identisch: curl -s http://10.0.0.1/evse/state liefert die selben Daten.

Kommandos

Kommandos können durch publishen auf das entsprechende Topic bzw ein HTTP-PUT auf die entsprechende URL ausgelöst werden. Der Payload eines Kommandos muss immer gültiges JSON sein. Das heißt insbesondere, dass ein Kommando, das keine Informationen benötigt, nicht mit einer leeren Nachricht aufgerufen werden darf, sondern mit null oder einem der folgenden "leeren" Werte: "", false, 0, [] oder {}. Um einen Neustart des ESPs auszulösen kann beispielsweise folgendes Kommando verwendet werden: mosquitto_pub -t "warp/ABC/reboot" -m "null" Der analoge HTTP-Request wäre: curl -H "Content-Type: application/json" -X PUT -d "null" http://10.0.0.1/reboot Bestimmte Kommandos ändern den Zustand der Wallbox nicht direkt, sondern lösen einmalige Ereignisse aus. Ein Beispiel ist evse/stop_charging, das einen Ladevorgang abbricht. Falls ein Kommando dieser Art mit dem MQTT-Retain-Flag auf dem Broker hinterlegt wird, wird es nach einen Verbindungsaufbau von der Wallbox ignoriert. Das verhindert, dass eigentlich einmalige Ereignisse mehrfach ausgeführt werden.

Konfigurationen

Konfigurationen können sowohl gelesen, als auch geschrieben werden. Da sie im Flash des ESPs abgelegt werden, muss aber, damit eine aktualisierte Konfiguration verwendet wird, nach der Aktualisierung ein Neustart des ESPs ausgelöst werden. Konfigurationen werden unter dem jeweiligen Pfad von der Wallbox gepublisht. Aktualisierungen werden auf dem speziellen Suffix _update entgegengenommen. Es können dabei nicht zu verändernde Einträge der Konfiguration durch null ausgedrückt werden.

Konfigurationen setzen per MQTT

Wenn zum Beispiel die Access-Point-Konfiguration der Wallbox wie folgt abgefragt wird: mosquitto_sub -v -t "warp/ABC/wifi/ap_config" "warp/ABC/wifi/ap_config": {"enable_ap":true, "ap_fallback_only":false, "ssid":"warp-ABC", "hide_ssid":false, "passphrase":null, "channel":1, "ip":"10.0.0.1", "gateway":"10.0.0.1", "subnet":"255.255.255.0"}, kann der Access Point danach folgendermaßen in den Fallback-Modus gebracht werden: mosquitto_pub -t "warp/ABC/wifi/ap_config_update" -m "{\"ap_fallback_only\": true, \"enable_ap\":null, \"ssid\":null, \"hide_ssid\":null, \"passphrase\":null, \"channel\":null, \"ip\":null, \"gateway\":null, \"subnet\":null}" Danach muss, um die Konfiguration anzuwenden noch ein Neustart durchgeführt werden: mosquitto_pub -t "warp/ABC/reboot" -m "null" Der Access Point sollte dann ab jetzt nur noch aktiv sein, wenn die Verbindung zum konfigurierten WLAN fehlgeschlagen ist.

Konfigurationen setzen per HTTP

Mit der HTTP-API kann äquivalent die Access-Point-Konfiguration mit curl -s http://10.0.0.1/wifi/ap_config abgefragt werden, der Fallback-Modus mit curl http://10.0.0.1/wifi/ap_config_update -H "Content-Type: application/json" -X PUT -d "{\"ap_fallback_only\": true, \"enable_ap\":null, \"ssid\":null, \"hide_ssid\":null, \"passphrase\":null, \"channel\":null, \"ip\":null, \"gateway\":null, \"subnet\":null}" aktiviert werden und danach der Neustart mit curl -H "Content-Type: application/json" -X PUT -d "null" http://10.0.0.1/reboot ausgelöst werden.

_modified und _reset

Neben der eigentlichen Konfiguration und dem Kommando mit dem Suffix _update existiert pro Konfiguration auch ein Zustand mit dem Suffix _modified, sowie ein Kommando mit Suffix _reset. Wenn beispielsweise der Access Point wie oben in den Fallback-Modus gebracht wurde, liefert mosquitto_sub -v -t "warp/ABC/wifi/ap_config_modified" "warp/ABC/wifi/ap_config_modified": {"modified": 3} Der _modified-Zustand gibt an, ob eine Konfiguration modifiziert wurde. Mögliche Werte sind dabei 0 bis 3:

0. Derzeit wird die Standard-Konfiguration verwendet. Seit dem Starten wurde die Konfiguration nicht verändert.
1. Derzeit wird die Standard-Konfiguration verwendet. Seit dem Starten wurde die Konfiguration verändert. Damit die Veränderung wirkt, muss ein Neustart durchgeführt werden.
2. Derzeit wird nicht die Standard-Konfiguration verwendet. Seit dem Starten wurde die Konfiguration nicht verändert.
3. Derzeit wird nicht die Standard-Konfiguration verwendet. Seit dem Starten wurde die Konfiguration verändert. Damit die Veränderung wirkt, muss ein Neustart durchgeführt werden.

Abkürzungen

Die Nachrichten für Kommandos und Konfigurationen können abgekürzt werden, falls sie Objekte mit genau einem Eintrag sind. Es ist dann möglich, den Wert des Eintrags direkt zu übertragen.

Um zum Beispiel den Strom einer externen Steuerung auf 13 Ampere zu aktualisieren kann entweder mosquitto_pub -t "warp/ABC/evse/external_current_update" -m "{\"current\": 13000}" verwendet werden, oder es kann der neue Wert von 13000 direkt übergeben werden: mosquitto_pub -t "warp/ABC/evse/external_current_update" -m "13000"

WARP Charger melden die jeweils unterstützten Features auf dem Topic info/features. Mithilfe der Features ist es möglich, dass eine Anwendung die API so verwendet, dass sie mit allen Versionen und Varianten des WARP Chargers kompatibel ist. Feature-Voraussetzungen sind an API-Topics in der Referenz vermerkt. Folgende Features kann eine Wallbox anbieten:

EVSE ("evse")

Ein Ladecontroller steht zur Verfügung. Dieses Feature sollte bei allen WARP Chargern, deren Hardware funktionsfähig ist, vorhanden sein.

Control Pilot Disconnect ("cp_disconnect")

Der Ladecontroller kann das Control Pilot-Signal unterbrechen.

Phasenwechsel ("phase_switch")

Hardware und Konfiguration erlauben eine manuelle Phasenumschaltung mit der API power_manager/external_current_update.

Button-Konfiguration ("button_configuration")

Das Verhalten des Tasters an der Front der Wallbox kann umkonfiguriert werden. Bei WARP1 ist das nicht möglich, da der Taster und der Schlüsselschalter nicht voneinander unterschieden werden können.

Ethernet ("ethernet")

Es ist ein ESP Ethernet Brick verbaut. Eine LAN-Verbindung ist möglich.

Stromzähler ("meters")

Von mindestens einem Stromzähler konnten erfolgreich Werte gelesen werden.

NFC-Bricklet ("nfc")

Ein NFC-Bricklet wurde gefunden. Freischaltung per NFC ist möglich.

RTC-Bricklet ("rtc")

Ein RTC-Bricklet wurde gefunden. Die Systemzeit wird auch ohne Netzwerk-Zeitsynchronisierung über Neustarts hinweg erhalten.

(veraltete API) Stromzähler ("meter")

Ein Stromzähler und Hardware zum Auslesen desselben über RS485 ist verfügbar. Dieses Feature wird erst gesetzt, wenn ein Stromzähler mindestens einmal erfolgreich über Modbus ausgelesen wuerde.

(veraltete API) Stromzähler misst phasenweise ("meter_phases")

Der verbaute Stromzähler kann Energie und weitere Messwerte einzelner Phasen messen.

Verschiedene APIs des WARP Chargers benutzen Unions (auch bekannt als Summentypen), um veränderliche Objekte auszudrücken. Eine Union besteht aus deren Daten, sowie einem Tag, dass angibt welche Variante der Daten verwendet wird. Als Tag wird immer eine Zahl verwendet. Tag und Daten werden in einem JSON-Array mit immer genau zwei Einträgen dargestellt. Ein Wert der entweder ein Objekt mit zwei Einträgen oder eine Zeichenkette sein soll, könnte z.B. so ausgedrückt werden: [0, {"entry_a": 123, "entry_b": "abc"}] bzw. [1, "Hello World"].