Appearance
What are the guarantees and limits of remote command execution?
A remote command is a request to the device, not proof that the physical or business operation happened.
Design the device application to validate the request, execute it safely, and report the resulting state. For consequential workflows, add the domain-level idempotency, expiry, acknowledgement, and reconciliation your product requires.
Separate request from outcome
A useful command lifecycle distinguishes:
text
created -> queued -> delivered -> accepted -> executing -> succeeded / failedDataplicity can carry the request, but a generic queued result is not confirmation that the device completed the operation.
That distinction is useful rather than limiting: the cloud controls who may request an operation, while the device remains authoritative for whether the operation is valid now and what physically happened.
See the device data and control contract for release-specific action semantics.
Keep the device as the final physical authority
When a command reaches the device, the local application should decide whether it is valid in the current state.
For example, open_valve might be rejected because:
- a local interlock is active;
- the device is in maintenance mode;
- required sensor state is unavailable;
- the request is stale;
- the operation has already been processed;
- the hardware reports a fault.
Cloud permission to request an action does not remove the local safety boundary.
Use idempotency where repetition matters
Networks retry. Processes restart. Operators click twice. If repeating a command could create a harmful or financially incorrect second effect, give the operation a stable identifier and make the device or authoritative backend deduplicate it.
Examples include:
- dispense transactions;
- credit reservations;
- paid access grants;
- one-time unlocks;
- irreversible actuator sequences.
Routine support actions such as diagnostics or reboot normally need much less machinery.
Decide what expiry means
Some commands are useful only for a short time.
A request such as run diagnostics may still make sense after a reconnect. A request such as open gate now may be meaningless or unsafe minutes later.
For time-sensitive operations, include a validity window in your product protocol or have the device reject requests that are no longer current.
Offline devices change the workflow
A device that is offline cannot execute or confirm a remote operation until connectivity returns. Generic Dataplicity actions should not be treated as a durable business queue across an arbitrary outage.
If the business process requires guaranteed eventual processing, model that requirement explicitly in the application protocol and reconcile it when the device reconnects.
See What happens when a device is offline?.
Match the mechanism to the consequence
| Action | Generic remote command suitable? | Additional design |
|---|---|---|
| Reboot device | Yes | Confirm reconnect/result |
| Run DNS/NTP/connectivity test | Yes | Return structured result |
| Refresh signage content | Yes | Version/checksum verification is useful |
| Change non-critical operating mode | Usually | Local validation + reported state |
| Unlock/open equipment | Depends | Expiry, local safety, acknowledgement |
| Dispense fuel / consume credit | Not by command semantics alone | Durable transaction protocol, idempotency, reconciliation |
| Safety shutdown/interlock | No as the sole authority | Keep the safety system local |
Report the result independently
For meaningful actions, return enough evidence to distinguish:
- rejected before execution;
- attempted and failed;
- succeeded;
- succeeded with resulting state;
- timed out or became stale.
Where practical, report the resulting product state through a separate stream or status value. This lets the operator verify the outcome independently of the request path.
Fleet jobs use the same pattern
Fleet Jobs are useful for bounded operations across cohorts. Define the expected outcome and verify it independently.
For example, after restarting a service across 500 units, verify process state, version, or health through Pulse, telemetry, logs, or another independent signal.