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:

  • Node messaging — a single pair of topics, to_cloud and from_cloud, carries most request/response traffic. Configuration is one of these messages, not a topic of its own: the node announces its shape with a setNodeConfig event on first connect or whenever the shape changes. Built-in services work the same way — schedule and trigger details are events on the same pair.
  • Parameters — the node reports its current values to a named device shadow; the cloud sends desired values down as shadow deltas, as direct publishes to the node's params topic, or as a broadcast to a group or subgroup control topic.
  • OTA — delivered through AWS IoT Jobs, on the $aws/things/{nodeId}/jobs/… topics, with file blocks arriving over IoT Streams.
  • Time series and notifications — separate publish-only topics for buffered samples and for direct notifications.
  • 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.

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~50 s (40 s keepalive + 10 s delay)None
Wi-Fi flicker, reconnect under 10 sNever — stays onlineNone
"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.

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.