Control Relays Safely

Use Case

Use this pattern when relay operations affect equipment and the caller must handle retries, uncertain outcomes, and multiple relay channels without creating duplicate side effects.

Recommended Flow

Send all relay changes for one device in one relays array. A single batch becomes one device command and avoids consecutive transmissions that the device may not process reliably.

Step-by-Step Implementation

1. Use List Device Type Definitions to confirm device.relay.set, relay count, and allowed actions.
2. Build the desired relay array. Use one item for single-channel control and multiple unique indexes for a coordinated change.
3. Generate a new caller-owned Idempotency-Key for this operation intent.
4. Call Execute Relay Command with device:control.
5. Read data.command.id and data.command.status. If the status is SENT, use Get Command Result until a terminal state or your bounded polling deadline.
6. Use data.state when the device acknowledgement includes it. Do not issue another refresh only to populate an optional field.
7. If the result is TIMEOUT, read the current device state before deciding whether another operation is safe.

Command Lifecycle

Result	Meaning	Client action
HTTP 202 + COMMAND_ACCEPTED	The platform accepted the request; it is not a separate command status	Read data.command.status and retain the command ID
SENT	The command is still waiting for confirmation	Query the command result with bounded polling
SUCCESS	The device confirmed execution	Apply returned state when present
FAILED	The platform confirmed that the command did not complete	Stop automatic retries and handle the failure
TIMEOUT	No final confirmation arrived within the wait window	Do not assume the device did or did not execute; read current state first

Key Interfaces

• Execute Relay Command
• Get Command Result
• Get Device State
• Rate Limits and Idempotency
• WebSocket Control Relays

Failure and Recovery

• If the HTTP outcome is unknown because the network failed, retry the identical request with the same Idempotency-Key.
• After 429 RATE_LIMITED, wait for Retry-After, then retry the same operation with the original key.
• Never reuse a key for a different device, relay array, or action; that returns IDEMPOTENCY_CONFLICT.
• After TIMEOUT, refresh state first. If the state is still unknown, require a business decision before sending another physical operation.
• Repeating JOG or other equipment actions can produce real side effects even when the previous response was lost. Design confirmation and operator safeguards accordingly.

Production Considerations

• Store the idempotency key, command ID, requested relay array, status, and requestId together for audit and recovery.
• Serialize or coordinate operations targeting the same device in your application.
• Use bounded result polling and honor rate limits.
• Validate the target channel and physical safety before allowing control from a UI or automation rule.

Next Steps

• Device State Changed Event
• Resource and Command Errors
• Build a Device Monitoring Dashboard