Przejdź do głównej zawartości

Przewodniki po API Reduxi

Zaktualizowano
📐 Reduxi · Dokumentacja techniczna

Przewodniki po API Reduxi

Połącz własne systemy z Reduxi: External API dostarcza dane z chmury przez HTTPS, a MQTT API daje bezpośredni dostęp do Reduxi Controller przez Twój broker MQTT.

📋 W tym artykule
  1. Którego przewodnika po API potrzebujesz?
  2. External API (REST)
  3. MQTT API
  4. Obsługa wersji MQTT
  5. Konfiguracja interfejsu MQTT Reduxi
  6. Klient Windows (MQTT Explorer)
  7. Polecenia
  8. Wartości zadane

1 Którego przewodnika po API potrzebujesz?

Reduxi oferuje dwa przewodniki po API. External API służy do pobierania z chmury Reduxi danych o Twoich sterownikach, urządzeniach, prognozach i cenach. MQTT API służy do odczytu wartości z Reduxi Controller i wysyłania do niego wartości zadanych oraz poleceń przez Twój własny broker MQTT.

External API MQTT API
Typ REST API przez HTTPS (OpenAPI 3.0) Wiadomości MQTT (wersja 3.x) na Twoim brokerze MQTT
Źródło danych Chmura Reduxi Reduxi Controller
Dostęp Token Bearer Host, port, nazwa użytkownika i hasło brokera MQTT, ustawione w Reduxi Configurator
Kierunek Pobiera dane Odczytuje dane, wysyła wartości zadane i polecenia
Zastosowanie Dashboardy, raportowanie i integracje z danymi o sterownikach, urządzeniach, prognozach i cenach Monitorowanie i sterowanie sterownikiem w czasie rzeczywistym

2 External API (REST)

External API daje dostęp do danych Twoich sterowników w chmurze Reduxi. Wszystkie wartości mocy i energii są podawane w jednostkach podstawowych: W i Wh. Żądania są autoryzowane tokenem Bearer.

  • Sterowniki: lista sterowników, szczegóły sterownika i ostatni znany stan jego urządzeń
  • Alarmy: aktywne alarmy sterownika
  • Dane urządzeń: pomiary według urządzenia, zagregowane pomiary według kategorii urządzeń i zapytania obejmujące wiele urządzeń
  • Typy danych: typy danych dostępne dla urządzenia
  • Prognozy: dane prognoz według lokalizacji lub sterownika
  • Ceny: ceny na rynku spot z dnia następnego, regiony rynku spot i cenniki według lokalizacji

🔌
Dokumentacja External API
Endpointy, parametry i odpowiedzi External API Reduxi

3 MQTT API

MQTT API łączy Reduxi Controller z Twoim brokerem MQTT. Sterownik publikuje odczyty oraz informacje o urządzeniach i strategiach w tematach (topics), a Ty odsyłasz wartości zadane, polecenia i ustawienia przez inne tematy. Aktualna specyfikacja ma wersję 1.5 i wymaga wersji oprogramowania sterownika 20260421084600.

  • Sterownik: identyfikator, keep-alive, interwały odczytu i keep-alive, ustawienia sieci
  • Urządzenia: lista urządzeń, informacje o urządzeniu, odczyty i wartości zadane
  • Strategie: lista strategii, informacje, odczyty, parametry, status aktywności i ustawienia zewnętrznego EMS
  • Polecenia: odświeżenie metadanych i restart

📡
Specyfikacja MQTT API
Wszystkie tematy, payloady i metody subskrypcji ze specyfikacji Reduxi MQTT

Dokumentacja MQTT jest tworzona z perspektywy Reduxi Controller.
Podczas odczytu z Reduxi MQTT zobaczysz termin "PUB". Dlaczego PUB? Ponieważ publikujemy dane z Reduxi Controller do tematu.
Podczas ustawiania wartości w Reduxi Controller przez MQTT zobaczysz termin "SUB". Dlaczego SUB? Ponieważ subskrybujemy temat i odczytujemy z niego dane, a wysłane przez Ciebie wartości są ustawiane w Reduxi Controller.

Rozdziały od 4 do 8 pokazują, jak ustawić Reduxi Configurator, aby sterownik wysyłał dane do Twojego brokera MQTT. Kończą się przykładem odczytu jednego urządzenia i ustawienia jego wartości zadanych.

4 Obsługa wersji MQTT

Obsługujemy wersję 3. x. Nie obsługujemy jednak wersji 5. x.

5 Konfiguracja interfejsu MQTT Reduxi

Zaloguj się do urządzenia Reduxi Controler i przejdź do ustawień systemu. W ustawieniach systemu wybierz MQTT v3 i zdefiniuj dane brokera MQTT: 

  • Host (tylko domena/IP, bez mqtts://)
  • Port
  • Nazwa użytkownika
  • Hasło
Strona połączenia MQTT v3 w Reduxi Configurator: host, port 1883, wczytywanie certyfikatów PEM, interwał odczytu 5 sek.
Opis tekstowy tego obrazu

Zrzut ekranu strony MQTT v3 connection w Reduxi Configurator. Lewe menu pod logo reduxi CONFIGURATOR: Users; Devices; Strategies; System (rozwinięte, znak minus); Identifier; Network; Open VPN; Connector (rozwinięte); Cloud; MQTT v3 (wybrane, pogrubione); iFlex; Configuration (zwinięte, znak plus); Distribution System Operators; Time. Nagłówek strony: MQTT v3 connection, zielona ikona linku po prawej. Tabela stanu: Client: puste; Host: puste; Connected: zielony znaczek. Sekcja formularza Mqtt connection: Host: mqtt.example.com (szare, styl tekstu zastępczego); Port: 1883 (szare); Username: puste; Password: puste; 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. Przyciski: Clear, Save.

6 Klient Windows (MQTT Explorer)

Dane możesz zbierać za pomocą MQTT Explorer, łącząc się z brokerem MQTT przy użyciu następujących ustawień: 

Z brokerem MQTT możesz się połączyć po uruchomieniu aplikacji MQTT Explorer.

Okno MQTT Connection w MQTT Explorer: host mqtt.example.com, port 1883, protokół mqtt, TLS wyłączone
Opis tekstowy tego obrazu

Zrzut ekranu MQTT Explorer (górny pasek: DISCONNECT, pole wyszukiwania) z otwartym oknem MQTT Connection nad przyciemnionym oknem głównym. Lewa lista: żółty przycisk plus z etykietą Connections; jeden zapisany wpis mqtt.example.com z małym tekstem mqtt://mqtt.example.com:1883/ (wybrany). Tytuł okna: MQTT Connection, a obok mqtt://mqtt.example.com:1883/. Pola: Name: mqtt.example.com; Validate certificate: przełącznik wyłączony; Encryption (tls): przełącznik wyłączony; Protocol: mqtt:// (lista rozwijana); Host: mqtt.example.com; Port: 1883; Username: puste; Password: zamaskowane kropkami, z ikoną oka pokaż/ukryj. Przyciski: DELETE, ADVANCED, SAVE (żółty), CONNECT (ciemny). W przyciemnionym tle widać fragment panelu Topic i wartość JSON z wpisami type POWER_ACTIVE, target FIXED, phaseType null.

7 Polecenia

7.1. Odświeżanie metadanych

Poproś Reduxi o ponowne opublikowanie w MQTT wszystkich metadanych o systemie, urządzeniach i strategiach. W przeciwnym razie okresowo publikowane są tylko odczyty i wartości zadane.

Topic: controllers/controller_unit_id/commands/refresh

Panel Publish w MQTT Explorer z tematem kończącym się na commands/refresh, wybrany json, czerwona strzałka przy Publish
Opis tekstowy tego obrazu

Zrzut ekranu MQTT Explorer (status DISCONNECT, pole wyszukiwania u góry) użytego do wysłania polecenia refresh. Lewe drzewo tematów: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE z keepAlive = 1734965285703; commands z wpisem refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(ucięte); 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 temat, 2 wiadomości); 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 temat, 2 wiadomości); 18 (1 temat, 2 wiadomości); 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 tematy, 12 wiadomości); 20 (2 tematy, 8 wiadomości); 27 (wybrane) z info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"}; parameters (1 temat, 4 wiadomości); list = [{"id":8,"typeId":7. Prawa strona: panel Topic (plakietka 2) ze ścieżką controllers / ZGFE / strategies / 27; panel Value z History; panel Publish z Topic: controllers/ZGFE/commands/refresh; format raw, xml, json z wybranym json; pusta treść wiadomości; przycisk PUBLISH ze czerwoną strzałką wskazującą na niego.

7.2. Restart

Restartuje Reduxi Controller.

Topic: controllers/controller_unit_id/commands/reboot

Panel Publish w MQTT Explorer z tematem kończącym się na commands/reboot, wybrany json, przycisk Publish zakreślony na czerwono
Opis tekstowy tego obrazu

Zrzut ekranu aplikacji MQTT Explorer (status DISCONNECT, pole wyszukiwania u góry) użytej do wysłania polecenia reboot. Lewe drzewo tematów: $SYS (48 tematów, 406 wiadomości); controllers; devices (29 tematów, 865 wiadomości); strategies (38 tematów, 884 wiadomości); commands (0 tematów, 1 wiadomość); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (wybrany wiersz); settings (2 tematy, 2 wiadomości); keepAlive = 1675762462861. Prawa strona: u góry podgląd wiadomości JSON z softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Panel Publish z Topic: /controllers/ … /commands/reboot, z czerwonym nawiasem na końcu pola tematu. Opcje formatu raw, xml, json: wybrany json. Treść wiadomości jest pusta. Przycisk PUBLISH zakreślony na czerwono. QoS: 0; retain: pole niezaznaczone.

8 Wartości zadane

Wartości zadane sterują mocą lub prądem urządzenia. Reduxi Controller publikuje aktywne wartości zadane każdego urządzenia, a nowe ustawiasz przez odpowiedni temat /set.

8.1. Wyświetlanie wszystkich aktywnych wartości zadanych urządzenia

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer pokazujący wartość zadaną urządzenia 15: action NONE, POWER_ACTIVE, FIXED, faza L1, wartość 0, priorytet 100
Opis tekstowy tego obrazu

Zrzut ekranu MQTT Explorer (status DISCONNECT, pole wyszukiwania u góry) pokazujący wartość zadaną urządzenia 15. Lewe drzewo tematów: $SYS (48 tematów, 862 wiadomości); controllers; devices; 13 (3 tematy, 235 wiadomości); 14 (3 tematy, 235 wiadomości); 15 rozwinięte z wpisami readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (wybrany wiersz, zaznaczony czerwonym nawiasem); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; następnie 18, 8, 9, 10, 11, 12 (po 3 tematy, 233 wiadomości); 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 tematów, 2104 wiadomości); commands (0 tematów, 1 wiadomość); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 tematy, 2 wiadomości); keepAlive = 1675762644772. Prawa strona, Topic / controllers / / devices / 15 / setpoint. Panel Value, QoS: 0, 02/07/2023 10:37:53 AM, z przyciskiem widoku sformatowanego zakreślonym na czerwono i wartością JSON zaznaczoną czerwonym nawiasem: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (ciąg dalszy). History: 20.

8.2. Ustawianie wartości zadanych dla urządzenia

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

MQTT Explorer publikujący wartość zadaną do devices/15/setpoint/set: SET POWER_ACTIVE FIXED wartość 1000, priorytet 10000
Opis tekstowy tego obrazu

Zrzut ekranu MQTT Explorer (status DISCONNECT, pole wyszukiwania u góry) użytego do opublikowania wartości zadanej dla urządzenia 15. Lewe drzewo tematów: $SYS (48 tematów, 1192 wiadomości); controllers; devices (wyróżnione); 13 (3 tematy, 341 wiadomości); 14 (3 tematy, 341 wiadomości); 15 rozwinięte 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".} (wybrany wiersz); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 tematy, 339 wiadomości); 8 (3 tematy, 340 wiadomości, wyróżnione); 9, 10, 11, 12 (po 3 tematy, 339 wiadomości); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 tematów, 3062 wiadomości); commands (0 tematów, 1 wiadomość); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 tematy, 2 wiadomości); keepAlive = 1675762764833. Prawa strona: plakietka History 20, następnie panel Publish. Topic: /controllers/ … /devices/15/setpoint/set; pole tematu jest zaznaczone czerwonymi nawiasami, a słowo set podkreślone na czerwono. Format raw, xml, json: wybrany json. Treść wiadomości, zaznaczona czerwonym nawiasem: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Przycisk PUBLISH zakreślony na czerwono. QoS: 0; retain niezaznaczone. Poniżej sekcja History.

8.2.1. Przykład 1

Ustaw moc czynną na -1 kW (eksport) na wszystkich fazach na 15 sekund.

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

8.2.2. Przykład 2

Ogranicz maksymalny prąd do 10A na fazie L2 na 30 sekund.

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

Powiązane z