Guías de API de Reduxi
Conecte sus propios sistemas con Reduxi: la External API ofrece datos de la nube a través de HTTPS y la API MQTT le da acceso directo a un Reduxi Controller mediante su broker MQTT.
1 ¿Qué guía de API necesita?
Reduxi ofrece dos guías de API. Use la External API para obtener de la nube de Reduxi datos de sus controladores, dispositivos, previsiones y precios. Use la API MQTT para leer valores de un Reduxi Controller y enviarle consignas y comandos a través de su propio broker MQTT.
| External API | MQTT API | |
|---|---|---|
| Tipo | API REST sobre HTTPS (OpenAPI 3.0) | Mensajes MQTT (versión 3.x) en su broker MQTT |
| Origen de los datos | Nube de Reduxi | Reduxi Controller |
| Acceso | Token Bearer | Host, puerto, nombre de usuario y contraseña del broker MQTT, definidos en el Reduxi Configurator |
| Dirección | Obtiene datos | Lee datos y envía consignas y comandos |
| Ideal para | Paneles, informes e integraciones con datos de controladores, dispositivos, previsiones y precios | Supervisión y control de un controlador en tiempo real |
2 External API (REST)
La External API le da acceso a los datos de sus controladores en la nube de Reduxi. Todos los valores de potencia y energía se entregan en unidades base: W y Wh. Las solicitudes se autorizan con un token Bearer.
- Controladores: lista de controladores, detalles de un controlador y el último estado conocido de sus dispositivos
- Alarmas: alarmas activas de un controlador
- Datos de dispositivos: mediciones por dispositivo, mediciones agregadas por categoría de dispositivo y consultas sobre varios dispositivos
- Tipos de datos: los tipos de datos disponibles para un dispositivo
- Previsiones: datos de previsión por ubicación o por controlador
- Precios: precios del mercado spot del día siguiente, regiones del mercado spot y listas de precios por ubicación
3 MQTT API
La API MQTT conecta un Reduxi Controller con su broker MQTT. El controlador publica sus lecturas y la información de dispositivos y estrategias en topics, y usted le devuelve consignas, comandos y ajustes a través de otros topics. La especificación actual es la versión 1.5 y requiere la versión de software del controlador 20260421084600.
- Controlador: identificador, keep-alive, intervalos de lectura y de keep-alive, ajustes de red
- Dispositivos: lista de dispositivos, información del dispositivo, lecturas y consignas
- Estrategias: lista de estrategias, información, lecturas, parámetros, estado activo y ajustes de EMS externo
- Comandos: actualizar metadatos y reiniciar
La documentación de MQTT se genera desde el punto de vista del Reduxi Controller.
Cuando lee datos de Reduxi MQTT, verá el término "PUB". ¿Por qué PUB? Porque publicamos los datos del Reduxi Controller en el topic.
Cuando establece valores en el Reduxi Controller mediante MQTT, verá el término "SUB". ¿Por qué SUB? Porque nos suscribimos al topic y leemos los datos de él, y aplicamos al Reduxi Controller los valores que usted ha enviado.
Las secciones 4 a 8 muestran cómo configurar el Reduxi Configurator para que el controlador envíe datos a su broker MQTT. Terminan con un ejemplo de lectura de un dispositivo y ajuste de sus consignas.
4 Compatibilidad de versiones MQTT
Admitimos la versión 3. x. Sin embargo, no admitimos la 5. x.
5 Configuración de la interfaz MQTT de Reduxi
Inicie sesión en el Reduxi Controller y vaya a System settings. En System settings, seleccione MQTT v3 y defina los datos del broker MQTT:
- Host (solo dominio/IP, sin mqtts://)
- Puerto
- Nombre de usuario
- Contraseña
Descripción en texto de esta imagen
Captura de pantalla de la página MQTT v3 connection del Reduxi Configurator. Menú izquierdo bajo el logotipo reduxi CONFIGURATOR: Users; Devices; Strategies; System (desplegado, signo menos); Identifier; Network; Open VPN; Connector (desplegado); Cloud; MQTT v3 (seleccionado, en negrita); iFlex; Configuration (contraído, signo más); Distribution System Operators; Time. Encabezado de la página: MQTT v3 connection, icono verde de enlace a la derecha. Tabla de estado: Client: vacío; Host: vacío; Connected: marca verde. Sección del formulario Mqtt connection: Host: mqtt.example.com (gris, estilo de texto de ejemplo); Port: 1883 (gris); Username: vacío; Password: vacío; 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. Botones: Clear, Save.
6 Cliente de Windows (MQTT Explorer)
Puede intentar recopilar datos con MQTT Explorer conectándose al broker MQTT con los siguientes datos:
Puede conectarse al broker MQTT al iniciar una aplicación MQTT Explorer.
Descripción en texto de esta imagen
Captura de pantalla de MQTT Explorer (barra superior: DISCONNECT, cuadro de búsqueda) con el cuadro de diálogo MQTT Connection abierto sobre la ventana principal atenuada. Lista izquierda: botón amarillo de más con la etiqueta Connections; una entrada guardada mqtt.example.com con el texto pequeño mqtt://mqtt.example.com:1883/ (seleccionada). Título del cuadro de diálogo: MQTT Connection, con mqtt://mqtt.example.com:1883/ a su lado. Campos: Name: mqtt.example.com; Validate certificate: interruptor desactivado; Encryption (tls): interruptor desactivado; Protocol: mqtt:// (lista desplegable); Host: mqtt.example.com; Port: 1883; Username: vacío; Password: oculta con puntos, con un icono de ojo para mostrar/ocultar. Botones: DELETE, ADVANCED, SAVE (amarillo), CONNECT (oscuro). En el fondo atenuado se ve parte del panel Topic y un valor JSON con las entradas type POWER_ACTIVE, target FIXED, phaseType null.
7 Comandos
7.1. Actualizar los metadatos
Solicite a Reduxi que vuelva a publicar en MQTT todos los metadatos del sistema, los dispositivos y las estrategias. De lo contrario, solo se publican periódicamente las lecturas y las consignas.
Topic: controllers/controller_unit_id/commands/refresh
Descripción en texto de esta imagen
Captura de pantalla de MQTT Explorer (estado DISCONNECT, cuadro de búsqueda arriba) utilizado para enviar el comando refresh. Árbol de topics a la izquierda: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE con keepAlive = 1734965285703; commands con la entrada refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(cortado); 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 mensajes); 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 mensajes); 18 (1 topic, 2 mensajes); 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 topics, 12 mensajes); 20 (2 topics, 8 mensajes); 27 (seleccionado) 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 mensajes); list = [{"id":8,"typeId":7. A la derecha: panel Topic (insignia 2) con la ruta controllers / ZGFE / strategies / 27; panel Value con History; panel Publish con Topic: controllers/ZGFE/commands/refresh; formato raw, xml, json con json seleccionado; cuerpo del mensaje vacío; botón PUBLISH con una flecha roja que lo señala.
7.2. Reiniciar
Reinicia el Reduxi Controller.
Topic: controllers/controller_unit_id/commands/reboot
Descripción en texto de esta imagen
Captura de pantalla de la aplicación MQTT Explorer (estado DISCONNECT, cuadro de búsqueda arriba) utilizada para enviar el comando reboot. Árbol de topics a la izquierda: $SYS (48 topics, 406 mensajes); controllers; devices (29 topics, 865 mensajes); strategies (38 topics, 884 mensajes); commands (0 topics, 1 mensaje); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (fila seleccionada); settings (2 topics, 2 mensajes); keepAlive = 1675762462861. A la derecha: una vista previa de un mensaje JSON arriba con softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Panel Publish con Topic: /controllers/ … /commands/reboot, con un corchete rojo al final del campo del topic. Opciones de formato raw, xml, json: json está seleccionado. El cuerpo del mensaje está vacío. El botón PUBLISH está rodeado en rojo. QoS: 0; retain: casilla sin marcar.
8 Consignas
Las consignas controlan la potencia o la corriente de un dispositivo. El Reduxi Controller publica las consignas activas de cada dispositivo y usted establece otras nuevas mediante el topic /set correspondiente.
8.1. Ver todas las consignas activas del dispositivo
Topic: controllers/controller_unit_id/devices/device_id/setpoint
Descripción en texto de esta imagen
Captura de pantalla de MQTT Explorer (estado DISCONNECT, cuadro de búsqueda arriba) que muestra la consigna del dispositivo 15. Árbol de topics a la izquierda: $SYS (48 topics, 862 mensajes); controllers; devices; 13 (3 topics, 235 mensajes); 14 (3 topics, 235 mensajes); 15 desplegado con las entradas readout = {"time":1675762671666,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (fila seleccionada, marcada con un corchete rojo); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; después 18, 8, 9, 10, 11, 12 (3 topics, 233 mensajes cada uno); 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 mensajes); commands (0 topics, 1 mensaje); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 topics, 2 mensajes); keepAlive = 1675762644772. A la derecha, Topic / controllers / / devices / 15 / setpoint. Panel Value, QoS: 0, 02/07/2023 10:37:53 AM, con el botón de vista con formato rodeado en rojo y el valor JSON enmarcado con un corchete rojo: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (continúa). History: 20.
8.2. Establecer consignas para el dispositivo
Topic: controllers/controller_unit_id/devices/device_id/setpoint/set
Descripción en texto de esta imagen
Captura de pantalla de MQTT Explorer (estado DISCONNECT, cuadro de búsqueda arriba) utilizado para publicar una consigna para el dispositivo 15. Árbol de topics a la izquierda: $SYS (48 topics, 1192 mensajes); controllers; devices (resaltado); 13 (3 topics, 341 mensajes); 14 (3 topics, 341 mensajes); 15 desplegado 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".} (fila seleccionada); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 topics, 339 mensajes); 8 (3 topics, 340 mensajes, resaltado); 9, 10, 11, 12 (3 topics, 339 mensajes cada uno); 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 mensajes); commands (0 topics, 1 mensaje); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 topics, 2 mensajes); keepAlive = 1675762764833. A la derecha: insignia History 20, después el panel Publish. Topic: /controllers/ … /devices/15/setpoint/set; el campo del topic está marcado con corchetes rojos y la palabra set está subrayada en rojo. Formato raw, xml, json: json seleccionado. Cuerpo del mensaje, enmarcado con un corchete rojo: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. Botón PUBLISH rodeado en rojo. QoS: 0; retain sin marcar. Debajo hay una sección History.
8.2.1. Ejemplo 1
Establezca la potencia activa en -1 kW (exportación) en todas las fases durante 15 segundos.
{
"values": [
{
"action": "SET",
"type": "POWER_ACTIVE",
"target": "FIXED",
"phaseType": null,
"value": 1000,
"priority": 10000,
"validForTime": 15000
}
]
}
8.2.2. Ejemplo 2
Limite la corriente máxima a 10 A en la fase L2 durante 30 segundos.
{
"values": [
{
"action": "SET",
"type": "CURRENT",
"target": "MAX",
"phaseType": "L2",
"value": 10,
"priority": 10000,
"validForTime": 30000
}
]
}