Guias de API da Reduxi
Ligue os seus próprios sistemas à Reduxi: a External API disponibiliza dados da cloud através de HTTPS e a API MQTT dá-lhe acesso direto a um Reduxi Controller através do seu broker MQTT.
1 De que guia de API precisa?
A Reduxi disponibiliza dois guias de API. Use a External API para obter da cloud da Reduxi dados dos seus controladores, dispositivos, previsões e preços. Use a API MQTT para ler valores de um Reduxi Controller e enviar-lhe valores de referência e comandos através do seu próprio broker MQTT.
| External API | MQTT API | |
|---|---|---|
| Tipo | API REST sobre HTTPS (OpenAPI 3.0) | Mensagens MQTT (versão 3.x) no seu broker MQTT |
| Origem dos dados | Cloud da Reduxi | Reduxi Controller |
| Acesso | Token Bearer | Host, porta, nome de utilizador e palavra-passe do broker MQTT, definidos no Reduxi Configurator |
| Direção | Obtém dados | Lê dados e envia valores de referência e comandos |
| Indicada para | Dashboards, relatórios e integrações com dados de controladores, dispositivos, previsões e preços | Monitorização e controlo de um controlador em tempo real |
2 External API (REST)
A External API dá-lhe acesso aos dados dos seus controladores na cloud da Reduxi. Todos os valores de potência e energia são fornecidos em unidades de base: W e Wh. Os pedidos são autorizados com um token Bearer.
- Controladores: lista de controladores, detalhes de um controlador e o último estado conhecido dos seus dispositivos
- Alarmes: alarmes ativos de um controlador
- Dados dos dispositivos: medições por dispositivo, medições agregadas por categoria de dispositivo e consultas a vários dispositivos
- Tipos de dados: os tipos de dados disponíveis para um dispositivo
- Previsões: dados de previsão por localização ou por controlador
- Preços: preços do mercado spot do dia seguinte, regiões do mercado spot e listas de preços por localização
3 MQTT API
A API MQTT liga um Reduxi Controller ao seu broker MQTT. O controlador publica as suas leituras e as informações sobre dispositivos e estratégias em tópicos (topics), e o utilizador envia valores de referência, comandos e definições de volta através de outros tópicos. A especificação atual é a versão 1.5 e requer a versão de software do controlador 20260421084600.
- Controlador: identificador, keep-alive, intervalos de leitura e de keep-alive, definições de rede
- Dispositivos: lista de dispositivos, informações do dispositivo, leituras e valores de referência
- Estratégias: lista de estratégias, informações, leituras, parâmetros, estado ativo e definições do EMS externo
- Comandos: atualizar metadados e reiniciar
A documentação MQTT é gerada do ponto de vista do Reduxi Controller.
Quando lê do Reduxi MQTT, vê o termo "PUB". Porquê PUB? Porque publicamos os dados do Reduxi Controller no tópico.
Quando define valores no Reduxi Controller através de MQTT, vê o termo "SUB". Porquê SUB? Porque subscrevemos o tópico e lemos os dados dele, aplicando ao Reduxi Controller os valores que enviou.
As secções 4 a 8 mostram como configurar o Reduxi Configurator para que o controlador envie dados para o seu broker MQTT. Terminam com um exemplo de leitura de um dispositivo e definição dos seus valores de referência.
4 Suporte de versões MQTT
Suportamos a versão 3. x. No entanto, não suportamos a 5. x.
5 Configuração da interface MQTT do Reduxi
Inicie sessão no dispositivo Reduxi Controler e aceda às definições do sistema. Em System settings, selecione MQTT v3 e defina os dados do broker MQTT:
- Host (apenas domínio/IP, sem mqtts://)
- Porta
- Nome de utilizador
- Palavra-passe
Descrição em texto desta imagem
Captura de ecrã da página MQTT v3 connection do Reduxi Configurator. Menu esquerdo sob o logótipo reduxi CONFIGURATOR: Users; Devices; Strategies; System (expandido, sinal de menos); Identifier; Network; Open VPN; Connector (expandido); Cloud; MQTT v3 (selecionado, a negrito); iFlex; Configuration (recolhido, sinal de mais); Distribution System Operators; Time. Cabeçalho da página: MQTT v3 connection, ícone verde de ligação à direita. Tabela de estado: Client: vazio; Host: vazio; Connected: visto verde. Secção do formulário Mqtt connection: Host: mqtt.example.com (cinzento, estilo de texto de exemplo); Port: 1883 (cinzento); Username: vazio; Password: vazio; 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. Botões: Clear, Save.
6 Cliente Windows (MQTT Explorer)
Pode tentar recolher dados com o MQTT Explorer, ligando-se ao broker MQTT com os seguintes dados:
Pode ligar-se ao broker MQTT ao iniciar uma aplicação MQTT Explorer.
Descrição em texto desta imagem
Captura de ecrã do MQTT Explorer (barra superior: DISCONNECT, caixa de pesquisa) com a caixa de diálogo MQTT Connection aberta sobre a janela principal esbatida. Lista à esquerda: botão amarelo de mais com a etiqueta Connections; uma entrada guardada mqtt.example.com com o texto pequeno mqtt://mqtt.example.com:1883/ (selecionada). Título da caixa de diálogo: MQTT Connection, com mqtt://mqtt.example.com:1883/ ao lado. Campos: Name: mqtt.example.com; Validate certificate: interruptor desativado; Encryption (tls): interruptor desativado; Protocol: mqtt:// (lista pendente); Host: mqtt.example.com; Port: 1883; Username: vazio; Password: ocultada com pontos, com um ícone de olho para mostrar/ocultar. Botões: DELETE, ADVANCED, SAVE (amarelo), CONNECT (escuro). No fundo esbatido, vê-se parte do painel Topic e um valor JSON com as entradas type POWER_ACTIVE, target FIXED, phaseType null.
7 Comandos
7.1. Atualizar metadados
Peça ao Reduxi que volte a publicar no MQTT todos os metadados sobre o sistema, os dispositivos e as estratégias. Caso contrário, apenas as leituras e os valores de referência são publicados periodicamente.
Topic: controllers/controller_unit_id/commands/refresh
Descrição em texto desta imagem
Captura de ecrã do MQTT Explorer (estado DISCONNECT, caixa de pesquisa no topo) utilizado para enviar o comando refresh. Árvore de tópicos à esquerda: e8c1fe29.ala.eu-central-1.emqxsl.com; controllers; ZGFE com keepAlive = 1734965285703; commands com a entrada refresh; identifier = {"unitId":"ZGFE","unitIdFormatted":"ZGE","boardModel":"REDUXI_1","CPUSerial":"16516642034211ad","EMMCSerial":"4.(cortado); settings; interval: readout = 15000, keepAlive = 60000; devices: 2 com 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 tópico, 2 mensagens); 12 com info = {"id":12,"name":"Iskraemeco AM550","typeId":16,"type":{"id":16,"categoryId":1,"category":{"id":1,"name":"Energy meter","enumeration":"ENERGY_METER"; 17 (1 tópico, 2 mensagens); 18 (1 tópico, 2 mensagens); strategies: 8 com info = {"id":8,"typeId":7,"type":{"id":7,"name":"1-phase current based ON/OFF regulation","enumeration":"DISCRETE_CURRENT_PHASE_1"}; parameters (3 tópicos, 12 mensagens); 20 (2 tópicos, 8 mensagens); 27 (selecionado) com info = {"id":27,"typeId":8,"type":{"id":8,"name":"Energy manager coordinator for PV, EVSE, battery and heat pump","enumeration":"UMBRELLA"}; parameters (1 tópico, 4 mensagens); list = [{"id":8,"typeId":7. Lado direito: painel Topic (distintivo 2) com o caminho controllers / ZGFE / strategies / 27; painel Value com History; painel Publish com Topic: controllers/ZGFE/commands/refresh; formato raw, xml, json com json selecionado; corpo da mensagem vazio; botão PUBLISH com uma seta vermelha a apontar para ele.
7.2. Reiniciar
Reinicia o Reduxi Controller.
Topic: controllers/controller_unit_id/commands/reboot
Descrição em texto desta imagem
Captura de ecrã da aplicação MQTT Explorer (estado DISCONNECT, caixa de pesquisa no topo) utilizada para enviar o comando reboot. Árvore de tópicos à esquerda: $SYS (48 tópicos, 406 mensagens); controllers; devices (29 tópicos, 865 mensagens); strategies (38 tópicos, 884 mensagens); commands (0 tópicos, 1 mensagem); identifier = {"unitId","unitIdFormatted","CPUSerial":.} (linha selecionada); settings (2 tópicos, 2 mensagens); keepAlive = 1675762462861. Lado direito: uma pré-visualização de mensagem JSON no topo com softwareVersion "20230207091611", hwVersion "0", hasWifiModule false, dso {.}; History: 1. Painel Publish com Topic: /controllers/ … /commands/reboot, com um parêntese vermelho no fim do campo do tópico. Opções de formato raw, xml, json: json está selecionado. O corpo da mensagem está vazio. O botão PUBLISH está rodeado a vermelho. QoS: 0; retain: caixa de seleção desassinalada.
8 Valores de referência
Os valores de referência controlam a potência ou a corrente de um dispositivo. O Reduxi Controller publica os valores de referência ativos de cada dispositivo e o utilizador define novos através do tópico /set correspondente.
8.1. Ver todos os valores de referência ativos do dispositivo
Topic: controllers/controller_unit_id/devices/device_id/setpoint
Descrição em texto desta imagem
Captura de ecrã do MQTT Explorer (estado DISCONNECT, caixa de pesquisa no topo) a mostrar o valor de referência do dispositivo 15. Árvore de tópicos à esquerda: $SYS (48 tópicos, 862 mensagens); controllers; devices; 13 (3 tópicos, 235 mensagens); 14 (3 tópicos, 235 mensagens); 15 expandido com as 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".} (linha selecionada, assinalada com um parêntese vermelho); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; depois 18, 8, 9, 10, 11, 12 (3 tópicos, 233 mensagens cada); 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 tópicos, 2104 mensagens); commands (0 tópicos, 1 mensagem); identifier = {"unitId","unitIdFormatted","CPUSerial"; settings (2 tópicos, 2 mensagens); keepAlive = 1675762644772. Lado direito, Topic / controllers / / devices / 15 / setpoint. Painel Value, QoS: 0, 02/07/2023 10:37:53 AM, com o botão da vista formatada rodeado a vermelho e o valor JSON assinalado com um parêntese vermelho: { "deviceId": 15, "values": [ { "action": "NONE", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": "L1", "value": 0, "priority": 100, "validForTime": 28571 }, {. (continua). History: 20.
8.2. Definir valores de referência para o dispositivo
Topic: controllers/controller_unit_id/devices/device_id/setpoint/set
Descrição em texto desta imagem
Captura de ecrã do MQTT Explorer (estado DISCONNECT, caixa de pesquisa no topo) utilizado para publicar um valor de referência para o dispositivo 15. Árvore de tópicos à esquerda: $SYS (48 tópicos, 1192 mensagens); controllers; devices (destacado); 13 (3 tópicos, 341 mensagens); 14 (3 tópicos, 341 mensagens); 15 expandido com readout = {"time":1675762794195,"values":[{"deviceId":15,"dataTypeId":174,"dataTypeEnum":"VOLTAGE_L1"; setpoint = {"deviceId":15,"values":[{"action":"NONE","type":"POWER_ACTIVE","target":"FIXED","phaseType":"L1".} (linha selecionada); info = {"id":15,"name":"Baterija","typeId":14,"type":{"id":14,"name":"Victron Energy MultiPlus II","enumeration":"BATTE; 18 (3 tópicos, 339 mensagens); 8 (3 tópicos, 340 mensagens, destacado); 9, 10, 11, 12 (3 tópicos, 339 mensagens cada); list = [{"id":8,"name":"Sončna elektrarna","typeId":7,"type":{"id":7,"name":"SolarEdge"; types = [{"id":40,"name":"ABB","enumeration":"CHARGER_ABB"; strategies (38 tópicos, 3062 mensagens); commands (0 tópicos, 1 mensagem); identifier = {"unitId","unitIdFormatted","CPUSerial":; settings (2 tópicos, 2 mensagens); keepAlive = 1675762764833. Lado direito: distintivo History 20 e depois o painel Publish. Topic: /controllers/ … /devices/15/setpoint/set; o campo do tópico está assinalado com parênteses vermelhos e a palavra set está sublinhada a vermelho. Formato raw, xml, json: json selecionado. Corpo da mensagem, assinalado com um parêntese vermelho: { "values": [ { "action": "SET", "type": "POWER_ACTIVE", "target": "FIXED", "phaseType": null, "value": 1000, "priority": 10000, "validForTime": 60000 } ] }. O botão PUBLISH está rodeado a vermelho. QoS: 0; retain desassinalado. Por baixo há uma secção History.
8.2.1. Exemplo 1
Definir a potência ativa para -1 kW (exportação) em todas as fases durante 15 segundos.
{
"values": [
{
"action": "SET",
"type": "POWER_ACTIVE",
"target": "FIXED",
"phaseType": null,
"value": 1000,
"priority": 10000,
"validForTime": 15000
}
]
}
8.2.2. Exemplo 2
Limitar a corrente máxima a 10 A na fase L2 durante 30 segundos.
{
"values": [
{
"action": "SET",
"type": "CURRENT",
"target": "MAX",
"phaseType": "L2",
"value": 10,
"priority": 10000,
"validForTime": 30000
}
]
}