Build a Device Monitoring Dashboard

Use Case

Use this pattern for an account-level dashboard that shows device connectivity and peripheral state while keeping HTTP traffic predictable.

• Use REST device lists for initial rendering, pagination, and background synchronization.
• Use a single-device query when a user explicitly refreshes a detail view or when an operation needs confirmation.
• Use WebSocket events for ongoing connection, relay, and digital-input state changes.

Do not continuously poll every device through HTTP.

Recommended Architecture

Maintain one state record per deviceId. Use stateUpdatedAt when merging runtime state so older data does not replace newer data. Connection events update connectivity; changes in device.state.changed identifies affected relays or digital inputs, while peripherals is a complete state block rather than an incremental patch. Read analog and sensor values when the user refreshes or the business flow requires them; do not poll every device at high frequency.

Step-by-Step Implementation

1. Obtain an access token with device:read.
2. Call List Devices, follow pagination, and store each device's deviceType, status, peripherals, and stateUpdatedAt.
3. Fetch List Device Type Definitions and map each deviceType to its capability definition. Cache these definitions instead of requesting them for every render.
4. Create a one-time WebSocket ticket, establish the connection, and start the documented heartbeat flow.
5. Apply device.connection.online, device.connection.offline, and device.state.changed events to the matching device record.
6. When a user explicitly requests fresh data for one device, call Get Device or send device.state.get.
7. After a disconnect or process restart, reconnect with a new ticket and rebuild the REST baseline before trusting the live view again. Refresh only business-critical devices individually.

Key Interfaces and Events

Purpose	Reference
Initial list and pagination	List Devices
Capability-driven UI	List Device Type Definitions
Explicit single-device refresh	Get Device
WebSocket authentication	Create WebSocket Ticket
Connectivity changes	Device Connection Events
Peripheral-state changes	Device State Changed Event

Failure and Recovery

• On WebSocket loss, mark the live channel as unavailable, reconnect with exponential backoff and jitter, and create a new wsTicket for every attempt.
• Events missed while disconnected are not replayed. Rebuild the state baseline through REST after reconnecting.
• If an event and a query race, keep the state with the newer stateUpdatedAt.
• After 429 RATE_LIMITED, wait for Retry-After. Do not switch to per-device polling to compensate for a disconnected WebSocket.
• An OFFLINE device may contain its last synchronized peripheral state. Show connectivity and state freshness separately.

Production Considerations

• Store a normalized state per deviceId; identify sensor readings by index + type.
• Make event application idempotent. Connection events provide occurredAt, while state events provide stateUpdatedAt; ignore older updates already reflected in the current record.
• Persist business-critical events promptly, because WebSocket has no history replay.
• Monitor reconnect attempts, event lag, REST synchronization failures, and requestId values without logging credentials or tokens.

Next Steps

• Monitor Offline and Power-loss Events
• REST API vs WebSocket
• Heartbeats and Reconnection