What are the guarantees and limits of remote command execution? #

Dataplicity has two different control paths:

generic Device Class actions for lightweight UI-to-device requests;
Product Application commands for durable workflow execution.

Do not apply the limits of the generic action inbox to Product Application commands.

Generic Device Class actions #

A generic action is a request to the device, not proof that the physical or business operation happened.

It is suitable for controls such as rebooting a device, running diagnostics, refreshing content, or changing a non-critical mode. The generic path can report that a request was queued, but it does not itself provide a durable domain contract for idempotency, expiry, cancellation, or acknowledgement. Pending generic actions also do not form a durable business queue across restart or an arbitrary outage.

For the exact release-specific inbox behaviour, see the device data and control contract.

Product Application commands #

When a customer workflow needs durable control semantics, use a Product Application command.

A Product Application command has a stable invocation identity and tracks a lifecycle including:

text

pending -> delivered -> acknowledged -> executing -> succeeded / failed

Additional terminal or control states include expired, rejected, and cancelled.

The command contract also supports:

an idempotency key so a repeated cloud-side request can return the existing invocation rather than create a second one;
a deadline and expiry behaviour;
hard cancellation before delivery and device-confirmed cancellation after delivery;
controlled redelivery when a delivered invocation has not been acknowledged;
explicit acknowledgement, executing, and terminal result states;
a correlation ID for tracing a command through a wider workflow;
optional mutex groups to prevent conflicting in-flight commands for the same product instance/device scope.

Product Application operations also accept an idempotency key. When the operation is idempotent, reusing that key resolves to the existing operation invocation instead of creating another.

These are cloud/runtime invocation guarantees. They do not make an actuator movement, fuel dispense, credit deduction, unlock, or other physical/business side effect exactly-once. If repeating the side effect would matter, the device or authoritative backend must recognise the stable invocation/domain identity and reconcile the final outcome.

Separate request from outcome #

For consequential workflows, separate three concerns:

Request: Dataplicity accepts and delivers an authorised invocation.
Execution: the device application decides whether the operation is valid and performs it.
Verification: the resulting state is reported so the operator or process can tell what actually happened.

A durable command can tell you that the device acknowledged, executed, rejected, expired, cancelled, succeeded, or failed the invocation. The device still owns the truth about the physical operation.

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 at the right layer #

There are two related but different idempotency problems:

Invocation idempotency prevents the same Product Application operation or command request from creating another cloud-side invocation when the same idempotency key is reused.

Domain idempotency prevents the real-world effect from happening twice. Use a stable domain identifier and device/backend deduplication where repetition could create a harmful or financially incorrect second effect.

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.

Product Application commands carry a deadline and can expire before execution. The product should still choose a timeout appropriate to the physical operation and reject work that is no longer safe or meaningful locally.

Offline devices change the workflow #

A device that is offline cannot execute or confirm a remote operation until connectivity returns.

For a generic Device Class action, do not assume a durable business queue across the outage.

For a Product Application command, choose the delivery policy deliberately. A command can be queued until the device is online or rejected immediately when the device is offline. Durable command state still does not replace application-owned offline authority for operations that must continue safely without cloud connectivity.

See What happens when a device is offline?.

Match the mechanism to the consequence #

Action	Recommended mechanism	Additional design
Reboot device	Generic Device Class action	Confirm reconnect/result
Run DNS/NTP/connectivity test	Generic Device Class action	Return structured result
Refresh signage content	Generic action or Product Application command	Version/checksum verification is useful
Change non-critical operating mode	Setting or generic action	Local validation + reported state
Unlock/open equipment	Product Application command	Expiry, local safety, acknowledgement, domain deduplication where required
Dispense fuel / consume credit	Product Application process + command	Durable transaction identity, reservation/reconciliation, device/backend idempotency
Safety shutdown/interlock	Local safety system	Remote command may request state but must not be the sole safety authority

Report the result independently #

For meaningful actions, return enough evidence to distinguish:

rejected before execution;
delivered but not yet acknowledged;
acknowledged or executing;
attempted and failed;
succeeded;
succeeded with resulting state;
expired or cancelled.

Where practical, also report the resulting product state through a separate stream, setting, record, or status value. This lets the operator verify the outcome independently of the request path.

Fleet jobs use the same request/verify discipline #

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.