Přeskočit do hlavního obsahu

Průvodci API Reduxi

Aktualizováno
📐 Reduxi · Technická dokumentace

Průvodci API Reduxi

Propojte vlastní systémy s Reduxi: External API poskytuje data z cloudu přes HTTPS, MQTT API vám dává přímý přístup k Reduxi Controller prostřednictvím vašeho MQTT brokeru.

📋 V tomto článku
  1. Který průvodce API potřebujete?
  2. External API (REST)
  3. MQTT API
  4. Podpora verzí MQTT
  5. Konfigurace rozhraní MQTT Reduxi
  6. Klient pro Windows (MQTT Explorer)
  7. Příkazy
  8. Žádané hodnoty

1 Který průvodce API potřebujete?

Reduxi nabízí dva průvodce API. External API použijte k získání dat o vašich jednotkách Reduxi Controller, zařízeních, předpovědích a cenách z cloudu Reduxi. MQTT API použijte ke čtení hodnot z Reduxi Controller a k odesílání žádaných hodnot a příkazů přes váš vlastní MQTT broker.

External API MQTT API
Typ REST API přes HTTPS (OpenAPI 3.0) Zprávy MQTT (verze 3.x) ve vašem MQTT brokeru
Zdroj dat Cloud Reduxi Reduxi Controller
Přístup Token Bearer Hostitel, port, uživatelské jméno a heslo MQTT brokeru, nastavené v Reduxi Configurator
Směr Načítá data Čte data, odesílá žádané hodnoty a příkazy
Použití Dashboardy, reporty a integrace s daty o jednotkách, zařízeních, předpovědích a cenách Sledování a ovládání jednotky v reálném čase

2 External API (REST)

External API vám zpřístupňuje data vašich jednotek Controller v cloudu Reduxi. Všechny hodnoty výkonu a energie jsou v základních jednotkách: W a Wh. Požadavky se autorizují tokenem Bearer.

  • Jednotky Controller: seznam jednotek, detaily jednotky a poslední známý stav jejích zařízení
  • Alarmy: aktivní alarmy jednotky
  • Data zařízení: měření podle zařízení, agregovaná měření podle kategorie zařízení a dotazy napříč více zařízeními
  • Datové typy: datové typy dostupné pro zařízení
  • Předpovědi: data předpovědí podle lokality nebo jednotky
  • Ceny: ceny na denním spotovém trhu (day-ahead), spotové regiony a ceníky podle lokality

🔌
Dokumentace External API
Koncové body, parametry a odpovědi rozhraní Reduxi External API

3 MQTT API

MQTT API propojuje Reduxi Controller s vaším MQTT brokerem. Jednotka publikuje své odečty a informace o zařízeních a strategiích do témat (topics) a vy jí posíláte žádané hodnoty, příkazy a nastavení zpět přes jiná témata. Aktuální specifikace má verzi 1.5 a vyžaduje verzi softwaru jednotky 20260421084600.

  • Jednotka: identifikátor, keep-alive, intervaly odečtu a keep-alive, nastavení sítě
  • Zařízení: seznam zařízení, informace o zařízení, odečty a žádané hodnoty
  • Strategie: seznam strategií, informace, odečty, parametry, stav aktivace a nastavení externího EMS
  • Příkazy: obnovení metadat a restart

📡
Specifikace MQTT API
Všechna témata, datové struktury a metody odběru ze specifikace Reduxi MQTT

Dokumentace MQTT je vytvořena z pohledu Reduxi Controller.
Když čtete z Reduxi MQTT, uvidíte pojem "PUB". Proč PUB? Protože data z Reduxi Controller publikujeme do tématu (topic).
Když nastavujete hodnoty do Reduxi Controller přes MQTT, uvidíte pojem "SUB". Proč SUB? Protože téma odebíráme a čteme z něj data, čímž nastavujeme hodnoty, které jste do Reduxi Controller odeslali.

Kapitoly 4 až 8 ukazují, jak nastavit Reduxi Configurator, aby jednotka odesílala data do vašeho MQTT brokeru. Končí příkladem čtení jednoho zařízení a nastavení jeho žádaných hodnot.

4 Podpora verzí MQTT

Podporujeme verzi 3. x. Verzi 5. x však nepodporujeme.

5 Konfigurace rozhraní MQTT Reduxi

Přihlaste se k zařízení Reduxi Controller a přejděte do System settings. V System settings vyberte MQTT v3 a zadejte údaje MQTT brokeru: 

  • Host (pouze doména/IP adresa, bez mqtts://)
  • Port
  • Uživatelské jméno
  • Heslo
Stránka připojení MQTT v3 v Reduxi Configurator: host, port 1883, nahrání certifikátů PEM, interval odečtu 5 s
Textový popis tohoto obrázku

Snímek obrazovky stránky MQTT v3 connection v Reduxi Configurator. Levé menu pod logem reduxi CONFIGURATOR: Users; Devices; Strategies; System (rozbaleno, znaménko mínus); Identifier; Network; Open VPN; Connector (rozbaleno); Cloud; MQTT v3 (vybráno, tučně); iFlex; Configuration (sbaleno, znaménko plus); Distribution System Operators; Time. Záhlaví stránky: MQTT v3 connection, vpravo zelená ikona odkazu. Tabulka stavu: Client: prázdné; Host: prázdné; Connected: zelená fajfka. Sekce formuláře Mqtt connection: Host: mqtt.example.com (šedě, styl zástupného textu); Port: 1883 (šedě); Username: prázdné; Password: prázdné; 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. Tlačítka: Clear, Save.

6 Klient pro Windows (MQTT Explorer)

Data můžete sbírat pomocí MQTT Explorer a připojením k MQTT brokeru s následujícími údaji: 

K MQTT brokeru se můžete připojit po spuštění aplikace MQTT Explorer.

Dialog MQTT Connection v MQTT Explorer: host mqtt.example.com, port 1883, protokol mqtt, TLS vypnuto
Textový popis tohoto obrázku

Snímek obrazovky MQTT Explorer (horní lišta: DISCONNECT, vyhledávací pole) s otevřeným dialogem MQTT Connection nad ztmaveným hlavním oknem. Levý seznam: žluté tlačítko plus s popiskem Connections; jedna uložená položka mqtt.example.com s malým textem mqtt://mqtt.example.com:1883/ (vybráno). Název dialogu: MQTT Connection, vedle něj mqtt://mqtt.example.com:1883/. Pole: Name: mqtt.example.com; Validate certificate: přepínač vypnut; Encryption (tls): přepínač vypnut; Protocol: mqtt:// (rozbalovací pole); Host: mqtt.example.com; Port: 1883; Username: prázdné; Password: maskováno tečkami, s ikonou oka pro zobrazení/skrytí. Tlačítka: DELETE, ADVANCED, SAVE (žluté), CONNECT (tmavé). Na ztmaveném pozadí je vidět část panelu Topic a hodnotu JSON se záznamy type POWER_ACTIVE, target FIXED, phaseType null.

7 Příkazy

7.1. Obnovení metadat

Vyžádejte si, aby Reduxi znovu publikoval do MQTT všechna metadata o systému, zařízeních a strategiích. Jinak se pravidelně publikují pouze odečty a žádané hodnoty.

Topic: controllers/controller_unit_id/commands/refresh

Panel Publish v MQTT Explorer s topicem končícím commands/refresh, vybráno json, červená šipka u Publish
Textový popis tohoto obrázku

Snímek obrazovky MQTT Explorer (stav DISCONNECT, vyhledávací pole nahoře) použitého k odeslání příkazu refresh. Levý strom témat: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE s keepAlive = 1734965285703; commands se záznamem refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(oříznuto); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 s 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 messages); 12 s 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 messages); 18 (1 topic, 2 messages); strategies: 8 s 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 messages); 20 (2 topics, 8 messages); 27 (vybráno) s 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 messages); list = [{"id":8,"typeId":7. Pravá strana: panel Topic (odznak 2) s cestou controllers / ZGFE / strategies / 27; panel Value s History; panel Publish s Topic: controllers/ZGFE/commands/refresh; formát raw, xml, json s vybraným json; prázdné tělo zprávy; tlačítko PUBLISH s červenou šipkou, která na něj ukazuje.

7.2. Restart

Restartuje Reduxi Controller.

Topic: controllers/controller_unit_id/commands/reboot

Panel Publish v MQTT Explorer s topicem končícím commands/reboot, vybráno json, tlačítko Publish zakroužkováno červeně
Textový popis tohoto obrázku

Snímek obrazovky aplikace MQTT Explorer (stav DISCONNECT, vyhledávací pole nahoře) použité k odeslání příkazu reboot. Levý strom témat: $SYS (48 topics, 406 messages); controllers; devices (29 topics, 865 messages); strategies (38 topics, 884 messages); commands (0 topics, 1 message); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (vybraný řádek); settings (2 topics, 2 messages); keepAlive = 1675762462861. Pravá strana: nahoře náhled zprávy JSON se softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Panel Publish s Topic: /controllers/ … /commands/reboot, s červenou závorkou na konci pole topicu. Možnosti formátu raw, xml, json: vybráno json. Tělo zprávy je prázdné. Tlačítko PUBLISH je zakroužkováno červeně. QoS: 0; retain: pole není zaškrtnuto.

8 Žádané hodnoty

Žádané hodnoty řídí výkon nebo proud zařízení. Reduxi Controller publikuje aktivní žádané hodnoty každého zařízení a nové hodnoty nastavíte přes odpovídající téma /set.

8.1. Zobrazení všech aktivních žádaných hodnot zařízení

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer zobrazuje žádanou hodnotu zařízení 15: action NONE, POWER_ACTIVE, FIXED, fáze L1, hodnota 0, priorita 100
Textový popis tohoto obrázku

Snímek obrazovky MQTT Explorer (stav DISCONNECT, vyhledávací pole nahoře) zobrazující žádanou hodnotu zařízení 15. Levý strom témat: $SYS (48 topics, 862 messages); controllers; devices; 13 (3 topics, 235 messages); 14 (3 topics, 235 messages); 15 rozbaleno se záznamy readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (vybraný řádek, označený červenou závorkou); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; poté 18, 8, 9, 10, 11, 12 (každé 3 topics, 233 messages); 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 messages); commands (0 topics, 1 message); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 topics, 2 messages); keepAlive = 1675762644772. Pravá strana, Topic / controllers / / devices / 15 / setpoint. Panel Value, QoS: 0, 02/07/2023 10:37:53 AM, s tlačítkem formátovaného zobrazení zakroužkovaným červeně a hodnotou JSON orámovanou červenou závorkou: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (pokračuje). History: 20.

8.2. Nastavení žádaných hodnot zařízení

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

MQTT Explorer publikuje žádanou hodnotu do devices/15/setpoint/set: SET POWER_ACTIVE FIXED hodnota 1000, priorita 10000
Textový popis tohoto obrázku

Snímek obrazovky MQTT Explorer (stav DISCONNECT, vyhledávací pole nahoře) použitého k publikování žádané hodnoty pro zařízení 15. Levý strom témat: $SYS (48 topics, 1192 messages); controllers; devices (zvýrazněno); 13 (3 topics, 341 messages); 14 (3 topics, 341 messages); 15 rozbaleno s readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (vybraný řádek); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 topics, 339 messages); 8 (3 topics, 340 messages, zvýrazněno); 9, 10, 11, 12 (každé 3 topics, 339 messages); 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 messages); commands (0 topics, 1 message); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 topics, 2 messages); keepAlive = 1675762764833. Pravá strana: odznak History 20, poté panel Publish. Topic: /controllers/ … /devices/15/setpoint/set; pole topicu je označeno červenými závorkami a slovo set je podtrženo červeně. Formát raw, xml, json: vybráno json. Tělo zprávy, orámované červenou závorkou: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Tlačítko PUBLISH je zakroužkováno červeně. QoS: 0; retain není zaškrtnuto. Níže je sekce History.

8.2.1. Příklad 1

Nastavte činný výkon na -1 kW (export) na všech fázích na 15 sekund.

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

8.2.2. Příklad 2

Omezte maximální proud na 10 A na fázi L2 na 30 sekund.

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

Související s