Preskoči na glavno vsebino

Vodniki za API Reduxi

Posodobljen
📐 Reduxi · Tehnična dokumentacija

Vodniki za API Reduxi

Povežite lastne sisteme z Reduxijem: External API zagotavlja podatke iz oblaka prek HTTPS, API MQTT pa vam omogoča neposreden dostop do naprave Reduxi Controller prek vašega MQTT brokerja.

📋 V tem članku
  1. Kateri vodnik za API potrebujete?
  2. External API (REST)
  3. MQTT API
  4. Podpora za različice MQTT
  5. Konfiguracija vmesnika MQTT Reduxi
  6. Odjemalec za Windows (MQTT Explorer)
  7. Ukazi
  8. Setpointi

1 Kateri vodnik za API potrebujete?

Reduxi ponuja dva vodnika za API. External API uporabite za pridobivanje podatkov o vaših krmilnikih, napravah, napovedih in cenah iz oblaka Reduxi. API MQTT uporabite za branje vrednosti iz naprave Reduxi Controller in pošiljanje setpointov ter ukazov prek vašega lastnega MQTT brokerja.

External API MQTT API
Vrsta REST API prek HTTPS (OpenAPI 3.0) Sporočila MQTT (različica 3.x) na vašem MQTT brokerju
Vir podatkov Oblak Reduxi Reduxi Controller
Dostop Žeton Bearer Gostitelj, vrata, uporabniško ime in geslo MQTT brokerja, nastavljeni v Reduxi Configurator
Smer Pridobiva podatke Bere podatke, pošilja setpointe in ukaze
Uporaba Nadzorne plošče, poročanje in integracije s podatki o krmilnikih, napravah, napovedih in cenah Spremljanje in upravljanje krmilnika v realnem času

2 External API (REST)

External API vam omogoča dostop do podatkov vaših krmilnikov v oblaku Reduxi. Vse vrednosti moči in energije so podane v osnovnih enotah: W in Wh. Zahtevki se overijo z žetonom Bearer.

  • Krmilniki: seznam krmilnikov, podrobnosti o krmilniku in zadnje znano stanje njegovih naprav
  • Alarmi: aktivni alarmi krmilnika
  • Podatki naprav: meritve po napravi, agregirane meritve po kategoriji naprav in poizvedbe po več napravah
  • Podatkovni tipi: podatkovni tipi, ki so na voljo za napravo
  • Napovedi: podatki napovedi po lokaciji ali po krmilniku
  • Cene: cene na spotnem trgu za naslednji dan, regije spotnega trga in cenovni seznami po lokaciji

🔌
Dokumentacija External API
Končne točke, parametri in odgovori vmesnika Reduxi External API

3 MQTT API

API MQTT povezuje Reduxi Controller z vašim MQTT brokerjem. Krmilnik objavlja odčitke ter informacije o napravah in strategijah v teme (topics), vi pa mu prek drugih tem pošiljate setpointe, ukaze in nastavitve. Trenutna specifikacija je različica 1.5 in zahteva programsko različico krmilnika 20260421084600.

  • Krmilnik: identifikator, keep-alive, intervali odčitavanja in keep-alive, nastavitve omrežja
  • Naprave: seznam naprav, informacije o napravi, odčitki in setpointi
  • Strategije: seznam strategij, informacije, odčitki, parametri, stanje aktivnosti in nastavitve zunanjega EMS
  • Ukazi: osvežitev metapodatkov in ponovni zagon

📡
Specifikacija API MQTT
Vse teme, strukture podatkov in metode naročanja iz specifikacije Reduxi MQTT

Dokumentacija MQTT je pripravljena z vidika Reduxi Controllerja.
Ko berete iz Reduxi MQTT, boste videli izraz "PUB". Zakaj PUB? Ker podatke iz Reduxi Controllerja objavljamo (publish) v temo.
Ko prek MQTT nastavljate vrednosti v Reduxi Controllerju, boste videli izraz "SUB". Zakaj SUB? Ker temo naročamo (subscribe) in iz nje beremo podatke ter v Reduxi Controllerju nastavimo vrednosti, ki ste jih poslali.

Poglavja od 4 do 8 prikazujejo, kako nastaviti Reduxi Configurator, da krmilnik pošilja podatke na vaš MQTT broker. Končajo se s primerom branja ene naprave in nastavljanja njenih setpointov.

4 Podpora za različice MQTT

Podpiramo različico 3. x. Različice 5. x pa ne podpiramo.

5 Konfiguracija vmesnika MQTT Reduxi

Prijavite se v napravo Reduxi Controler in odprite System settings. Pod System settings izberite MQTT v3 in določite podatke brokerja MQTT: 

  • Host (samo domena/IP, brez mqtts://)
  • Vrata
  • Uporabniško ime
  • Geslo
Stran MQTT v3 connection v Reduxi Configuratorju: host, port 1883, nalaganje certifikatov PEM, interval odčitavanja 5 sec
Besedilni opis te slike

Posnetek zaslona strani MQTT v3 connection v Reduxi Configuratorju. Levi meni pod logotipom reduxi CONFIGURATOR: Users; Devices; Strategies; System (razširjeno, znak minus); Identifier; Network; Open VPN; Connector (razširjeno); Cloud; MQTT v3 (izbrano, krepko); iFlex; Configuration (strnjeno, znak plus); Distribution System Operators; Time. Glava strani: MQTT v3 connection, zelena ikona povezave na desni. Tabela stanja: Client: prazno; Host: prazno; Connected: zelena kljukica. Razdelek obrazca Mqtt connection: Host: mqtt.example.com (sivo, v slogu nadomestnega besedila); Port: 1883 (sivo); Username: prazno; Password: prazno; 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. Gumba: Clear, Save.

6 Odjemalec za Windows (MQTT Explorer)

Podatke lahko poskusite zbirati z orodjem MQTT Explorer, tako da se povežete z brokerjem MQTT z naslednjimi podatki: 

Z brokerjem MQTT se lahko povežete, ko zaženete aplikacijo MQTT Explorer.

Pogovorno okno MQTT Connection v MQTT Explorerju: host mqtt.example.com, port 1883, protocol mqtt, TLS izklopljen
Besedilni opis te slike

Posnetek zaslona MQTT Explorerja (zgornja vrstica: DISCONNECT, iskalno polje) z odprtim pogovornim oknom MQTT Connection nad zatemnjenim glavnim oknom. Levi seznam: rumen gumb plus z oznako Connections; en shranjen vnos mqtt.example.com z majhnim besedilom mqtt://mqtt.example.com:1883/ (izbrano). Naslov pogovornega okna: MQTT Connection, ob njem mqtt://mqtt.example.com:1883/. Polja: Name: mqtt.example.com; Validate certificate: stikalo izklopljeno; Encryption (tls): stikalo izklopljeno; Protocol: mqtt:// (spustni seznam); Host: mqtt.example.com; Port: 1883; Username: prazno; Password: zakrito s pikami, z ikono očesa za prikaz/skritje. Gumbi: DELETE, ADVANCED, SAVE (rumen), CONNECT (temen). V zatemnjenem ozadju sta vidna del plošče Topic in vrednost JSON z vnosi type POWER_ACTIVE, target FIXED, phaseType null.

7 Ukazi

7.1. Osvežitev metapodatkov

Zahtevajte, naj Reduxi ponovno objavi vse metapodatke o sistemu, napravah in strategijah v MQTT. Sicer se periodično objavljajo samo odčitki in setpointi.

Topic: controllers/controller_unit_id/commands/refresh

Plošča Publish v MQTT Explorerju s temo, ki se konča s commands/refresh, izbran json, rdeča puščica pri Publish
Besedilni opis te slike

Posnetek zaslona MQTT Explorerja (stanje DISCONNECT, iskalno polje zgoraj), s katerim se pošlje ukaz refresh. Levo drevo tem: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE s keepAlive = 1734965285703; commands z vnosom refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(odrezano); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 z 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 tema, 2 sporočili); 12 z info = {"id":12,"name":"Iskraemeco AM550","typeId":16,"type":{"id":16,"categoryId":1,"category":{"id":1,"name":"Energy meter","enumeration":"ENERGY_METER"; 17 (1 tema, 2 sporočili); 18 (1 tema, 2 sporočili); strategies: 8 z info = {"id":8,"typeId":7,"type":{"id":7,"name":"1-phase current based ON/OFF regulation","enumeration":"DISCRETE_CURRENT_PHASE_1"}; parameters (3 teme, 12 sporočil); 20 (2 temi, 8 sporočil); 27 (izbrano) z info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"}; parameters (1 tema, 4 sporočila); list = [{"id":8,"typeId":7. Desna stran: plošča Topic (značka 2) s potjo controllers / ZGFE / strategies / 27; plošča Value z History; plošča Publish s Topic: controllers/ZGFE/commands/refresh; format raw, xml, json, izbran je json; prazno telo sporočila; gumb PUBLISH z rdečo puščico, ki kaže nanj.

7.2. Ponovni zagon

Znova zažene Reduxi Controller.

Topic: controllers/controller_unit_id/commands/reboot

Plošča Publish v MQTT Explorerju s temo, ki se konča s commands/reboot, izbran json, gumb Publish obkrožen z rdečo
Besedilni opis te slike

Posnetek zaslona aplikacije MQTT Explorer (stanje DISCONNECT, iskalno polje zgoraj), s katerim se pošlje ukaz reboot. Levo drevo tem: $SYS (48 tem, 406 sporočil); controllers; devices (29 tem, 865 sporočil); strategies (38 tem, 884 sporočil); commands (0 tem, 1 sporočilo); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (izbrana vrstica); settings (2 temi, 2 sporočili); keepAlive = 1675762462861. Desna stran: zgoraj predogled sporočila JSON z softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Plošča Publish s Topic: /controllers/ … /commands/reboot, z rdečim oklepajem na koncu polja teme. Možnosti formata raw, xml, json: izbran je json. Telo sporočila je prazno. Gumb PUBLISH je obkrožen z rdečo. QoS: 0; retain: potrditveno polje ni označeno.

8 Setpointi

Setpointi določajo moč ali tok naprave. Reduxi Controller objavlja aktivne setpointe vsake naprave, nove pa nastavite prek ustrezne teme /set.

8.1. Ogled vseh aktivnih setpointov naprave

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer prikazuje setpoint naprave 15: action NONE, POWER_ACTIVE, FIXED, phase L1, value 0, priority 100
Besedilni opis te slike

Posnetek zaslona MQTT Explorerja (stanje DISCONNECT, iskalno polje zgoraj), ki prikazuje setpoint naprave 15. Levo drevo tem: $SYS (48 tem, 862 sporočil); controllers; devices; 13 (3 teme, 235 sporočil); 14 (3 teme, 235 sporočil); 15 razširjeno z vnosi readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (izbrana vrstica, označena z rdečim oklepajem); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; nato 18, 8, 9, 10, 11, 12 (po 3 teme, 233 sporočil); 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 tem, 2104 sporočil); commands (0 tem, 1 sporočilo); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 temi, 2 sporočili); keepAlive = 1675762644772. Desna stran, Topic / controllers / / devices / 15 / setpoint. Plošča Value, QoS: 0, 02/07/2023 10:37:53 AM, z gumbom za oblikovani pogled, obkroženim z rdečo, in vrednostjo JSON, označeno z rdečim oklepajem: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (se nadaljuje). History: 20.

8.2. Nastavitev setpointov za napravo

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

MQTT Explorer objavlja setpoint na devices/15/setpoint/set: SET POWER_ACTIVE FIXED value 1000, priority 10000
Besedilni opis te slike

Posnetek zaslona MQTT Explorerja (stanje DISCONNECT, iskalno polje zgoraj), s katerim se objavi setpoint za napravo 15. Levo drevo tem: $SYS (48 tem, 1192 sporočil); controllers; devices (poudarjeno); 13 (3 teme, 341 sporočil); 14 (3 teme, 341 sporočil); 15 razširjeno z readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (izbrana vrstica); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 teme, 339 sporočil); 8 (3 teme, 340 sporočil, poudarjeno); 9, 10, 11, 12 (po 3 teme, 339 sporočil); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 tem, 3062 sporočil); commands (0 tem, 1 sporočilo); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 temi, 2 sporočili); keepAlive = 1675762764833. Desna stran: značka History 20, nato plošča Publish. Topic: /controllers/ … /devices/15/setpoint/set; polje teme je označeno z rdečimi oklepaji, beseda set je podčrtana z rdečo. Format raw, xml, json: izbran je json. Telo sporočila, označeno z rdečim oklepajem: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Gumb PUBLISH je obkrožen z rdečo. QoS: 0; retain ni označeno. Spodaj je razdelek History.

8.2.1. Primer 1

Nastavite delovno moč na -1 kW (oddaja) na vseh fazah za 15 sekund.

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

8.2.2. Primer 2

Omejite največji tok na 10 A na fazi L2 za 30 sekund.

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

Sorodno