Commands and Jobs
EMQX Fleets provides two mechanisms for sending operations to devices: Commands and Jobs. They serve different interaction patterns and have different delivery guarantees.
Commands vs Jobs
| Commands | Jobs | |
|---|---|---|
| Interaction pattern | Real-time request-response | Async batch dispatch with per-device tracking |
| Target | A single device | One or more devices or a Thing Group |
| Delivery | Immediate, requires device to be online | Queued, device picks up on reconnect |
| Execution tracking | Single execution record with status | Per-device execution record with full lifecycle |
| Timeout | Yes (configurable per command) | Job-level and per-step timeouts |
| Typical use | Trigger an action now (lock, unlock, reboot) | Roll out a change to a fleet (firmware update, config push) |
Commands
A Command is a real-time interaction with a single connected device. Fleets publishes the command request to the device over MQTT and waits for a response. The execution starts in SENT state and transitions to a terminal status (SUCCEEDED, FAILED, REJECTED, TIMED_OUT, or CANCELED) once the device responds or the TTL expires.
Commands are appropriate when:
- The device must be online to receive the operation
- You need an immediate response
- The operation targets one device
See Send Commands for details.
Jobs
A Job is an asynchronous operation dispatched to one or more devices. Devices receive a notification when a job is pending, then pull the job document, execute it, and report their status back to Fleets. Each target device has its own execution record with an independent status.
Jobs are appropriate when:
- You need to push an operation to many devices
- Devices may be intermittently offline (jobs are queued and delivered on reconnect)
- You need to track per-device execution progress over time
See Manage Jobs for details.
Execution Statuses
Command Execution Statuses
| Status | Meaning |
|---|---|
SENT | Command published to the device; awaiting response |
SUCCEEDED | Device responded with a successful result |
FAILED | Device responded with a failure |
REJECTED | Device rejected the command |
TIMED_OUT | No response received within the timeout window |
CANCELED | Command was canceled |
Job Execution Statuses
| Status | Meaning |
|---|---|
QUEUED | Job is pending, waiting for the device to pick it up |
IN_PROGRESS | Device has started the job |
SUCCEEDED | Device reported successful completion |
FAILED | Device reported failure |
REJECTED | Device rejected the job |
TIMED_OUT | Device did not complete the job within the timeout |
CANCELED | Execution was canceled by the cloud |
REMOVED | Execution record was deleted |