Monitorar desconexões e eventos de energia
Caso de uso
Use este padrão quando seu backend precisar atualizar disponibilidade, disparar alertas ou registrar sinais suportados de mudança de energia sem sondar repetidamente o estado do dispositivo.
device.connection.onlineedevice.connection.offlinedescrevem mudanças de conexão.device.power.lostreporta um sinal de queda de energia dos dispositivos que oferecem esse sinal.device.power.restoredreporta a energia restaurada, mas não significa que a conexão de rede esteja disponível.- Nem todos os modelos de dispositivo têm o mesmo comportamento de detecção de energia. Verifique a definição de tipo de dispositivo e a documentação do dispositivo entregue antes de prometer esses alertas em um produto. Se nenhuma capacidade explícita estiver documentada, não presuma suporte.
Fluxo recomendado
O WebSocket oferece notificações oportunas, mas não é um sistema de registro permanente. Mantenha o estado atual no seu próprio serviço e restaure-o a partir do REST após qualquer lacuna de eventos.
Implementação passo a passo
- Construa o estado inicial da conta com Listar dispositivos (em inglês).
- Revise Listar definições de tipo de dispositivo (em inglês) e a documentação do dispositivo entregue antes de ativar alertas ou interface específica de energia. Uma lista genérica de operações não é prova de que exista detecção de energia.
- Crie um ticket de WebSocket (em inglês), conecte e inicie o Ping/Pong do protocolo mais
session.ping. - Com
device.connection.offline, pare de apresentar o dispositivo como controlável e registreoccurredAt. - Com
device.connection.online, marque a conectividade como restaurada, mas não presuma que todo o estado de periféricos já está sincronizado. Atualize o dispositivo quando precisar do estado atual. - Com
device.power.lost, persista o evento e dispare o alerta. Comdevice.power.restored, você pode fechar o alerta de energia, mas aguardedevice.connection.onlineantes de tratar o dispositivo como controlável. - Use apenas o topic estruturado e as marcas de tempo para os eventos de energia. Não analise nem ramifique com base no texto bruto do firmware.
- Após reconectar, use REST para restaurar a base da conta e consulte apenas os dispositivos críticos que exijam confirmação imediata.
Interfaces e eventos principais
| Finalidade | Referência |
|---|---|
| Base atual da conta | Listar dispositivos (em inglês) |
| Confirmar um dispositivo | Consultar dispositivo (em inglês) |
| Eventos de conexão e desconexão | Eventos de conexão de dispositivo (em inglês) |
| Semântica de queda e restauração de energia | Eventos de energia de dispositivo (em inglês) |
| Heartbeat e recuperação | Heartbeat e reconexão (em inglês) |
Falhas e recuperação
- Detecte conexões fechadas e timeouts de heartbeat, e reconecte com backoff exponencial limitado e jitter aleatório.
- Nunca reutilize um
wsTicket; crie um novo imediatamente antes de cada tentativa de conexão. - Os eventos não são reproduzidos. Após reconectar, reconstrua o estado atual em vez de assumir que nenhum evento ocorreu.
- A entrega de eventos pode ser duplicada em torno de tentativas ou reconexões. Torne os manipuladores idempotentes usando o topic disponível, o
deviceId, as marcas de tempo e o estado resultante; não dependa de um campo que o contrato do evento não define. - Eventos de energia e de conexão não têm ordem garantida, e pode chegar apenas uma das duas categorias. Não infira mudanças de energia a partir de
online/offline.
Considerações para produção
- Armazene o momento de recebimento do evento separadamente do
occurredAtdo dispositivo, para observabilidade. - Defina regras de supressão e recuperação de alertas para que tempestades de reconexão não gerem incidentes duplicados.
- Trate o WebSocket como um canal de atualização ao vivo e o REST como o caminho de recuperação de estado.
- Confirme o suporte a eventos de energia durante o onboarding do dispositivo. Não presuma suporte só porque outro tipo de dispositivo reporta esse evento.