Vai al contenuto principale

Guide API di Reduxi

Aggiornato
📐 Reduxi · Documentazione tecnica

Guide API di Reduxi

Collegate i vostri sistemi a Reduxi: l'External API fornisce dati dal cloud tramite HTTPS, l'API MQTT offre accesso diretto a un Reduxi Controller attraverso il vostro broker MQTT.

📋 In questo articolo
  1. Di quale guida API avete bisogno?
  2. External API (REST)
  3. MQTT API
  4. Supporto delle versioni MQTT
  5. Configurazione dell'interfaccia MQTT di Reduxi
  6. Client Windows (MQTT Explorer)
  7. Comandi
  8. Setpoint

1 Di quale guida API avete bisogno?

Reduxi offre due guide API. Usate l'External API per recuperare dal cloud Reduxi i dati di controller, dispositivi, previsioni e prezzi. Usate l'API MQTT per leggere i valori di un Reduxi Controller e inviargli setpoint e comandi attraverso il vostro broker MQTT.

External API MQTT API
Tipo API REST su HTTPS (OpenAPI 3.0) Messaggi MQTT (versione 3.x) sul vostro broker MQTT
Origine dei dati Cloud Reduxi Reduxi Controller
Accesso Token Bearer Host, porta, nome utente e password del broker MQTT, impostati nel Reduxi Configurator
Direzione Recupera dati Legge dati, invia setpoint e comandi
Ideale per Dashboard, reportistica e integrazioni con dati di controller, dispositivi, previsioni e prezzi Monitoraggio e controllo di un controller in tempo reale

2 External API (REST)

L'External API dà accesso ai dati dei vostri controller nel cloud Reduxi. Tutti i valori di potenza ed energia sono espressi in unità di base: W e Wh. Le richieste sono autorizzate con un token Bearer.

  • Controller: elenco dei controller, dettagli di un controller e ultimo stato noto dei suoi dispositivi
  • Allarmi: allarmi attivi di un controller
  • Dati dei dispositivi: misure per dispositivo, misure aggregate per categoria di dispositivo e interrogazioni su più dispositivi
  • Tipi di dati: tipi di dati disponibili per un dispositivo
  • Previsioni: dati di previsione per sede o per controller
  • Prezzi: prezzi del mercato spot day-ahead, regioni del mercato spot ed elenchi prezzi per sede

🔌
Documentazione dell'External API
Endpoint, parametri e risposte dell'External API di Reduxi

3 MQTT API

L'API MQTT collega un Reduxi Controller al vostro broker MQTT. Il controller pubblica letture, informazioni sui dispositivi e sulle strategie nei topic, e voi inviate setpoint, comandi e impostazioni tramite altri topic. La specifica attuale è la versione 1.5 e richiede la versione software del controller 20260421084600.

  • Controller: identificatore, keep-alive, intervalli di lettura e di keep-alive, impostazioni di rete
  • Dispositivi: elenco dei dispositivi, informazioni sul dispositivo, letture e setpoint
  • Strategie: elenco delle strategie, informazioni, letture, parametri, stato attivo e impostazioni dell'EMS esterno
  • Comandi: aggiornamento dei metadati e riavvio

📡
Specifica dell'API MQTT
Tutti i topic, i payload e i metodi di sottoscrizione della specifica MQTT di Reduxi

La documentazione MQTT è generata dal punto di vista del Reduxi Controller.
Quando si leggono dati da Reduxi MQTT, compare il termine "PUB". Perché PUB? Perché i dati vengono pubblicati (publish) dal Reduxi Controller sul topic.
Quando si impostano valori sul Reduxi Controller tramite MQTT, compare il termine "SUB". Perché SUB? Perché il Reduxi Controller si sottoscrive (subscribe) al topic e ne legge i dati, applicando i valori inviati.

Le sezioni da 4 a 8 mostrano come impostare il Reduxi Configurator affinché il controller invii i dati al vostro broker MQTT. Si chiudono con un esempio di lettura di un dispositivo e impostazione dei suoi setpoint.

4 Supporto delle versioni MQTT

È supportata la versione 3. x. Non è invece supportata la 5. x.

5 Configurazione dell'interfaccia MQTT di Reduxi

Accedere al dispositivo Reduxi Controler e andare in System settings. In System settings selezionare MQTT v3 e definire i dati del broker MQTT: 

  • Host (solo dominio/IP, senza mqtts://)
  • Porta
  • Nome utente
  • Password
Pagina di connessione MQTT v3 di Reduxi Configurator: host, porta 1883, caricamento dei certificati PEM, intervallo di lettura 5 sec
Descrizione testuale di questa immagine

Schermata della pagina MQTT v3 connection di Reduxi Configurator. Menu a sinistra sotto il logo reduxi CONFIGURATOR: Users; Devices; Strategies; System (aperto, segno meno); Identifier; Network; Open VPN; Connector (aperto); Cloud; MQTT v3 (selezionato, in grassetto); iFlex; Configuration (chiuso, segno più); Distribution System Operators; Time. Intestazione della pagina: MQTT v3 connection, icona verde di collegamento a destra. Tabella di stato: Client: vuoto; Host: vuoto; Connected: segno di spunta verde. Sezione del modulo Mqtt connection: Host: mqtt.example.com (grigio, stile segnaposto); Port: 1883 (grigio); Username: vuoto; Password: vuoto; 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. Pulsanti: Clear, Save.

6 Client Windows (MQTT Explorer)

Per raccogliere i dati si può provare MQTT Explorer, collegandosi al broker MQTT con i seguenti dati: 

È possibile collegarsi al broker MQTT avviando un'applicazione MQTT Explorer.

Finestra MQTT Connection di MQTT Explorer: host mqtt.example.com, porta 1883, protocollo mqtt, TLS disattivato
Descrizione testuale di questa immagine

Schermata di MQTT Explorer (barra superiore: DISCONNECT, casella di ricerca) con la finestra MQTT Connection aperta sopra la finestra principale oscurata. Elenco a sinistra: pulsante giallo con il segno più con l'etichetta Connections; una voce salvata mqtt.example.com con testo piccolo mqtt://mqtt.example.com:1883/ (selezionata). Titolo della finestra: MQTT Connection, con mqtt://mqtt.example.com:1883/ accanto. Campi: Name: mqtt.example.com; Validate certificate: interruttore disattivato; Encryption (tls): interruttore disattivato; Protocol: mqtt:// (menu a discesa); Host: mqtt.example.com; Port: 1883; Username: vuoto; Password: mascherata con puntini, con un'icona a occhio per mostrare/nascondere. Pulsanti: DELETE, ADVANCED, SAVE (giallo), CONNECT (scuro). Sullo sfondo oscurato si vedono parte del pannello Topic e un valore JSON con le voci type POWER_ACTIVE, target FIXED, phaseType null.

7 Comandi

7.1. Aggiornare i metadati

Richiedere a Reduxi di ripubblicare su MQTT tutti i metadati su sistema, dispositivi e strategie. Altrimenti vengono pubblicati periodicamente solo le letture e i setpoint.

Topic: controllers/controller_unit_id/commands/refresh

Pannello Publish di MQTT Explorer con topic che termina in commands/refresh, json selezionato, freccia rossa su Publish
Descrizione testuale di questa immagine

Schermata di MQTT Explorer (stato DISCONNECT, casella di ricerca in alto) usata per inviare il comando refresh. Albero dei topic a sinistra: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE con keepAlive = 1734965285703; commands con la voce refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(tagliato); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 con 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 messaggi); 12 con 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 messaggi); 18 (1 topic, 2 messaggi); strategies: 8 con info = {"id":8,"typeId":7,"type":{"id":7,"name":"1-phase current based ON/OFF regulation","enumeration":"DISCRETE_CURRENT_PHASE_1"}; parameters (3 topic, 12 messaggi); 20 (2 topic, 8 messaggi); 27 (selezionato) con 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 messaggi); list = [{"id":8,"typeId":7. Sul lato destro: pannello Topic (badge 2) con il percorso controllers / ZGFE / strategies / 27; pannello Value con History; pannello Publish con Topic: controllers/ZGFE/commands/refresh; formato raw, xml, json con json selezionato; corpo del messaggio vuoto; pulsante PUBLISH con una freccia rossa che lo indica.

7.2. Riavvio

Riavvia il Reduxi Controller.

Topic: controllers/controller_unit_id/commands/reboot

Pannello Publish di MQTT Explorer con topic che termina in commands/reboot, json selezionato, pulsante Publish cerchiato in rosso
Descrizione testuale di questa immagine

Schermata dell'applicazione MQTT Explorer (stato DISCONNECT, casella di ricerca in alto) usata per inviare il comando reboot. Albero dei topic a sinistra: $SYS (48 topic, 406 messaggi); controllers; devices (29 topic, 865 messaggi); strategies (38 topic, 884 messaggi); commands (0 topic, 1 messaggio); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (riga selezionata); settings (2 topic, 2 messaggi); keepAlive = 1675762462861. Sul lato destro: in alto un'anteprima di un messaggio JSON con softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Pannello Publish con Topic: /controllers/ … /commands/reboot, con una parentesi rossa alla fine del campo del topic. Opzioni di formato raw, xml, json: json è selezionato. Il corpo del messaggio è vuoto. Il pulsante PUBLISH è cerchiato in rosso. QoS: 0; retain: casella non selezionata.

8 Setpoint

I setpoint controllano la potenza o la corrente di un dispositivo. Il Reduxi Controller pubblica i setpoint attivi di ogni dispositivo e voi ne impostate di nuovi tramite il topic /set corrispondente.

8.1. Visualizzare tutti i setpoint attivi del dispositivo

Topic: controllers/controller_unit_id/devices/device_id/setpoint

MQTT Explorer con il setpoint del dispositivo 15: action NONE, POWER_ACTIVE, FIXED, fase L1, valore 0, priorità 100
Descrizione testuale di questa immagine

Schermata di MQTT Explorer (stato DISCONNECT, casella di ricerca in alto) con il setpoint del dispositivo 15. Albero dei topic a sinistra: $SYS (48 topic, 862 messaggi); controllers; devices; 13 (3 topic, 235 messaggi); 14 (3 topic, 235 messaggi); 15 espanso con le voci readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (riga selezionata, contrassegnata da una parentesi rossa); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; poi 18, 8, 9, 10, 11, 12 (3 topic, 233 messaggi ciascuno); 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 topic, 2104 messaggi); commands (0 topic, 1 messaggio); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 topic, 2 messaggi); keepAlive = 1675762644772. Sul lato destro, Topic / controllers / / devices / 15 / setpoint. Pannello Value, QoS: 0, 02/07/2023 10:37:53 AM, con il pulsante della vista formattata cerchiato in rosso e il valore JSON racchiuso da una parentesi rossa: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (continua). History: 20.

8.2. Impostare i setpoint del dispositivo

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

MQTT Explorer pubblica un setpoint su devices/15/setpoint/set: SET POWER_ACTIVE FIXED valore 1000, priorità 10000
Descrizione testuale di questa immagine

Schermata di MQTT Explorer (stato DISCONNECT, casella di ricerca in alto) usata per pubblicare un setpoint per il dispositivo 15. Albero dei topic a sinistra: $SYS (48 topic, 1192 messaggi); controllers; devices (evidenziato); 13 (3 topic, 341 messaggi); 14 (3 topic, 341 messaggi); 15 espanso con readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (riga selezionata); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 topic, 339 messaggi); 8 (3 topic, 340 messaggi, evidenziato); 9, 10, 11, 12 (3 topic, 339 messaggi ciascuno); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 topic, 3062 messaggi); commands (0 topic, 1 messaggio); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 topic, 2 messaggi); keepAlive = 1675762764833. Sul lato destro: badge History 20, poi il pannello Publish. Topic: /controllers/ … /devices/15/setpoint/set; il campo del topic è contrassegnato da parentesi rosse e la parola set è sottolineata in rosso. Formato raw, xml, json: json selezionato. Corpo del messaggio, racchiuso da una parentesi rossa: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Il pulsante PUBLISH è cerchiato in rosso. QoS: 0; retain non selezionato. Sotto c'è una sezione History.

8.2.1. Esempio 1

Impostare la potenza attiva su -1 kW (esportazione) su tutte le fasi per 15 secondi.

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

8.2.2. Esempio 2

Limitare la corrente massima a 10A sulla fase L2 per 30 secondi.

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

Correlato a