Controlar relés con seguridad

Caso de uso

Usa este patrón cuando las operaciones de relé afecten a equipos reales y quien las invoca deba manejar reintentos, resultados inciertos y varios canales de relé sin generar efectos secundarios duplicados.

Flujo recomendado

Envía todos los cambios de relé de un dispositivo en un único array relays. Un solo lote se convierte en un único comando de dispositivo y evita transmisiones consecutivas que el dispositivo podría no procesar de forma fiable.

Implementación paso a paso

1. Usa Listar definiciones de tipo de dispositivo (en inglés) para confirmar device.relay.set, el número de relés y las acciones permitidas.
2. Construye el array de relés deseado. Usa un solo elemento para controlar un canal, o varios índices distintos para un cambio coordinado.
3. Genera un Idempotency-Key nuevo, propio del llamador, para esta intención de operación.
4. Llama a Ejecutar comando de relé (en inglés) con device:control.
5. Lee data.command.id y data.command.status. Si el estado es SENT, usa Consultar resultado de comando (en inglés) hasta llegar a un estado terminal o a tu plazo acotado de sondeo.
6. Usa data.state cuando la confirmación del dispositivo lo incluya. No lances otra actualización solo para rellenar un campo opcional.
7. Si el resultado es TIMEOUT, lee el estado actual del dispositivo antes de decidir si es seguro lanzar otra operación.

Ciclo de vida del comando

Resultado	Significado	Acción del cliente
HTTP 202 + COMMAND_ACCEPTED	La plataforma aceptó la petición; no es un estado de comando independiente	Lee data.command.status y conserva el ID del comando
SENT	El comando sigue esperando confirmación	Consulta el resultado con sondeo acotado
SUCCESS	El dispositivo confirmó la ejecución	Aplica el estado devuelto si está presente
FAILED	La plataforma confirmó que el comando no se completó	Detén los reintentos automáticos y gestiona el fallo
TIMEOUT	No llegó ninguna confirmación final dentro de la ventana de espera	No des por hecho que el dispositivo lo ejecutó o no; lee primero el estado actual

Interfaces clave

• Ejecutar comando de relé (en inglés)
• Consultar resultado de comando (en inglés)
• Consultar estado del dispositivo (en inglés)
• Límites de tasa e idempotencia (en inglés)
• Controlar relés por WebSocket (en inglés)

Fallos y recuperación

• Si el resultado HTTP es desconocido porque falló la red, reintenta la petición idéntica con el mismo Idempotency-Key.
• Tras un 429 RATE_LIMITED, espera lo que indique Retry-After y reintenta la misma operación con la clave original.
• No reutilices nunca una clave para un dispositivo, array de relés o acción distintos; eso devuelve IDEMPOTENCY_CONFLICT.
• Tras un TIMEOUT, actualiza primero el estado. Si sigue sin conocerse, exige una decisión de negocio antes de enviar otra operación física.
• Repetir JOG u otras acciones sobre el equipo puede producir efectos secundarios reales aunque la respuesta anterior se haya perdido. Diseña las confirmaciones y las salvaguardas del operador en consecuencia.

Consideraciones para producción

• Guarda juntos la clave de idempotencia, el ID del comando, el array de relés solicitado, el estado y el requestId para auditoría y recuperación.
• Serializa o coordina en tu aplicación las operaciones dirigidas al mismo dispositivo.
• Usa sondeo de resultado acotado y respeta los límites de tasa.
• Valida el canal de destino y la seguridad física antes de permitir el control desde una interfaz o una regla de automatización.

Siguientes pasos

• Evento de cambio de estado del dispositivo (en inglés)
• Errores de recursos y comandos (en inglés)
• Construir un panel de monitorización de dispositivos