Device Twins

What the twin holds

The twin is the device's current state, kept on the server so it survives the device going to sleep or dropping offline. It tracks the latest value of each series the device publishes, plus two kinds of named key-value fields you push explicitly:

// things a device card commonly shows
mqtt.publish("~/~/status/firmware", "v1.2.0");
mqtt.publish("~/~/status/ip",       WiFi.localIP().toString().c_str());
mqtt.publish("~/~/status/uptime",   millis() / 1000);

The echo pattern: confirming a setting took

config exists for a specific loop. The dashboard sends a setting down to the device; the device applies it and publishes it back as a config value. Because the card renders the echoed value, the user sees the change land — not the value they typed, but the value the device actually adopted.

// dashboard pushes a new setpoint -> device receives it ->
// device applies it -> device echoes confirmation:
mqtt.publish("~/~/config/setpoint", appliedSetpoint);

If the echo never arrives, the user knows the device didn't get the message — which is exactly the feedback you want.

Online state and last-seen

The twin also tracks liveness. A device that has published recently shows as online; one that has gone quiet fades on the dashboard. Devices typically report a small set of self-metrics — uptime, boot count, free heap — that double as a heartbeat and as the data behind the card.

Labeling and forgetting devices

Devices identify themselves by a generated device ID (see Device Identity), which is stable but not friendly. The dashboard lets you attach a human label to a device so the cards, graphs, and rule messages read like English instead of a hex string.

You can also remove a device from the Devices screen. That clears its slot in the twin store — it does not touch the device itself. The next time that device publishes, its card simply reappears, rebuilt from its next report.