Controle MQTT agendado
O controle MQTT programado é destinado a mensagens agendadas com antecedência. Para controle ao vivo, consulte Controle MQTT Ao Vivo em vez disso.
Este guia ajudará você a configurar o MQTT em seu Sofar EMS para controlar e monitorar remotamente instalações de baterias e painéis solares.
O que você precisa
- Sofar EMS com conectividade à internet.
- Credenciais MQTT: Isso pode ser solicitado enviando um e-mail para support@eniris.be.
- Ambiente de desenvolvimento Python (ou qualquer outro cliente MQTT). Este guia usa um exemplo básico escrito em Python para ajudá-lo a começar com MQTT e o envio de comandos. Recomendamos usar Python pela facilidade de uso, mas qualquer outro cliente MQTT é suportado.
Informações extras
O MQTT é um protocolo de comunicação rápido pela internet. É um sistema de mensagens de publicação/assinatura, que permite uma conexão direta entre sua máquina e o Sofar EMS. Seus ativos são classificados em grupos de solar, bateria, EV e HVAC. No momento, esta integração permite controle por grupo, não por dispositivo.
Configuração de primeira vez (Ponto de partida para novos usuários)
Eu tenho um Sofar EMS que gostaria de configurar para Controle Remoto MQTT.
1. Verifique sua rede
Certifique-se de que sua rede permite o tráfego de rede MQTT pela porta 1883. Você pode fazer isso usando o comando:
nc -zv mqtt.eniris.be 1883
Quando este comando não está disponível, você pode alternativamente baixar e executar este código python.
Quando estiver em dúvida, consulte seu engenheiro de rede ou use temporariamente o hotspot 4G/5G do seu telefone quando ocorrerem erros de conexão.
Quando a porta 1883 não estiver acessível a partir da sua rede, oferecemos um backup na porta 80. Isso pode ser configurado em seu cliente MQTT em uma etapa posterior deste manual.
2. Adicione seus dispositivos
Login na interface de comissionamento e certifique-se de que os dispositivos estão adicionados ao Sofar EMS.
3. Adicione o sinal externo MQTT
4. Habilite o sinal remoto MQTT
Selecione todos os dispositivos que você gostaria de incluir no Controle Remoto MQTT.
5. O sinal remoto foi adicionado
A interface de Controle Remoto MQTT foi ativada no Sofar EMS.
Agora estamos prontos para enviar alguns comandos básicos usando um exemplo simples. A coluna Status informa se algum comando está ativo.
Script de demonstração em Python
Um bom ponto de partida seria testar sua nova integração configurada com um exemplo simples.
Este código de teste faz um trabalho simples de enviar continuamente o seguinte cronograma:
- Bateria: Carregar a 5 kW por 15 minutos em 10 minutos
- Solar: Definir a potência para 0 kW por uma hora em 30 minutos
O Sofar EMS responde com uma mensagem de confirmação contendo o identificador exclusivo do cronograma ou uma mensagem de erro.
Em seguida, buscamos o próximo cronograma para ambos os tipos de dispositivos, confirmando que o comando foi bem-sucedido.
Por favor, baixe o arquivo abaixo em seu IDE Python preferido. Preencha seu número de série e credenciais MQTT e execute o script:
Quando isso for bem-sucedido, você pode continuar enviando outros tipos de mensagens. Todas as mensagens são descritas abaixo.
Documentação MQTT para Envio de Comandos
Esta seção detalha o formato de mensagem MQTT e os requisitos de carga útil para configurar o controle agendado de dispositivos dentro da rede do Sofar EMS.
Tópicos MQTT
- Tópico de Assinatura:
standard1/rp_one_s/remoteScheduleMetrics/<controller SN> - Tópico de Feedback:
standard1/outbound/remoteScheduleMetrics/feedback/<controller SN>
Onde <controller SN> deve ser substituído pelo número de série real do Sofar EMS que você pretende controlar.
Tipos de Mensagens MQTT
1. Definir Cronograma (set_schedule)
Cria um novo cronograma para um tipo de dispositivo.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "set_schedule",
"fields": {
"device_type": "<Device Type>",
"node_id": "<Node ID>" (Opcional),
"start_time": <Unix Timestamp>,
"end_time": <Unix Timestamp>,
"policy": "<Policy>",
"power_setpoint_w": <Setpoint in watts>,
"site_import": <Site Import in Watts>,
"site_export": <Site Export in Watts>,
"remove_overlap": <True/False> (Opcional) (default=False),
"tag": <Tag String> (Opcional) (default=None)
}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "set_schedule_ack",
"state": {
"schedule_id": <Schedule ID>,
"deleted_ids": <SIDs deletados se remove_overlap=True>,
"tag": <Tag String> (default=None)
},
"responseCode": 0
}
}
2. Definir Cronogramas (set_schedules)
Cria múltiplos novos cronogramas.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "set_schedules",
"fields":
"0": '{
"device_type": "<Device Type>",
"node_id": "<Node ID>" (Opcional),
"start_time": <Unix Timestamp>,
"end_time": <Unix Timestamp>,
"policy": "<Policy>",
"power_setpoint_w": <Setpoint in watts>,
"site_import": <Site Import in Watts>,
"site_export": <Site Export in Watts>,
"remove_overlap": <True/False> (Opcional) (default=False)
}',
"1": '{
"device_type": "<Device Type>",
"node_id": "<Node ID>" (Opcional),
"start_time": <Unix Timestamp>,
"end_time": <Unix Timestamp>,
"policy": "<Policy>",
"power_setpoint_w": <Setpoint in watts>,
"site_import": <Site Import in Watts>,
"site_export": <Site Export in Watts>,
"remove_overlap": <True/False> (Opcional) (default=False)
}',
...
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "set_schedules_ack",
"state": {
"schedule_ids": <Schedule IDs>,
"deleted_ids": <Schedulde IDs deletados se remove_overlap=True>
},
"responseCode": 0
}
}
3. Obter Cronograma (get_schedule)
Recupera um cronograma específico por ID.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_schedule",
"fields": {
"id": <Schedule ID>
}
}
Resposta:
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "get_schedule_ack",
"state": <Schedule>,
"responseCode": 0
}
}
4. Obter Agenda Ativa (get_active_schedule)
Recupera a agenda atualmente ativa para um tipo de dispositivo.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_active_schedule",
"fields": {
"device_type": "<Device Type>",
"node_id": "<Node ID>" (Opcional),
}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "get_active_schedule_ack",
"state": <Schedule>,
"responseCode": 0
}
}
5. Obter Próxima Agenda (get_next_schedule)
Recupera a próxima agenda a ser realizada para um tipo de dispositivo.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_next_schedule",
"fields": {
"device_type": "<Device Type>",
"node_id": "<Node ID>" (Opcional),
}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "get_next_schedule_ack",
"state": <Schedule>,
"responseCode": 0
}
}
6. Obter Agendas (get_schedules)
Recupera todas as agendas para uma data específica.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_schedules",
"fields": {
"date": "<Date String of Format dd/mm/yyyy>"
}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "get_schedules_ack",
"state": {
"schedules": [<Schedule>, ...]
},
"responseCode": 0
}
}
7. Obter Agendas Futuras (get_future_schedules)
Recupera todas as agendas futuras.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_future_schedules",
"fields": {}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "get_future_schedules_ack",
"state": {
"schedules": [<Schedule>, ...]
},
"responseCode": 0
}
}
8. Remover Agenda (remove_schedule)
Remove uma agenda específica pelo ID.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "remove_schedule",
"fields": {
"id": <Schedule ID>
}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "remove_schedule_ack",
"state": "Agenda <Schedule ID> removida com sucesso",
"responseCode": 0
}
}
9. Obter Feedback do Site (get_feedback)
Recupera feedback detalhado sobre o estado do sistema.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_feedback",
"fields": {
"device": <Device (node) level>
}
}
Resposta (Sucesso):
Estrutura de Payload de Feedback
10. Topologia do Site (get_toplogy)
Obtém a topologia do site.
{
"extraTags": {
"nodeId": "<Controller SN>_site_0"
},
"time": <Unix Timestamp>,
"message_type": "get_topology",
"fields": {}
}
Resposta (Sucesso):
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "get_topology_ack",
"state": {
"nodeId": <nodeId>,
"nodeType": <nodeType>,
"nomCurrent": <nominalCurrent>
"children": [{<ChildObject>}]
},
"responseCode": 0
}
}
Formato Padrão de Resposta de Agenda
{
"id": <Schedule ID>,
"device_type": "<Device Type>",
"node_id": "<Node ID>" (Opcional),
"start_time": <Unix Timestamp>,
"end_time": <Unix Timestamp>,
"policy": "<Schedule Policy>",
"power_setpoint_w": <Setpoint in watts>,
"created_at": <Unix Timestamp>
}
Tipos de Componentes e Políticas
Para detalhes sobre componentes disponíveis e políticas que podem ser agendadas, consulte a seção Componentes e Políticas MQTT na documentação do Controle MQTT ao Vivo.
As agendas específicas para dispositivos podem ser enviadas usando o campo opcional node_id, referindo-se ao ID do nó do dispositivo controlável.
Tratamento de Erros
Todas as mensagens podem retornar uma resposta de erro com responseCode: 1 quando ocorre um erro:
{
"requestTime": <Unix Timestamp>,
"time": <Unix Timestamp>,
"siteNodeId": "<Controller SN>_site_0",
"data": {
"message_type": "<Message Type>_ack",
"error": <Error Body>,
"responseCode": 1
}
}
Quando um erro não relacionado ocorre, o tipo de mensagem será (general_error).
Erros comuns incluem:
- Sobreposição de agenda com agendas existentes
- Intervalo de tempo inválido
- Tipo de dispositivo não encontrado
- ID de agenda não encontrado
- Política inválida para o tipo de dispositivo
Regras de Gerenciamento de Agendas
- Regras de Sobreposição
- As agendas não podem se sobrepor para o mesmo tipo de dispositivo
- As agendas não podem se sobrepor para o mesmo dispositivo
- As agendas para o mesmo dispositivo e tipo de dispositivo não podem se sobrepor
- Agendas existentes e sobrepostas serão excluídas se a variável
remove_overlapestiver definida comoTrueao criar uma nova agenda.
- Cada agenda deve ter:
- Um tipo de dispositivo válido
- Um horário de início (timestamp Unix)
- Um horário de término (timestamp Unix)
- Uma política (que corresponda às políticas disponíveis para o tipo de dispositivo)
- Um ponto de ajuste de potência (para políticas que o exigem)
- O horário de início deve ser antes do horário de término
- Se o horário de início estiver no passado, ele é automaticamente alterado para começar agora
- As agendas só podem ser excluídas se ainda não tiverem iniciado. Agendas ativas não podem ser excluídas.
- As agendas podem ser definidas para diferentes tipos de dispositivos de forma independente
- O sistema aplica automaticamente a política apropriada quando uma agenda se torna ativa