API (Programmierschnittstelle)
Die openWB kann über verschiedene Schnittstellen gesteuert werden.
openWB series1 und series2 Standard, Standard+, Buchse, Duo, Custom sowie Pro+:
- MQTT und MQTT-Brücke
- MQTT-API für openWB software2 im secondary mode
- openWB Modbus Rev2.0 im secondary mode
openWB Pro:
- Modbus
Das OCPP-Protokoll enthält auch einen Abschnitt zur Steuerung von Ladepunkten. Dies ist in openWB nicht umgesetzt. OCPP kann in der openWB ausschließlich zum Erfassen von Ladevorgängen genutzt werden. Weitere Infos zu OCPP in der openWB findet Ihr hier: https://wiki.openwb.de/doku.php?id=openwb:software:ocpp
MQTT und MQTT-Brücke
Für externe Automatisierungsysteme wie z.B. Homeassistant, io-broker usw., kann es notwendig sein, sich mit dem MQTT-Broker der openWB als Client oder per Brücke zu verbinden. Der openWB-Broker ist auf Port 1883 (unverschlüsselt, mqtt, kann optional abgeschaltet werden), 9001 (unverschlüsselt, Websochet, kann optional abgeschaltet werden), 8883 (verschlüsselt, mqtt) und 9002 (verschlüsselt, Websocket) erreichbar. Das Veröffentlichen von Topics ist nur an openWB/set möglich. Bei aktivierter Benutzerverwaltung müssen gültige Anmeldedaten mit übergeben werden. Die Rechte (lesen und schreiben) können mit den vordefinierten Rollen zugewiesen werden.
Die Regelung arbeitet mit den Daten aus dem openWB-Broker. Deshalb können falsche Daten, die über die MQTT-Schnittstelle gesendet werden, die Regelung stören. Wir haben Maßnahmen umgesetzt, um den openWB-Broker bestmöglich vor Fehlkonfiguration zu schützen. Bitte habt dennoch Verständnis, wenn wir Euch bei einem Supportfall bitten, externe Systeme kurzzeitig zu deaktivieren.
MQTT-API für openWB software2 im secondary mode
openWB series1, series2, Pro+ sowie openWB Pro bieten die gleiche Schnittstelle. Wenn die MQTT-Schnittstelle genutzt wird, darf die openWB nicht gleichzeitig von einer openWB primary gesteuert werden. Die openWB muss sich im Modus Secondary befinden.
Alle Werte müssen als retained Topics im JSON-Format veröffentlicht werden. Alle abonnierten Topics sind ebenfalls im JSON-Format.
{duo_num} muss durch die lokale Nummer des Ladepunkts ersetzt werden (Einstellungen → Konfiguration → Ladepunkte → Ladepunkt-Nummer). Wenn deine openWB keine openWB Duo ist, ist der Wert immer 0. Wenn deine openWB eine openWB Duo ist, müssen die Werte für duo_num=0 und duo_num=1 gepublished werden.
| Topic | Format | Einheit | Publish/Subscribe | Beschreibung | Hinweis |
|---|---|---|---|---|---|
| openWB/set/internal_chargepoint/{duo_num}/data/cp_interruption_duration | int | s | publish | Dauer der CP-Unterbrechung, wird sofort ausgeführt | |
| openWB/set/internal_chargepoint/{duo_num}/data/phases_to_use | int | 1;3 | publish | Sollwert für die Anzahl Phasen | |
| openWB/set/internal_chargepoint/{duo_num}/data/set_current | float | A/100; A | publish | Sollwert des Ladestroms, positiv (laden) oder negativ (entladen, falls vom Ladepunkt unterstützt) | |
| openWB/set/internal_chargepoint/{duo_num}/data/trigger_phase_switch | bool | publish | Phasenumschaltung jetzt anstoßen | ||
| openWB/set/internal_chargepoint/global_data | {„heartbeat“: int, „parent_ip“: str} | unix-timestamp | publish | Heartbeat setzen | Es muss mindestens alle 60s ein aktueller Zeitstempel geschrieben werden, sonst wird die Ladung gestoppt. |
| openWB/set/internal_chargepoint/last_tag | None | publish | Letzten Tag zurücksetzen, wenn dieser verarbeitet wurde | Der Tag muss durch das Publishen von None zurück gesetzt werden, wenn er von der Steuerung verarbeitet wurde. | |
| openWB/internal_chargepoint/{duo_num}/get/charge_state | bool | subscribe | Zeigt an, ob ein Ladevorgang aktiv ist | ||
| openWB/internal_chargepoint/{duo_num}/get/current_branch | str | subscribe | Ausgewählter Entwicklungszweig | ||
| openWB/internal_chargepoint/{duo_num}/get/current_commit | str | subscribe | Commit-Hash der installierten Version | ||
| openWB/internal_chargepoint/{duo_num}/get/currents | [float, float, float] | A | subscribe | Aktuelle Phasenströme | |
| openWB/internal_chargepoint/{duo_num}/get/evse_current | float | A*100; A | subscribe | Freigegebener Strom des Ladecontrollers | |
| openWB/internal_chargepoint/{duo_num}/get/exported | float | Wh | subscribe | Entladene Energie | |
| openWB/internal_chargepoint/{duo_num}/get/fault_state | int | subscribe | Fehlerstatus | 0: Kein Fehler 1: Warnung 2: Fehler |
|
| openWB/internal_chargepoint/{duo_num}/get/fault_str | str | subscribe | Fehlerbeschreibung | ||
| openWB/internal_chargepoint/{duo_num}/get/frequency | float | Hz | subscribe | Netzfrequenz | |
| openWB/internal_chargepoint/{duo_num}/get/imported | float | Wh | subscribe | Geladene Energie | |
| openWB/internal_chargepoint/{duo_num}/get/max_evse_current | float | A | subscribe | Maximaler Strom der EVSE | |
| openWB/internal_chargepoint/{duo_num}/get/phases_in_use | int | [0-3] | subscribe | Anzahl der Phasen, mit denen geladen wird. | |
| openWB/internal_chargepoint/{duo_num}/get/plug_state | bool | subscribe | Zeigt an, ob aktuell ein Fahrzeug angesteckt ist | ||
| openWB/internal_chargepoint/{duo_num}/get/power | float | W | subscribe | Leistung | |
| openWB/internal_chargepoint/{duo_num}/get/power_factors | [float, float, float] | subscribe | Aktuelle Leistungsfaktoren | ||
| openWB/internal_chargepoint/{duo_num}/get/powers | [float, float, float] | W | subscribe | Aktuelle Phasenleistungen | |
| openWB/internal_chargepoint/{duo_num}/get/rfid | str | subscribe | Zuletzt gescannter RFID-Tag oder PIN | ||
| openWB/internal_chargepoint/{duo_num}/get/serial_number | str | subscribe | Seriennummer des Zählers | ||
| openWB/internal_chargepoint/{duo_num}/get/soc | float | % | subscribe | SoC des angesteckten Fahrzeugs | nur verfügbar für Pro+ mit kompatiblem Fahrzeug |
| openWB/internal_chargepoint/{duo_num}/get/soc_timestamp | float | unix-timestamp | subscribe | Zeitstempel des SoC des angesteckten Fahrzeugs | |
| openWB/internal_chargepoint/{duo_num}/get/vehicle_id | str | MAC | subscribe | MAC-Adresse des angesteckten Fahrzeugs | nur verfügbar für Pro+ mit kompatiblem Fahrzeug |
| openWB/internal_chargepoint/{duo_num}/get/version | str | subscribe | Installierte Version | ||
| openWB/internal_chargepoint/{duo_num}/get/voltages | [float, float, float] | V | subscribe | Aktuelle Phasenspannungen |
openWB Modbus Rev2.0 im secondary mode
openWB series1, series2, Pro+ sowie openWB Pro bieten die gleiche Modbus-Schnittstelle. Wenn die Modbus-Schnittstelle genutzt wird, darf die openWB nicht gleichzeitig von einer openWB primary gesteuert werden.
Bei der openWB Pro ist die Modbus-Schnittstelle immer aktiv. Bei openWB series 1, series2 sowie Pro+ muss der Ladepunkt zunächst in den secondary-Modbus versetzt werden und dann unter Einstellungen → Allgemein → Steuerungsmodus die Option Steuerung über Modbus als secondary aktiviert werden.
Port: 1502, Slave ID: 1, Read input registers
Um dem Heartbeat aktiv zu halten muss wenigstens alle 80 Sekunden eine Anfrage erfolgen (lesend ausreichend).
| Register | Format | Read / Write | Value | Notes | Product (1=series2 2=Pro 3=both) |
|---|---|---|---|---|---|
| 10100 | sint32 | Read | LP 1 Actual Power | Watt | 3 |
| 10102 | sint32 | Read | LP 1 Wh Imported Counter | Wh Charged | 3 |
| 10104 | sint16 | Read | LP 1 Phase 1 Voltage | Voltage / 100 | 3 |
| 10105 | sint16 | Read | LP 1 Phase 2 Voltage | Voltage / 100 | 3 |
| 10106 | sint16 | Read | LP 1 Phase 3 Voltage | Voltage / 100 | 3 |
| 10107 | sint16 | Read | LP 1 Phase 1 Ampere | Ampere / 100 | 3 |
| 10108 | sint16 | Read | LP 1 Phase 2 Ampere | Ampere / 100 | 3 |
| 10109 | sint16 | Read | LP 1 Phase 3 Ampere | Ampere / 100 | 3 |
| 10114 | sint16 | Read | LP 1 Plugged Status | 0 = no, 1 = yes | 3 |
| 10115 | sint16 | Read | LP 1 Charging Active | 0 = no, 1 = yes | 3 |
| 10116 | sint16 | Read | LP 1 Actual A Configured | 0 = no charging allowed, 6-32 A, 600-3200 / 100 A | 3 |
| 10120 | sint16 | Read | LP 1 SoC | %, if available the SoC before start charging | 2 |
| 10121 | sint32 | Read | LP 1 SoC Timestamp | Timestamp when the SoC has been retrieved | 2 |
| 10130 | sint16 | Read | LP1 Phase 1 Watt | Watt | 3 |
| 10131 | sint16 | Read | LP1 Phase 2 Watt | Watt | 3 |
| 10132 | sint16 | Read | LP1 Phase 3 Watt | Watt | 3 |
| 10140 | sint16 | Read | LP 1 V2G Ready | 0 = Vehicle can’t do V2G, 1 = Vehicle is ready for V2G | 2 |
| 10141 | sint32 | Read | LP 1 Wh Exported Counter | Wh discharged | 2 |
| 10143 | sint16 | Read | Type of Hardware | 1 = series2, 2 = Pro | 3 |
| 10150 | String | Read | Serial Number of Chargepoint | String in ASCII, 2 characters each register, up to 20 characters (10150-10159) | 3 |
| 10160 | String | Read | RFID Tag | RFID Tag ASCII, 2 characters each register, up to 20 characters (10160-10169) | 3 |
| 10171 | sint16 | Write | Current LP 1 | Value in A * 100 (0, 600-3200) | 3 |
| 10180 | sint16 | Write | Phase Target | Trigger phase Switch, 1 = one Phase or 3 = three Phase | 3 |
| 10181 | sint16 | Write | Trigger Phase switching | 1 = trigger Phase switching | 1 |
| 10190 | sint16 | Write | Heartbeat | Configure Heartbeat, 0 = deactivated or 1 = activated. If heartbeat is enabled every read through modbus resets the heartbeat counter. If the counter is above 60 seconds the charging (if active) will be stopped. | 3 |
| 10198 | sint16 | Write | Trigger CP interrupt | Value in seconds triggers CP interruptions | 1 |
| 10199 | sint16 | Write | Force Update | Force Update of the Chargepoint, 1 = triggers Update. After the Update a reboot will be performed. | 2 |
| 10200 ++ | LP2 same as 101xx for LP1 |
Notes:
- Schreibbare Register sind nicht lesbar.
- Ein Rückgabewert von -1 meint im Normalfall eine ungültige Rückgabe im openWB Backend.