How should desired and reported configuration work?

Treat remote configuration as a two-sided contract:

desired state is what the operator or system wants;
reported state is what the device says it is actually using.

Do not treat writing a setting in the cloud as proof that the device has applied it.

Why the distinction matters

A device may be:

offline when the setting changes;
running an older application that does not understand the setting;
unable to apply the value because of local state;
rejecting the value because it is unsafe or invalid;
partially configured;
rebooting or rolling back.

If your UI shows only the requested value, operators can mistake intent for reality.

The normal flow

text

operator changes setting
        |
        v
desired value stored
        |
        v
device receives desired state
        |
        v
local application validates and applies
        |
        v
device reports accepted/effective value

The customer-facing application should make disagreement visible when it matters.

Validate twice

Validate configuration at both boundaries:

UI/cloud validation prevents obvious bad input and gives immediate feedback.
Device validation is authoritative for whether the value is safe and possible on that hardware in its current state.

Examples:

a temperature setpoint can be syntactically valid but outside the safe range for a specific unit;
a network address can be well formed but conflict with local configuration;
a motor speed can be within a general range but prohibited while a service door is open.

The local application should reject values it cannot safely apply.

Make disagreement observable

Useful states include:

in sync - reported equals desired;
pending - desired changed but device has not yet confirmed it;
offline - desired exists but delivery/application cannot currently be verified;
rejected - device explicitly refused the value;
error - application attempted but failed;
unknown - reported state has not yet been established.

Do not fabricate a confirmation from device connectivity alone.

Decide whether a setting is durable

A setting normally represents persistent desired configuration, not a one-off instruction.

Use a setting for things such as:

setpoints;
thresholds;
schedules;
feature flags;
product mode where that mode is intended to persist;
endpoint/dependency configuration.

Use a one-off action/command for things such as:

reboot now;
run a connectivity test;
capture diagnostics;
refresh content now;
perform a bounded operation once.

If the operator expects the value to remain true after reconnect/reboot, it is probably desired state rather than an action.

Handle offline devices deliberately

A desired value can outlive the connection. Your application needs to decide what the operator sees while the device is offline and what happens when it reconnects.

Do not imply that an offline device has applied a setting simply because the control plane accepted the requested value.

See What happens when a device is offline?.

Version the contract

A fleet can contain devices running different application versions. When adding or changing settings:

define which software versions understand the setting;
preserve compatible units and semantics;
choose safe defaults;
make unsupported values visible rather than silently ignored;
roll out to a staging cohort before broad use.

Device Classes should provide the stable product-level contract, but the device application still needs backward-compatible behaviour during rollout.

Do not use desired state as a safety override

The cloud may request a configuration. The device decides whether it is currently legal and safe to apply.

For safety-critical limits, keep hard local constraints that cannot be weakened merely because a remote value changed.

A good customer UI

For important settings, show enough evidence for the operator to know what happened:

Field	Example
Desired	4.0 °C
Reported	4.0 °C
Status	In sync
Last device report	12:41:08

During disagreement:

Field	Example
Desired	2.0 °C
Reported	4.0 °C
Status	Pending / rejected
Reason	Below local minimum

The exact UI can vary; the semantic distinction should not.

How should desired and reported configuration work? ​

Why the distinction matters ​

The normal flow ​

Validate twice ​

Make disagreement observable ​

Decide whether a setting is durable ​

Handle offline devices deliberately ​

Version the contract ​

Do not use desired state as a safety override ​

A good customer UI ​

Related ​