Construir un panel de monitorización de dispositivos

Caso de uso

Usa este patrón para un panel a nivel de cuenta que muestre la conectividad y el estado de periféricos de los dispositivos, manteniendo el tráfico HTTP predecible.

• Usa las listas de dispositivos por REST para el renderizado inicial, la paginación y la sincronización en segundo plano.
• Usa una consulta de un solo dispositivo cuando el usuario actualiza explícitamente una vista de detalle o cuando una operación necesita confirmación.
• Usa eventos WebSocket para los cambios continuos de conexión, relés y entradas digitales.

No sondees continuamente todos los dispositivos por HTTP.

Arquitectura recomendada

Mantén un registro de estado por cada deviceId. Usa stateUpdatedAt al fusionar el estado en tiempo de ejecución, para que los datos antiguos no sustituyan a los nuevos. Los eventos de conexión actualizan la conectividad; changes en device.state.changed identifica los relés o entradas digitales afectados, mientras que peripherals es un bloque de estado completo, no un parche incremental. Lee los valores analógicos y de sensor cuando el usuario actualice o el flujo de negocio lo requiera; no sondees todos los dispositivos con alta frecuencia.

Implementación paso a paso

1. Obtén un access token con device:read.
2. Llama a Listar dispositivos (en inglés), sigue la paginación y guarda el deviceType, status, periféricos y stateUpdatedAt de cada dispositivo.
3. Consulta Listar definiciones de tipo de dispositivo (en inglés) y asocia cada deviceType con su definición de capacidades. Cachea estas definiciones en lugar de pedirlas en cada renderizado.
4. Crea un ticket de WebSocket (en inglés) de un solo uso, establece la conexión y arranca el flujo de heartbeat documentado.
5. Aplica los eventos device.connection.online, device.connection.offline y device.state.changed al registro de dispositivo correspondiente.
6. Cuando un usuario pida explícitamente datos actualizados de un dispositivo, llama a Consultar dispositivo (en inglés) o envía device.state.get (en inglés).
7. Tras una desconexión o un reinicio del proceso, reconecta con un ticket nuevo y reconstruye la base REST antes de volver a confiar en la vista en vivo. Actualiza individualmente solo los dispositivos críticos para el negocio.

Interfaces y eventos clave

Para qué	Referencia
Lista inicial y paginación	Listar dispositivos (en inglés)
Interfaz dirigida por capacidades	Listar definiciones de tipo de dispositivo (en inglés)
Actualización explícita de un dispositivo	Consultar dispositivo (en inglés)
Autenticación WebSocket	Crear WebSocket Ticket (en inglés)
Cambios de conectividad	Eventos de conexión de dispositivo (en inglés)
Cambios de estado de periféricos	Evento de cambio de estado del dispositivo (en inglés)

Fallos y recuperación

• Si se pierde el WebSocket, marca el canal en vivo como no disponible, reconecta con backoff exponencial y jitter, y crea un wsTicket nuevo en cada intento.
• Los eventos perdidos mientras estabas desconectado no se reproducen. Reconstruye la base de estado por REST después de reconectar.
• Si un evento y una consulta compiten, conserva el estado con el stateUpdatedAt más reciente.
• Tras un 429 RATE_LIMITED, espera lo que indique Retry-After. No pases a sondear por dispositivo para compensar un WebSocket desconectado.
• Un dispositivo OFFLINE puede conservar su último estado de periféricos sincronizado. Muestra la conectividad y la frescura del estado por separado.

Consideraciones para producción

• Guarda un estado normalizado por deviceId; identifica las lecturas de sensor por index + type.
• Haz que aplicar eventos sea idempotente. Los eventos de conexión traen occurredAt, y los de estado traen stateUpdatedAt; ignora las actualizaciones más antiguas que el registro actual.
• Persiste con prontitud los eventos críticos para el negocio, porque WebSocket no tiene reproducción de historial.
• Monitoriza los intentos de reconexión, el retraso de eventos, los fallos de sincronización REST y los valores de requestId, sin registrar credenciales ni tokens.

Siguientes pasos

• Monitorizar desconexiones y eventos de alimentación
• REST API o WebSocket
• Heartbeat y reconexión (en inglés)