Siirry pääsisältöön

Reduxin API-oppaat

Päivitetty
📐 Reduxi · Tekninen dokumentaatio

Reduxin API-oppaat

Yhdistä omat järjestelmäsi Reduxiin: External API tarjoaa pilvidataa HTTPS:n kautta, ja MQTT API antaa suoran pääsyn Reduxi Controlleriin oman MQTT-brokerisi kautta.

📋 Tässä artikkelissa
  1. Mitä API-opasta tarvitset?
  2. External API (REST)
  3. MQTT API
  4. MQTT-versiotuki
  5. Reduxin MQTT-rajapinnan määritys
  6. Windows-asiakas (MQTT Explorer)
  7. Komennot
  8. Asetusarvot

1 Mitä API-opasta tarvitset?

Reduxi tarjoaa kaksi API-opasta. External API:lla haet Reduxin pilvestä tietoja Reduxi Controller -yksiköistäsi, laitteistasi, ennusteistasi ja hinnoistasi. MQTT API:lla luet arvoja Reduxi Controllerista ja lähetät sille asetusarvoja ja komentoja oman MQTT-brokerisi kautta.

External API MQTT API
Tyyppi REST API HTTPS:n yli (OpenAPI 3.0) MQTT-viestit (versio 3.x) MQTT-brokerissasi
Datan lähde Reduxin pilvi Reduxi Controller
Pääsy Bearer-tunnus MQTT-brokerin isäntä, portti, käyttäjätunnus ja salasana, määritetty Reduxi Configuratorissa
Suunta Hakee dataa Lukee dataa, lähettää asetusarvoja ja komentoja
Käyttötarkoitus Kojelaudat, raportointi ja integraatiot, joissa tarvitaan Controller-, laite-, ennuste- ja hintatietoja Controllerin valvonta ja ohjaus reaaliajassa

2 External API (REST)

External API antaa pääsyn Controller-yksiköidesi tietoihin Reduxin pilvessä. Kaikki teho- ja energia-arvot annetaan perusyksiköissä: W ja Wh. Pyynnöt valtuutetaan Bearer-tunnuksella.

  • Controllerit: luettelo Controller-yksiköistä, yksikön tiedot ja sen laitteiden viimeisin tunnettu tila
  • Hälytykset: Controllerin aktiiviset hälytykset
  • Laitedata: mittaukset laitekohtaisesti, laiteluokittain koostetut mittaukset ja kyselyt usean laitteen yli
  • Datatyypit: laitteelle saatavilla olevat datatyypit
  • Ennusteet: ennustedata sijainnin tai Controllerin mukaan
  • Hinnoittelu: seuraavan päivän spot-markkinahinnat, spot-markkina-alueet ja sijaintikohtaiset hintaluettelot

🔌
External API -dokumentaatio
Reduxi External API:n päätepisteet, parametrit ja vastaukset

3 MQTT API

MQTT API yhdistää Reduxi Controllerin MQTT-brokeriisi. Controller julkaisee lukemansa sekä laite- ja strategiatiedot topiceihin, ja sinä lähetät asetusarvoja, komentoja ja asetuksia takaisin muiden topicien kautta. Nykyinen määrittely on versio 1.5, ja se edellyttää Controllerin ohjelmistoversiota 20260421084600.

  • Controller: tunniste, keep-alive, lukuvälit ja keep-alive-välit, verkkoasetukset
  • Laitteet: laiteluettelo, laitetiedot, lukemat ja asetusarvot
  • Strategiat: strategialuettelo, tiedot, lukemat, parametrit, aktiivisuustila ja ulkoisen EMS:n asetukset
  • Komennot: metadatan päivitys ja uudelleenkäynnistys

📡
MQTT API -määrittely
Reduxi MQTT -määrittelyn kaikki topicit, payloadit ja tilausmenetelmät

MQTT-dokumentaatio on laadittu Reduxi Controllerin näkökulmasta.
Kun luet dataa Reduxin MQTT:stä, näet termin "PUB". Miksi PUB? Koska julkaisemme Reduxi Controllerin datan topiciin.
Kun asetat arvoja Reduxi Controlleriin MQTT:n kautta, näet termin "SUB". Miksi SUB? Koska tilaamme topicin ja luemme siitä dataa, jolloin lähettämäsi arvot asetetaan Reduxi Controlleriin.

Luvut 4–8 näyttävät, miten Reduxi Configurator määritetään niin, että Controller lähettää dataa MQTT-brokeriisi. Ne päättyvät esimerkkiin, jossa luetaan yksi laite ja asetetaan sen asetusarvot.

4 MQTT-versiotuki

Tuemme versiota 3. x. Versiota 5. x emme kuitenkaan tue.

5 Reduxin MQTT-rajapinnan määritys

Kirjaudu Reduxi Controller -laitteeseen ja siirry kohtaan System settings. Valitse System settingsissä MQTT v3 ja määritä MQTT-brokerin tiedot: 

  • Host (vain verkkotunnus/IP-osoite, ilman mqtts://)
  • Portti
  • Username
  • Salasana
Reduxi Configuratorin MQTT v3 connection -sivu: host, portti 1883, PEM-varmenteiden lataukset, lukuväli 5 sek
Kuvan tekstikuvaus

Kuvakaappaus Reduxi Configuratorin MQTT v3 connection -sivusta. Vasen valikko reduxi CONFIGURATOR -logon alla: Users; Devices; Strategies; System (avattu, miinusmerkki); Identifier; Network; Open VPN; Connector (avattu); Cloud; MQTT v3 (valittu, lihavoitu); iFlex; Configuration (suljettu, plusmerkki); Distribution System Operators; Time. Sivun otsikko: MQTT v3 connection, oikealla vihreä linkkikuvake. Tilataulukko: Client: tyhjä; Host: tyhjä; Connected: vihreä valintamerkki. Lomakeosio Mqtt connection: Host: mqtt.example.com (harmaa, paikkamerkkityyli); Port: 1883 (harmaa); Username: tyhjä; Password: tyhjä; 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. Painikkeet: Clear, Save.

6 Windows-asiakas (MQTT Explorer)

Voit yrittää kerätä dataa MQTT Explorerilla ja yhdistämällä MQTT-brokeriin seuraavilla tiedoilla: 

Voit yhdistää MQTT-brokeriin, kun käynnistät MQTT Explorer -sovelluksen.

MQTT Explorerin MQTT Connection -ikkuna: host mqtt.example.com, portti 1883, protokolla mqtt, TLS pois päältä
Kuvan tekstikuvaus

Kuvakaappaus MQTT Explorerista (yläpalkki: DISCONNECT, hakukenttä), jossa MQTT Connection -ikkuna on auki himmennetyn pääikkunan päällä. Vasen luettelo: keltainen plus-painike, teksti Connections; yksi tallennettu kohta mqtt.example.com ja pieni teksti mqtt://mqtt.example.com:1883/ (valittu). Ikkunan otsikko: MQTT Connection, sen vieressä mqtt://mqtt.example.com:1883/. Kentät: Name: mqtt.example.com; Validate certificate: kytkin pois päältä; Encryption (tls): kytkin pois päältä; Protocol: mqtt:// (avattava luettelo); Host: mqtt.example.com; Port: 1883; Username: tyhjä; Password: piilotettu pisteillä, näytä/piilota-silmäkuvake. Painikkeet: DELETE, ADVANCED, SAVE (keltainen), CONNECT (tumma). Himmennetyssä taustassa näkyy osa Topic-paneelista ja JSON-arvo, jossa on kohdat type POWER_ACTIVE, target FIXED, phaseType null.

7 Komennot

7.1. Metatietojen päivitys

Pyydä Reduxia julkaisemaan uudelleen kaikki järjestelmän, laitteiden ja strategioiden metatiedot MQTT:hen. Muuten julkaistaan jaksoittain vain lukemat ja asetusarvot.

Topic: controllers/controller_unit_id/commands/refresh

MQTT Explorerin Publish-paneeli, topicin lopussa commands/refresh, json valittu, punainen nuoli kohdassa Publish
Kuvan tekstikuvaus

Kuvakaappaus MQTT Explorerista (tila DISCONNECT, hakukenttä ylhäällä), jolla lähetetään refresh-komento. Vasen topic-puu: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE ja keepAlive = 1734965285703; commands ja kohta refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(leikkautunut); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 ja 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 ja 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 ja 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 (valittu) ja 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. Oikealla puolella: Topic-paneeli (merkki 2), polku controllers / ZGFE / strategies / 27; Value-paneeli ja History; Publish-paneeli, jossa Topic: controllers/ZGFE/commands/refresh; muoto raw, xml, json, json valittu; tyhjä viestin runko; PUBLISH-painike, jota osoittaa punainen nuoli.

7.2. Uudelleenkäynnistys

Käynnistää Reduxi Controllerin uudelleen.

Topic: controllers/controller_unit_id/commands/reboot

MQTT Explorerin Publish-paneeli, topicin lopussa commands/reboot, json valittu, Publish-painike ympyröity punaisella
Kuvan tekstikuvaus

Kuvakaappaus MQTT Explorer -sovelluksesta (tila DISCONNECT, hakukenttä ylhäällä), jolla lähetetään reboot-komento. Vasen topic-puu: $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":.} (valittu rivi); settings (2 topics, 2 messages); keepAlive = 1675762462861. Oikealla puolella: JSON-viestin esikatselu ylhäällä, jossa softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Publish-paneeli, jossa Topic: /controllers/ … /commands/reboot, ja topic-kentän lopussa punainen hakasulje. Muotovaihtoehdot raw, xml, json: json on valittu. Viestin runko on tyhjä. PUBLISH-painike on ympyröity punaisella. QoS: 0; retain: valintaruutu ei valittu.

8 Asetusarvot

Asetusarvot ohjaavat laitteen tehoa tai virtaa. Reduxi Controller julkaisee kunkin laitteen aktiiviset asetusarvot, ja uudet arvot asetat vastaavan /set-topicin kautta.

8.1. Laitteen kaikkien aktiivisten asetusarvojen tarkastelu

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer näyttää laitteen 15 asetusarvon: action NONE, POWER_ACTIVE, FIXED, vaihe L1, value 0, priority 100
Kuvan tekstikuvaus

Kuvakaappaus MQTT Explorerista (tila DISCONNECT, hakukenttä ylhäällä), jossa näkyy laitteen 15 asetusarvo. Vasen topic-puu: $SYS (48 topics, 862 messages); controllers; devices; 13 (3 topics, 235 messages); 14 (3 topics, 235 messages); 15 avattuna ja kohdat readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (valittu rivi, merkitty punaisella hakasulkeella); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; sitten 18, 8, 9, 10, 11, 12 (3 topics, 233 messages kukin); 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. Oikealla puolella Topic / controllers / / devices / 15 / setpoint. Value-paneeli, QoS: 0, 02/07/2023 10:37:53 AM, muotoillun näkymän painike ympyröity punaisella ja JSON-arvo rajattu punaisella hakasulkeella: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (jatkuu). History: 20.

8.2. Laitteen asetusarvojen asettaminen

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

MQTT Explorer julkaisee asetusarvon topiciin devices/15/setpoint/set: SET POWER_ACTIVE FIXED value 1000, priority 10000
Kuvan tekstikuvaus

Kuvakaappaus MQTT Explorerista (tila DISCONNECT, hakukenttä ylhäällä), jolla julkaistaan laitteen 15 asetusarvo. Vasen topic-puu: $SYS (48 topics, 1192 messages); controllers; devices (korostettu); 13 (3 topics, 341 messages); 14 (3 topics, 341 messages); 15 avattuna ja kohdat readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (valittu rivi); 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, korostettu); 9, 10, 11, 12 (3 topics, 339 messages kukin); 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. Oikealla puolella: History-merkki 20 ja sen jälkeen Publish-paneeli. Topic: /controllers/ … /devices/15/setpoint/set; topic-kenttä on merkitty punaisilla hakasulkeilla ja sana set on alleviivattu punaisella. Muoto raw, xml, json: json valittu. Viestin runko, rajattu punaisella hakasulkeella: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. PUBLISH-painike ympyröity punaisella. QoS: 0; retain ei valittu. Alla on History-osio.

8.2.1. Esimerkki 1

Aseta pätöteho arvoon -1 kW (vienti) kaikissa vaiheissa 15 sekunnin ajaksi.

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

8.2.2. Esimerkki 2

Rajoita suurin virta 10 A:iin vaiheessa L2 30 sekunnin ajaksi.

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

Liittyy seuraavaan