Command Lifecycle

Every command follows a defined lifecycle from creation to completion.

Status Flow

PENDING → SENT → ACKNOWLEDGED (success)
                → FAILED (device error)
                → TIMEOUT (no response in 5 minutes)

PENDING — Command is created in the database.

SENT — Command is published to the device's MQTT command topic:

tenant/{tenantId}/app/{applicationId}/device/{deviceToken}/cmd

Platform → DeviceDevice subscribes to receive commands

Payload format:

{
  "commandId": "uuid",
  "command": "reboot",
  "parameters": { "delay": 5 }
}

Device processes the command and publishes an acknowledgment:

tenant/{tenantId}/app/{applicationId}/device/{deviceToken}/ack

Device → PlatformDevice publishes command acknowledgment

ACK payload:

{
  "commandId": "uuid",
  "status": "success",
  "message": "Command executed"
}

Backend processes ACK — Updates the command status to ACKNOWLEDGED. WebSocket notifies the frontend in real-time.

Timeout — If no ACK is received within 5 minutes, the command status is set to TIMEOUT.

View all commands sent to a device on the Messaging tab. Each row is expandable to show:

Detail	Description
Parameters	The JSON parameters sent with the command
Response	The device's response payload
Error	Error message (if the command failed)
Timestamps	When the command was sent and acknowledged
Command ID	Unique identifier for tracking