Skip to main content

Node–Cloud Communication

A node keeps one long-lived MQTT connection to the cloud and does everything over it: reports its configuration, publishes state, receives commands, and downloads firmware. This page explains that channel — useful if you are writing firmware, integrating a client, or working out why a device shows as offline.

One connection, many topics​

The node connects to AWS IoT Core over TLS with its own X.509 certificate, and stays connected. There is no polling and no second channel: parameter writes, OTA job documents and service messages all arrive on that same session.

Topics fall into a few families:

  • Configuration — the node publishes its shape once, on first connect or whenever the shape changes.
  • Parameters — the node reports its current values; the cloud sends desired values down.
  • Services — schedules, OTA, and the other built-in services each have their own topics.
  • Presence — connect and disconnect events the broker raises, which the cloud turns into the node's online state.

The exact topic names and payload schemas are in the MQTT node reference, generated from the AsyncAPI spec.

Reported and desired state​

Node state lives in a device shadow with two halves. Reported is what the node says is true. Desired is what a client has asked for and the node has not yet confirmed.

A parameter write travels desired-first: a client writes the desired value, the cloud delivers it to the node, the node acts and then reports the new value. Clients that render device state should read reported, not desired — otherwise a switch appears to have flipped before the relay actually moved.

Connect, disconnect, reconnect​

The node sends a keepalive ping on an interval. If the broker stops hearing from it, it raises a disconnect event. The cloud deliberately waits before believing it, because a device that reconnects within a few seconds never really went away.

That delay is why offline is not instantaneous:

ScenarioShadow flips to offlineVisible flicker
Graceful disconnect~10 s after the device closes the connectionNone
Power outage, no reconnect~100 s (90 s keepalive + 10 s delay)None
Wi-Fi flicker, reconnect under 10 sNever — stays onlineNone
Long outage, later reconnectOffline at ~100 s, online on reconnectOne offline → online pair
"Offline" means the broker stopped hearing from it

This table is the answer to the most common operational question. A node that shows online can still be unresponsive — the connection is alive but the application is wedged — and a node that shows offline may have been gone for only a minute. Read Operations for what to do about each.

When the node is offline​

Publishes do not queue indefinitely. Schedules keep firing, because they run on the node itself; automations do not, because the cloud evaluates them and needs the node reachable to act. Time series points are buffered up to the queue size the firmware configures, and OTA jobs simply wait.