Прескачане към основното съдържание

Ръководства за API на Reduxi

Обновено
📐 Reduxi · Техническа документация

Ръководства за API на Reduxi

Свържете собствените си системи с Reduxi: Външният API (External API) предоставя облачни данни през HTTPS, а MQTT API ви дава директен достъп до Reduxi Controller чрез вашия MQTT брокер.

📋 В тази статия
  1. От кое ръководство за API се нуждаете?
  2. Външен API (REST)
  3. MQTT API
  4. Поддръжка на версии на MQTT
  5. Конфигуриране на интерфейса MQTT на Reduxi
  6. Windows клиент (MQTT Explorer)
  7. Команди
  8. Зададени стойности

1 От кое ръководство за API се нуждаете?

Reduxi предлага две ръководства за API. Използвайте Външния API (External API), за да получавате от облака на Reduxi данни за вашите контролери, устройства, прогнози и цени. Използвайте MQTT API, за да четете стойности от Reduxi Controller и да му изпращате зададени стойности и команди през собствения си MQTT брокер.

Външен API (External API) MQTT API
Тип REST API през HTTPS (OpenAPI 3.0) MQTT съобщения (версия 3.x) във вашия MQTT брокер
Източник на данните Облак на Reduxi Reduxi Controller
Достъп Bearer токен Хост, порт, потребителско име и парола на MQTT брокера, зададени в Reduxi Configurator
Посока Извлича данни Чете данни, изпраща зададени стойности и команди
Подходящ за Табла, отчети и интеграции с данни за контролери, устройства, прогнози и цени Наблюдение и управление на контролер в реално време

2 Външен API (REST)

Външният API (External API) ви дава достъп до данните на вашите контролери в облака на Reduxi. Всички стойности за мощност и енергия са в базови единици: W и Wh. Заявките се оторизират с Bearer токен.

  • Контролери: списък с контролери, подробности за контролер и последното известно състояние на устройствата на контролера
  • Аларми: активни аларми на контролер
  • Данни от устройства: измервания по устройство, агрегирани измервания по категория устройства и заявки за няколко устройства
  • Типове данни: типовете данни, налични за устройство
  • Прогнози: данни за прогнози по местоположение или по контролер
  • Цени: цени на спот пазара за следващия ден, региони на спот пазара и ценови списъци по местоположение

🔌
Документация на Външния API
Крайни точки, параметри и отговори на Външния API на Reduxi

3 MQTT API

MQTT API свързва Reduxi Controller с вашия MQTT брокер. Контролерът публикува показанията си, информация за устройствата и стратегиите в теми (topics), а вие изпращате обратно зададени стойности, команди и настройки през други теми. Текущата спецификация е версия 1.5 и изисква софтуерна версия на контролера 20260421084600.

  • Контролер: идентификатор, keep-alive, интервали на отчитане и keep-alive, настройки на мрежата
  • Устройства: списък с устройства, информация за устройство, показания и зададени стойности
  • Стратегии: списък със стратегии, информация, показания, параметри, активен статус и настройки на външна EMS
  • Команди: опресняване на метаданните и рестартиране

📡
Спецификация на MQTT API
Всички теми, структури на данните и методи за абониране от спецификацията на Reduxi MQTT

MQTT документацията е изготвена от гледната точка на Reduxi Controller.
Когато четете от Reduxi MQTT, ще видите термина "PUB". Защо PUB? Защото публикуваме данните от Reduxi Controller в темата.
Когато задавате стойности на Reduxi Controller през MQTT, ще видите термина "SUB". Защо SUB? Защото се абонираме за темата и четем данните от нея, като задаваме на Reduxi Controller стойностите, които сте изпратили.

Раздели 4 до 8 показват как да настроите Reduxi Configurator, така че контролерът да изпраща данни към вашия MQTT брокер. Завършват с пример за четене на едно устройство и задаване на зададени стойности.

4 Поддръжка на версии на MQTT

Поддържаме версия 3. x. Не поддържаме обаче 5. x.

5 Конфигуриране на интерфейса MQTT на Reduxi

Влезте в устройството Reduxi Controler и отидете в System settings. Под System settings изберете MQTT v3 и определете данните на MQTT брокера: 

  • Host (само домейн/IP, без mqtts://)
  • Порт
  • Потребителско име
  • Парола
Страница MQTT v3 connection в Reduxi Configurator: host, порт 1883, качване на PEM сертификати, интервал на отчитане 5 sec
Текстово описание на това изображение

Екранна снимка на страницата MQTT v3 connection в Reduxi Configurator. Ляво меню под логото reduxi CONFIGURATOR: Users; Devices; Strategies; System (разгънато, знак минус); Identifier; Network; Open VPN; Connector (разгънато); Cloud; MQTT v3 (избрано, удебелено); iFlex; Configuration (свито, знак плюс); Distribution System Operators; Time. Заглавие на страницата: MQTT v3 connection, зелена иконка на връзка вдясно. Таблица със състояние: Client: празно; Host: празно; Connected: зелена отметка. Секция на формата Mqtt connection: Host: mqtt.example.com (сиво, като примерен текст); Port: 1883 (сиво); Username: празно; Password: празно; 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. Бутони: Clear, Save.

6 Windows клиент (MQTT Explorer)

Можете да опитате да събирате данни с MQTT Explorer, като се свържете към MQTT брокера със следното: 

Можете да се свържете към MQTT брокера, когато стартирате приложението MQTT Explorer.

Диалог MQTT Connection в MQTT Explorer: host mqtt.example.com, порт 1883, протокол mqtt, TLS изключен
Текстово описание на това изображение

Екранна снимка на MQTT Explorer (горна лента: DISCONNECT, поле за търсене) с отворен диалог MQTT Connection върху затъмнения главен прозорец. Ляв списък: жълт бутон плюс с надпис Connections; един запазен елемент mqtt.example.com с малък текст mqtt://mqtt.example.com:1883/ (избран). Заглавие на диалога: MQTT Connection, а до него mqtt://mqtt.example.com:1883/. Полета: Name: mqtt.example.com; Validate certificate: превключвател изключен; Encryption (tls): превключвател изключен; Protocol: mqtt:// (падащ списък); Host: mqtt.example.com; Port: 1883; Username: празно; Password: скрита с точки, с иконка око за показване/скриване. Бутони: DELETE, ADVANCED, SAVE (жълт), CONNECT (тъмен). В затъмнения фон се вижда част от панела Topic и JSON стойност с елементите type POWER_ACTIVE, target FIXED, phaseType null.

7 Команди

7.1. Опресняване на метаданните

Поискайте Reduxi да публикува отново в MQTT всички метаданни за системата, устройствата и стратегиите. В противен случай периодично се публикуват само отчитанията и зададените стойности.

Topic: controllers/controller_unit_id/commands/refresh

Панел Publish в MQTT Explorer с тема, завършваща на commands/refresh, избран json, червена стрелка към Publish
Текстово описание на това изображение

Екранна снимка на MQTT Explorer (състояние DISCONNECT, поле за търсене горе), използван за изпращане на командата refresh. Ляво дърво с теми: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE с keepAlive = 1734965285703; commands с елемент refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(отрязано); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 с 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 с 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 с 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 (избрано) с 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. Дясна страна: панел Topic (значка 2) с път controllers / ZGFE / strategies / 27; панел Value с History; панел Publish с Topic: controllers/ZGFE/commands/refresh; формат raw, xml, json с избран json; празно тяло на съобщението; бутон PUBLISH с червена стрелка, която го сочи.

7.2. Рестартиране

Рестартира Reduxi Controller.

Topic: controllers/controller_unit_id/commands/reboot

Панел Publish в MQTT Explorer с тема, завършваща на commands/reboot, избран json, бутонът Publish е заобиколен с червено
Текстово описание на това изображение

Екранна снимка на приложението MQTT Explorer (състояние DISCONNECT, поле за търсене горе), използвано за изпращане на командата reboot. Ляво дърво с теми: $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":.} (избран ред); settings (2 topics, 2 messages); keepAlive = 1675762462861. Дясна страна: JSON преглед на съобщение отгоре със softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Панел Publish с Topic: /controllers/ … /commands/reboot, с червена скоба в края на полето за тема. Опции за формат raw, xml, json: избран е json. Тялото на съобщението е празно. Бутонът PUBLISH е заобиколен с червено. QoS: 0; retain: квадратчето не е отметнато.

8 Зададени стойности

Зададените стойности управляват мощността или тока на устройство. Reduxi Controller публикува активните зададени стойности на всяко устройство, а вие задавате нови през съответната тема /set.

8.1. Преглед на всички активни зададени стойности за устройството

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer показва зададена стойност на устройство 15: action NONE, POWER_ACTIVE, FIXED, фаза L1, value 0, priority 100
Текстово описание на това изображение

Екранна снимка на MQTT Explorer (състояние DISCONNECT, поле за търсене горе), показваща зададената стойност на устройство 15. Ляво дърво с теми: $SYS (48 topics, 862 messages); controllers; devices; 13 (3 topics, 235 messages); 14 (3 topics, 235 messages); 15 разгънато с елементи readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (избран ред, маркиран с червена скоба); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; след това 18, 8, 9, 10, 11, 12 (по 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. Дясна страна, Topic / controllers / / devices / 15 / setpoint. Панел Value, QoS: 0, 02/07/2023 10:37:53 AM, с бутона за форматиран изглед, заобиколен с червено, и JSON стойността, обградена с червена скоба: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (продължава). History: 20.

8.2. Задаване на зададени стойности за устройството

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

MQTT Explorer публикува зададена стойност в devices/15/setpoint/set: SET POWER_ACTIVE FIXED value 1000, priority 10000
Текстово описание на това изображение

Екранна снимка на MQTT Explorer (състояние DISCONNECT, поле за търсене горе), използван за публикуване на зададена стойност за устройство 15. Ляво дърво с теми: $SYS (48 topics, 1192 messages); controllers; devices (маркирано); 13 (3 topics, 341 messages); 14 (3 topics, 341 messages); 15 разгънато с readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (избран ред); 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, маркирано); 9, 10, 11, 12 (по 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. Дясна страна: значка History 20, след това панел Publish. Topic: /controllers/ … /devices/15/setpoint/set; полето за тема е маркирано с червени скоби, а думата set е подчертана с червено. Формат raw, xml, json: избран json. Тяло на съобщението, обградено с червена скоба: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Бутонът PUBLISH е заобиколен с червено. QoS: 0; retain не е отметнато. Отдолу е секция History.

8.2.1. Пример 1

Задайте активна мощност -1 kW (изнасяне) на всички фази за 15 секунди.

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

8.2.2. Пример 2

Ограничете максималния ток до 10A на фаза L2 за 30 секунди.

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

Свързани с(ъс)