Controlar relés com segurança

Caso de uso

Use este padrão quando operações de relé afetam equipamentos reais e quem as chama precisa lidar com tentativas, resultados incertos e vários canais de relé sem gerar efeitos colaterais duplicados.

Fluxo recomendado

Envie todas as mudanças de relé de um dispositivo em um único array relays. Um único lote se torna um único comando de dispositivo e evita transmissões consecutivas que o dispositivo pode não processar de forma confiável.

Implementação passo a passo

1. Use Listar definições de tipo de dispositivo (em inglês) para confirmar device.relay.set, o número de relés e as ações permitidas.
2. Construa o array de relés desejado. Use um único item para controlar um canal, ou vários índices distintos para uma mudança coordenada.
3. Gere um Idempotency-Key novo, de propriedade do chamador, para esta intenção de operação.
4. Chame Executar comando de relé (em inglês) com device:control.
5. Leia data.command.id e data.command.status. Se o status for SENT, use Consultar resultado de comando (em inglês) até chegar a um estado terminal ou ao seu prazo limitado de sondagem.
6. Use data.state quando a confirmação do dispositivo o incluir. Não dispare outra atualização apenas para preencher um campo opcional.
7. Se o resultado for TIMEOUT, leia o estado atual do dispositivo antes de decidir se é seguro iniciar outra operação.

Ciclo de vida do comando

Resultado	Significado	Ação do cliente
HTTP 202 + COMMAND_ACCEPTED	A plataforma aceitou a requisição; não é um status de comando independente	Leia data.command.status e mantenha o ID do comando
SENT	O comando ainda está aguardando confirmação	Consulte o resultado com sondagem limitada
SUCCESS	O dispositivo confirmou a execução	Aplique o estado retornado quando presente
FAILED	A plataforma confirmou que o comando não foi concluído	Pare as tentativas automáticas e trate a falha
TIMEOUT	Nenhuma confirmação final chegou dentro da janela de espera	Não presuma que o dispositivo executou ou não; leia primeiro o estado atual

Interfaces principais

• Executar comando de relé (em inglês)
• Consultar resultado de comando (em inglês)
• Consultar estado do dispositivo (em inglês)
• Limites de taxa e idempotência (em inglês)
• Controlar relés via WebSocket (em inglês)

Falhas e recuperação

• Se o resultado HTTP for desconhecido porque a rede falhou, tente novamente a requisição idêntica com o mesmo Idempotency-Key.
• Após um 429 RATE_LIMITED, aguarde o Retry-After e tente novamente a mesma operação com a chave original.
• Nunca reutilize uma chave para um dispositivo, array de relés ou ação diferentes; isso retorna IDEMPOTENCY_CONFLICT.
• Após um TIMEOUT, atualize primeiro o estado. Se ainda for desconhecido, exija uma decisão de negócio antes de enviar outra operação física.
• Repetir JOG ou outras ações no equipamento pode produzir efeitos colaterais reais mesmo quando a resposta anterior foi perdida. Projete confirmações e salvaguardas de operador de acordo.

Considerações para produção

• Armazene juntos a chave de idempotência, o ID do comando, o array de relés solicitado, o status e o requestId para auditoria e recuperação.
• Serialize ou coordene em sua aplicação as operações direcionadas ao mesmo dispositivo.
• Use sondagem de resultado limitada e respeite os limites de taxa.
• Valide o canal de destino e a segurança física antes de permitir controle a partir de uma interface ou regra de automação.

Próximos passos

• Evento de mudança de estado do dispositivo (em inglês)
• Erros de recursos e comandos (em inglês)
• Construir um painel de monitoramento de dispositivos