Zum Hauptinhalt gehen

Reduxi API-Leitfäden

Aktualisiert
📐 Reduxi · Technische Dokumentation

Reduxi API-Leitfäden

Verbinden Sie Ihre eigenen Systeme mit Reduxi: Die External API liefert Cloud-Daten über HTTPS, die MQTT-API gibt Ihnen über Ihren MQTT-Broker direkten Zugriff auf einen Reduxi Controller.

📋 In diesem Artikel
  1. Welchen API-Leitfaden brauchen Sie?
  2. External API (REST)
  3. MQTT API
  4. Unterstützte MQTT-Versionen
  5. Konfiguration der Reduxi-MQTT-Schnittstelle
  6. Windows-Client (MQTT Explorer)
  7. Befehle
  8. Sollwerte

1 Welchen API-Leitfaden brauchen Sie?

Reduxi bietet zwei API-Leitfäden. Mit der External API rufen Sie Daten zu Ihren Controllern, Geräten, Prognosen und Preisen aus der Reduxi Cloud ab. Mit der MQTT-API lesen Sie Werte aus einem Reduxi Controller und senden ihm Sollwerte und Befehle über Ihren eigenen MQTT-Broker.

External API MQTT API
Typ REST-API über HTTPS (OpenAPI 3.0) MQTT-Nachrichten (Version 3.x) auf Ihrem MQTT-Broker
Datenquelle Reduxi Cloud Reduxi Controller
Zugriff Bearer-Token Host, Port, Benutzername und Passwort des MQTT-Brokers, festgelegt im Reduxi Configurator
Richtung Ruft Daten ab Liest Daten, sendet Sollwerte und Befehle
Geeignet für Dashboards, Reporting und Integrationen mit Controller-, Geräte-, Prognose- und Preisdaten Überwachung und Steuerung eines Controllers in Echtzeit

2 External API (REST)

Die External API gibt Ihnen Zugriff auf die Daten Ihrer Controller in der Reduxi Cloud. Alle Leistungs- und Energiewerte werden in Basiseinheiten geliefert: W und Wh. Anfragen werden mit einem Bearer-Token autorisiert.

  • Controller: Liste der Controller, Controller-Details und der zuletzt bekannte Status der Geräte eines Controllers
  • Alarme: aktive Alarme eines Controllers
  • Gerätedaten: Messwerte pro Gerät, aggregierte Messwerte pro Gerätekategorie und Abfragen über mehrere Geräte
  • Datentypen: die für ein Gerät verfügbaren Datentypen
  • Prognosen: Prognosedaten pro Standort oder pro Controller
  • Preise: Day-Ahead-Spotmarktpreise, Spotmarktregionen und Preislisten pro Standort

🔌
Dokumentation der External API
Endpunkte, Parameter und Antworten der Reduxi External API

3 MQTT API

Die MQTT-API verbindet einen Reduxi Controller mit Ihrem MQTT-Broker. Der Controller veröffentlicht seine Messwerte sowie Geräte- und Strategieinformationen in Topics, und Sie senden Sollwerte, Befehle und Einstellungen über andere Topics zurück. Die aktuelle Spezifikation hat die Version 1.5 und erfordert die Controller-Softwareversion 20260421084600.

  • Controller: Kennung, Keep-alive, Intervalle für Messwerte und Keep-alive, Netzeinstellungen
  • Geräte: Geräteliste, Geräteinformationen, Messwerte und Sollwerte
  • Strategien: Strategieliste, Informationen, Messwerte, Parameter, Aktivstatus und externe EMS-Einstellungen
  • Befehle: Metadaten aktualisieren und Neustart

📡
MQTT-API-Spezifikation
Alle Topics, Payloads und Subscribe-Methoden der Reduxi-MQTT-Spezifikation

Die MQTT-Dokumentation ist aus Sicht des Reduxi Controllers erstellt.
Wenn Sie aus Reduxi MQTT lesen, sehen Sie den Begriff "PUB". Warum PUB? Weil wir die Daten vom Reduxi Controller im Topic veröffentlichen (publish).
Wenn Sie über MQTT Werte an den Reduxi Controller senden, sehen Sie den Begriff "SUB". Warum SUB? Weil wir das Topic abonnieren (subscribe) und daraus Daten lesen. So übernimmt der Reduxi Controller die Werte, die Sie gesendet haben.

Die Abschnitte 4 bis 8 zeigen, wie Sie den Reduxi Configurator so einstellen, dass der Controller Daten an Ihren MQTT-Broker sendet. Sie enden mit einem Beispiel: ein Gerät auslesen und seine Sollwerte setzen.

4 Unterstützte MQTT-Versionen

Wir unterstützen die Version 3. x. Die Version 5. x unterstützen wir jedoch nicht.

5 Konfiguration der Reduxi-MQTT-Schnittstelle

Melden Sie sich am Reduxi Controller an und öffnen Sie die System settings. Wählen Sie unter System settings die Option MQTT v3 und legen Sie die Daten des MQTT-Brokers fest: 

  • Host (nur Domain/IP, ohne mqtts://)
  • Port
  • Benutzername
  • Passwort
Seite MQTT v3 connection im Reduxi Configurator: Host, Port 1883, Uploads für PEM-Zertifikate, Ausleseintervall 5 sec
Textbeschreibung dieses Bildes

Screenshot der Seite MQTT v3 connection im Reduxi Configurator. Linkes Menü unter dem Logo reduxi CONFIGURATOR: Users; Devices; Strategies; System (ausgeklappt, Minuszeichen); Identifier; Network; Open VPN; Connector (ausgeklappt); Cloud; MQTT v3 (ausgewählt, fett); iFlex; Configuration (eingeklappt, Pluszeichen); Distribution System Operators; Time. Seitenkopf: MQTT v3 connection, grünes Link-Symbol rechts. Statustabelle: Client: leer; Host: leer; Connected: grüner Haken. Formularabschnitt Mqtt connection: Host: mqtt.example.com (grau, Platzhalter-Stil); Port: 1883 (grau); Username: leer; Password: leer; Server CA chain (PEM format): Choose File, No file chosen; Client public certificate (PEM format): Choose File, No file chosen; Client private key (PEM format): Choose File, No file chosen; Readout interval: 5 sec. Schaltflächen: Clear, Save.

6 Windows-Client (MQTT Explorer)

Sie können versuchen, Daten mit dem MQTT Explorer zu erfassen, indem Sie sich wie folgt mit dem MQTT-Broker verbinden: 

Sie können sich mit dem MQTT-Broker verbinden, sobald Sie die Anwendung MQTT Explorer starten.

Dialog MQTT Connection im MQTT Explorer: Host mqtt.example.com, Port 1883, Protokoll mqtt, TLS aus
Textbeschreibung dieses Bildes

Screenshot des MQTT Explorers (obere Leiste: DISCONNECT, Suchfeld) mit geöffnetem Dialog MQTT Connection über dem abgedunkelten Hauptfenster. Linke Liste: gelbe Plus-Schaltfläche mit der Beschriftung Connections; ein gespeicherter Eintrag mqtt.example.com mit kleinem Text mqtt://mqtt.example.com:1883/ (ausgewählt). Dialogtitel: MQTT Connection, daneben mqtt://mqtt.example.com:1883/. Felder: Name: mqtt.example.com; Validate certificate: Schalter aus; Encryption (tls): Schalter aus; Protocol: mqtt:// (Dropdown); Host: mqtt.example.com; Port: 1883; Username: leer; Password: mit Punkten maskiert, mit einem Auge-Symbol zum Anzeigen/Verbergen. Schaltflächen: DELETE, ADVANCED, SAVE (gelb), CONNECT (dunkel). Im abgedunkelten Hintergrund sind ein Teil des Topic-Bereichs und ein JSON-Wert mit den Einträgen type POWER_ACTIVE, target FIXED, phaseType null zu sehen.

7 Befehle

7.1. Metadaten aktualisieren

Fordern Sie Reduxi auf, alle Metadaten zu System, Geräten und Strategien erneut an MQTT zu veröffentlichen. Andernfalls werden nur Messwerte und Sollwerte regelmäßig veröffentlicht.

Topic: controllers/controller_unit_id/commands/refresh

Publish-Bereich im MQTT Explorer mit einem Topic, das auf commands/refresh endet, json ausgewählt, roter Pfeil auf Publish
Textbeschreibung dieses Bildes

Screenshot des MQTT Explorers (Status DISCONNECT, Suchfeld oben), mit dem der Befehl refresh gesendet wird. Linker Topic-Baum: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE mit keepAlive = 1734965285703; commands mit dem Eintrag refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(abgeschnitten); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 mit info = {"id":2,"name":"Tesla Wall Connector Gen 3","typeId":59,"type":{"id":59,"categoryId":3,"category":{"id":3,"name":"EV charger","enumeration":"EV_CHARGER"; 4 (1 Topic, 2 Nachrichten); 12 mit info = {"id":12,"name":"Iskraemeco AM550","typeId":16,"type":{"id":16,"categoryId":1,"category":{"id":1,"name":"Energy meter","enumeration":"ENERGY_METER"; 17 (1 Topic, 2 Nachrichten); 18 (1 Topic, 2 Nachrichten); strategies: 8 mit info = {"id":8,"typeId":7,"type":{"id":7,"name":"1-phase current based ON/OFF regulation","enumeration":"DISCRETE_CURRENT_PHASE_1"}; parameters (3 Topics, 12 Nachrichten); 20 (2 Topics, 8 Nachrichten); 27 (ausgewählt) mit info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"}; parameters (1 Topic, 4 Nachrichten); list = [{"id":8,"typeId":7. Rechte Seite: Topic-Bereich (Badge 2) mit dem Pfad controllers / ZGFE / strategies / 27; Value-Bereich mit History; Publish-Bereich mit Topic: controllers/ZGFE/commands/refresh; Format raw, xml, json, json ausgewählt; leerer Nachrichtentext; Schaltfläche PUBLISH mit einem roten Pfeil, der darauf zeigt.

7.2. Neustart

Startet den Reduxi Controller neu.

Topic: controllers/controller_unit_id/commands/reboot

Publish-Bereich im MQTT Explorer mit einem Topic, das auf commands/reboot endet, json ausgewählt, Schaltfläche Publish rot eingekreist
Textbeschreibung dieses Bildes

Screenshot der Anwendung MQTT Explorer (Status DISCONNECT, Suchfeld oben), mit der der Befehl reboot gesendet wird. Linker Topic-Baum: $SYS (48 Topics, 406 Nachrichten); controllers; devices (29 Topics, 865 Nachrichten); strategies (38 Topics, 884 Nachrichten); commands (0 Topics, 1 Nachricht); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (ausgewählte Zeile); settings (2 Topics, 2 Nachrichten); keepAlive = 1675762462861. Rechte Seite: oben eine JSON-Nachrichtenvorschau mit softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Publish-Bereich mit Topic: /controllers/ … /commands/reboot, mit einer roten Klammer am Ende des Topic-Felds. Formatoptionen raw, xml, json: json ist ausgewählt. Der Nachrichtentext ist leer. Die Schaltfläche PUBLISH ist rot eingekreist. QoS: 0; retain: Kontrollkästchen nicht angehakt.

8 Sollwerte

Sollwerte steuern die Leistung oder den Strom eines Geräts. Der Reduxi Controller veröffentlicht die aktiven Sollwerte jedes Geräts, und neue Sollwerte setzen Sie über das passende /set-Topic.

8.1. Alle aktiven Sollwerte des Geräts anzeigen

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer zeigt den Sollwert von Gerät 15: action NONE, POWER_ACTIVE, FIXED, Phase L1, value 0, priority 100
Textbeschreibung dieses Bildes

Screenshot des MQTT Explorers (Status DISCONNECT, Suchfeld oben), der den Sollwert von Gerät 15 zeigt. Linker Topic-Baum: $SYS (48 Topics, 862 Nachrichten); controllers; devices; 13 (3 Topics, 235 Nachrichten); 14 (3 Topics, 235 Nachrichten); 15 ausgeklappt mit den Einträgen readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (ausgewählte Zeile, mit einer roten Klammer markiert); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; dann 18, 8, 9, 10, 11, 12 (je 3 Topics, 233 Nachrichten); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge","enumeration":"SOLAR_SOLARE; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 Topics, 2104 Nachrichten); commands (0 Topics, 1 Nachricht); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 Topics, 2 Nachrichten); keepAlive = 1675762644772. Rechte Seite, Topic / controllers / / devices / 15 / setpoint. Value-Bereich, QoS: 0, 02/07/2023 10:37:53 AM, mit der rot eingekreisten Schaltfläche für die formatierte Ansicht und dem JSON-Wert, der mit einer roten Klammer umrahmt ist: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (setzt sich fort). History: 20.

8.2. Sollwerte für das Gerät festlegen

Topic: controllers/controller_unit_id/devices/device_id/setpoint/set

MQTT Explorer veröffentlicht einen Sollwert an devices/15/setpoint/set: SET POWER_ACTIVE FIXED value 1000, priority 10000
Textbeschreibung dieses Bildes

Screenshot des MQTT Explorers (Status DISCONNECT, Suchfeld oben), mit dem ein Sollwert für Gerät 15 veröffentlicht wird. Linker Topic-Baum: $SYS (48 Topics, 1192 Nachrichten); controllers; devices (hervorgehoben); 13 (3 Topics, 341 Nachrichten); 14 (3 Topics, 341 Nachrichten); 15 ausgeklappt mit readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (ausgewählte Zeile); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 Topics, 339 Nachrichten); 8 (3 Topics, 340 Nachrichten, hervorgehoben); 9, 10, 11, 12 (je 3 Topics, 339 Nachrichten); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 Topics, 3062 Nachrichten); commands (0 Topics, 1 Nachricht); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 Topics, 2 Nachrichten); keepAlive = 1675762764833. Rechte Seite: History-Badge 20, dann der Publish-Bereich. Topic: /controllers/ … /devices/15/setpoint/set; das Topic-Feld ist mit roten Klammern markiert und das Wort set ist rot unterstrichen. Format raw, xml, json: json ausgewählt. Nachrichtentext, mit einer roten Klammer umrahmt: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Die Schaltfläche PUBLISH ist rot eingekreist. QoS: 0; retain nicht angehakt. Darunter folgt ein Bereich History.

8.2.1. Beispiel 1

Die Wirkleistung auf -1 kW (Export) an allen Phasen für 15 Sekunden setzen.

{
 "values": [
 {
 "action": "SET",
 "type": "POWER_ACTIVE",
 "target": "FIXED",
 "phaseType": null,
 "value": 1000,
 "priority": 10000,
 "validForTime": 15000
 }
 ]
}

8.2.2. Beispiel 2

Den maximalen Strom auf Phase L2 für 30 Sekunden auf 10 A begrenzen.

{
 "values": [
 {
 "action": "SET",
 "type": "CURRENT",
 "target": "MAX",
 "phaseType": "L2",
 "value": 10,
 "priority": 10000,
 "validForTime": 30000
 }
 ]
}

Verknüpfung mit