Preskočiť na hlavný obsah

Sprievodcovia API Reduxi

Aktualizované
📐 Reduxi · Technická dokumentácia

Sprievodcovia API Reduxi

Prepojte vlastné systémy s Reduxi: External API poskytuje dáta z cloudu cez HTTPS, MQTT API vám dáva priamy prístup k Reduxi Controller cez váš MQTT broker.

📋 V tomto článku
  1. Ktorého sprievodcu API potrebujete?
  2. External API (REST)
  3. MQTT API
  4. Podpora verzií MQTT
  5. Konfigurácia rozhrania MQTT Reduxi
  6. Klient pre Windows (MQTT Explorer)
  7. Príkazy
  8. Žiadané hodnoty

1 Ktorého sprievodcu API potrebujete?

Reduxi ponúka dvoch sprievodcov API. External API použite na získanie dát o vašich jednotkách Reduxi Controller, zariadeniach, predpovediach a cenách z cloudu Reduxi. MQTT API použite na čítanie hodnôt z Reduxi Controller a na odosielanie žiadaných hodnôt a príkazov cez váš vlastný MQTT broker.

External API MQTT API
Typ REST API cez HTTPS (OpenAPI 3.0) Správy MQTT (verzia 3.x) vo vašom MQTT brokeri
Zdroj dát Cloud Reduxi Reduxi Controller
Prístup Token Bearer Hostiteľ, port, používateľské meno a heslo MQTT brokera, nastavené v Reduxi Configurator
Smer Načítava dáta Číta dáta, odosiela žiadané hodnoty a príkazy
Použitie Dashboardy, reporty a integrácie s dátami o jednotkách, zariadeniach, predpovediach a cenách Sledovanie a ovládanie jednotky v reálnom čase

2 External API (REST)

External API vám sprístupňuje dáta vašich jednotiek Controller v cloude Reduxi. Všetky hodnoty výkonu a energie sú v základných jednotkách: W a Wh. Požiadavky sa autorizujú tokenom Bearer.

  • Jednotky Controller: zoznam jednotiek, detaily jednotky a posledný známy stav jej zariadení
  • Alarmy: aktívne alarmy jednotky
  • Dáta zariadení: merania podľa zariadenia, agregované merania podľa kategórie zariadení a dotazy naprieč viacerými zariadeniami
  • Dátové typy: dátové typy dostupné pre zariadenie
  • Predpovede: dáta predpovedí podľa lokality alebo jednotky
  • Ceny: ceny na spotovom trhu na nasledujúci deň, spotové regióny a cenníky podľa lokality

🔌
Dokumentácia External API
Koncové body, parametre a odpovede rozhrania Reduxi External API

3 MQTT API

MQTT API prepája Reduxi Controller s vaším MQTT brokerom. Jednotka publikuje svoje odpočty a informácie o zariadeniach a stratégiách do tém (topics) a vy jej posielate žiadané hodnoty, príkazy a nastavenia späť cez iné témy. Aktuálna špecifikácia má verziu 1.5 a vyžaduje verziu softvéru jednotky 20260421084600.

  • Jednotka: identifikátor, keep-alive, intervaly odpočtu a keep-alive, nastavenia siete
  • Zariadenia: zoznam zariadení, informácie o zariadení, odpočty a žiadané hodnoty
  • Stratégie: zoznam stratégií, informácie, odpočty, parametre, stav aktivity a nastavenia externého EMS
  • Príkazy: obnovenie metadát a reštart

📡
Špecifikácia MQTT API
Všetky témy, dátové štruktúry a metódy odberu zo špecifikácie Reduxi MQTT

Dokumentácia MQTT je vytvorená z pohľadu Reduxi Controller.
Keď čítate z Reduxi MQTT, uvidíte pojem "PUB". Prečo PUB? Pretože dáta z Reduxi Controller publikujeme do témy.
Keď nastavujete hodnoty v Reduxi Controller cez MQTT, uvidíte pojem "SUB". Prečo SUB? Pretože tému odoberáme a čítame z nej dáta, čím nastavujeme hodnoty, ktoré ste poslali do Reduxi Controller.

Kapitoly 4 až 8 ukazujú, ako nastaviť Reduxi Configurator, aby jednotka odosielala dáta do vášho MQTT brokera. Končia príkladom čítania jedného zariadenia a nastavenia jeho žiadaných hodnôt.

4 Podpora verzií MQTT

Podporujeme verziu 3. x. Verziu 5. x však nepodporujeme.

5 Konfigurácia rozhrania MQTT Reduxi

Prihláste sa do zariadenia Reduxi Controller a prejdite do System settings. V System settings vyberte MQTT v3 a zadajte údaje brokera MQTT: 

  • Host (len doména/IP, bez mqtts://)
  • Port
  • Používateľské meno
  • Heslo
Stránka pripojenia MQTT v3 v Reduxi Configurator: host, port 1883, nahratie certifikátov PEM, interval načítania 5 sec
Textový popis tohto obrázka

Snímka obrazovky stránky MQTT v3 connection v Reduxi Configurator. Ľavé menu pod logom reduxi CONFIGURATOR: Users; Devices; Strategies; System (rozbalené, znamienko mínus); Identifier; Network; Open VPN; Connector (rozbalené); Cloud; MQTT v3 (vybrané, tučné); iFlex; Configuration (zbalené, znamienko plus); Distribution System Operators; Time. Hlavička stránky: MQTT v3 connection, vpravo zelená ikona prepojenia. Tabuľka stavu: Client: prázdne; Host: prázdne; Connected: zelená značka. Sekcia formulára Mqtt connection: Host: mqtt.example.com (sivé, štýl zástupného textu); Port: 1883 (sivé); Username: prázdne; Password: prázdne; 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čidlá: Clear, Save.

6 Klient pre Windows (MQTT Explorer)

Dáta môžete zbierať pomocou MQTT Explorer a pripojením k brokeru MQTT s týmito údajmi: 

K brokeru MQTT sa môžete pripojiť po spustení aplikácie MQTT Explorer.

Dialóg MQTT Connection v MQTT Explorer: host mqtt.example.com, port 1883, protokol mqtt, TLS vypnuté
Textový popis tohto obrázka

Snímka obrazovky MQTT Explorer (horná lišta: DISCONNECT, vyhľadávacie pole) s otvoreným dialógom MQTT Connection nad stmaveným hlavným oknom. Ľavý zoznam: žlté tlačidlo plus s popisom Connections; jedna uložená položka mqtt.example.com s malým textom mqtt://mqtt.example.com:1883/ (vybraná). Názov dialógu: MQTT Connection, vedľa neho mqtt://mqtt.example.com:1883/. Polia: Name: mqtt.example.com; Validate certificate: prepínač vypnutý; Encryption (tls): prepínač vypnutý; Protocol: mqtt:// (rozbaľovací zoznam); Host: mqtt.example.com; Port: 1883; Username: prázdne; Password: skryté bodkami, s ikonou oka na zobrazenie/skrytie. Tlačidlá: DELETE, ADVANCED, SAVE (žlté), CONNECT (tmavé). V stmavenom pozadí je vidieť časť panela Topic a hodnotu JSON so záznamami type POWER_ACTIVE, target FIXED, phaseType null.

7 Príkazy

7.1. Obnovenie metadát

Požiadajte Reduxi, aby znova publikoval do MQTT všetky metadáta o systéme, zariadeniach a stratégiách. Inak sa periodicky publikujú iba načítané hodnoty a žiadané hodnoty.

Topic: controllers/controller_unit_id/commands/refresh

Panel Publish v MQTT Explorer s témou končiacou commands/refresh, vybraný json, červená šípka pri Publish
Textový popis tohto obrázka

Snímka obrazovky MQTT Explorer (stav DISCONNECT, vyhľadávacie pole hore) použitého na odoslanie príkazu refresh. Ľavý strom tém: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE s keepAlive = 1734965285703; commands s položkou refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(odrezané); 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 téma, 2 správy); 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 téma, 2 správy); 18 (1 téma, 2 správy); 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 témy, 12 správ); 20 (2 témy, 8 správ); 27 (vybrané) s info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"}; parameters (1 téma, 4 správy); 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ázdne telo správy; tlačidlo PUBLISH s červenou šípkou, ktorá naň ukazuje.

7.2. Reštart

Reštartuje Reduxi Controller.

Topic: controllers/controller_unit_id/commands/reboot

Panel Publish v MQTT Explorer s témou končiacou commands/reboot, vybraný json, tlačidlo Publish zakrúžkované červenou
Textový popis tohto obrázka

Snímka obrazovky aplikácie MQTT Explorer (stav DISCONNECT, vyhľadávacie pole hore) použitej na odoslanie príkazu reboot. Ľavý strom tém: $SYS (48 tém, 406 správ); controllers; devices (29 tém, 865 správ); strategies (38 tém, 884 správ); commands (0 tém, 1 správa); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (vybraný riadok); settings (2 témy, 2 správy); keepAlive = 1675762462861. Pravá strana: hore náhľad správy JSON so softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Panel Publish s Topic: /controllers/ … /commands/reboot, s červenou zátvorkou na konci poľa témy. Možnosti formátu raw, xml, json: vybraný je json. Telo správy je prázdne. Tlačidlo PUBLISH je zakrúžkované červenou. QoS: 0; retain: políčko nezaškrtnuté.

8 Žiadané hodnoty

Žiadané hodnoty riadia výkon alebo prúd zariadenia. Reduxi Controller publikuje aktívne žiadané hodnoty každého zariadenia a nové nastavíte cez zodpovedajúcu tému /set.

8.1. Zobrazenie všetkých aktívnych žiadaných hodnôt zariadenia

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer zobrazuje žiadanú hodnotu zariadenia 15: action NONE, POWER_ACTIVE, FIXED, fáza L1, hodnota 0, priorita 100
Textový popis tohto obrázka

Snímka obrazovky MQTT Explorer (stav DISCONNECT, vyhľadávacie pole hore) zobrazujúca žiadanú hodnotu zariadenia 15. Ľavý strom tém: $SYS (48 tém, 862 správ); controllers; devices; 13 (3 témy, 235 správ); 14 (3 témy, 235 správ); 15 rozbalené s položkami 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ý riadok, označený červenou zátvorkou); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; potom 18, 8, 9, 10, 11, 12 (každé 3 témy, 233 správ); 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 tém, 2104 správ); commands (0 tém, 1 správa); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 témy, 2 správy); keepAlive = 1675762644772. Pravá strana, Topic / controllers / / devices / 15 / setpoint. Panel Value, QoS: 0, 02/07/2023 10:37:53 AM, s tlačidlom formátovaného zobrazenia zakrúžkovaným červenou a hodnotou JSON v červenej zátvorke: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (pokračuje). History: 20.

8.2. Nastavenie žiadaných hodnôt zariadenia

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

MQTT Explorer publikuje žiadanú hodnotu do devices/15/setpoint/set: SET POWER_ACTIVE FIXED hodnota 1000, priorita 10000
Textový popis tohto obrázka

Snímka obrazovky MQTT Explorer (stav DISCONNECT, vyhľadávacie pole hore) použitého na publikovanie žiadanej hodnoty pre zariadenie 15. Ľavý strom tém: $SYS (48 tém, 1192 správ); controllers; devices (zvýraznené); 13 (3 témy, 341 správ); 14 (3 témy, 341 správ); 15 rozbalené 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ý riadok); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 témy, 339 správ); 8 (3 témy, 340 správ, zvýraznené); 9, 10, 11, 12 (každé 3 témy, 339 správ); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 tém, 3062 správ); commands (0 tém, 1 správa); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 témy, 2 správy); keepAlive = 1675762764833. Pravá strana: odznak History 20, potom panel Publish. Topic: /controllers/ … /devices/15/setpoint/set; pole témy je označené červenými zátvorkami a slovo set je podčiarknuté červenou. Format raw, xml, json: vybraný json. Telo správy v červenej zátvorke: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Tlačidlo PUBLISH je zakrúžkované červenou. QoS: 0; retain nezaškrtnuté. Pod tým je sekcia History.

8.2.1. Príklad 1

Nastavte činný výkon na -1 kW (dodávka) na všetkých fázach na 15 sekúnd.

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

8.2.2. Príklad 2

Obmedzte maximálny prúd na 10 A vo fáze L2 na 30 sekúnd.

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

Súvisiace s