How online/offline status works
A device is online when we've heard from it within its expected reporting window. Once that window passes it's marked offline and a device/offline event is emitted.
How long is the window?
It depends on how the device reports, because a device that reports every 5 minutes shouldn't be judged by the same clock as one reporting every 10 seconds.
| How the device connects | Window |
|---|---|
| Through a gateway (RS485, Modbus, I²C, GPIO, …) | 90 seconds. The gateway sends a presence heartbeat every ~10 s regardless of how rarely the device publishes, so a 5-minute publish interval is perfectly safe. |
| Polled by us (HTTP, SNMP, direct Modbus-TCP) | 3 × your configured poll interval. |
| Edge / fog devices | 15 minutes, matching the fog node's heartbeat. |
| Direct MQTT / webhook | 90 seconds by default — we can't see the interval of a device that pushes to us. Set a reporting grace period on the device if it reports less often. |
Every window is at least 90 seconds and at most 1 hour.
If your device reports on a slow schedule and keeps flipping between online and offline, setting its reporting grace period to roughly three times its real interval is the fix.
What the status dot colours mean
Device dot
A device's dot reflects its live presence and read health, in this order of priority:
- 🟢 Green — online and healthy. We've received a good reading within the device's reporting window (above) and every tag is within its threshold.
- 🟡 Yellow — online, but a threshold is breached. The device is reporting fine, but at least one tag is outside its configured alert threshold (see alert thresholds). This is about the value, not the connection — it clears automatically when the value returns to range.
- 🟠 Amber — unreachable (the gateway can't read it). The gateway is online and tried to read this device, but the read failed — a sensor didn't respond, a Modbus/parameter read errored, and so on. The link to the gateway is fine; this one device or sensor isn't answering. Hover the dot for the reason (e.g. "a parameter is unreadable").
- 🔴 Red / grey — offline. No live presence at all: either the gateway itself is down, or the device's reporting window expired, or a direct-MQTT device went silent.
Amber vs. red is the important distinction. Amber means "the gateway is talking to us, but this one device won't answer"; red/grey means "we've got nothing." A flaky sensor on a healthy gateway shows amber — far more useful than a plain "offline". Amber is not a replacement for offline; it's a finer state that splits the old "offline" into device-not-answering (amber) and nothing-there (red/grey).
When a whole gateway goes offline, its devices switch from amber to red/grey — once the gateway is gone we can no longer say it's "trying", so the devices are simply offline. They return to amber if the gateway reconnects and the same read keeps failing.
Priority: offline (red/grey) and unreachable (amber) both take precedence over the yellow threshold warning — a device that isn't reading can't be "in alert".
(One cosmetic note: "offline" renders red on the Devices list but grey on the gateway detail page and in the mobile app — same state, different shade.)
Gateway dot
A gateway's dot reflects only its own connection — an unreachable child device never turns the gateway amber:
- 🟢 Green — online. The gateway is connected, whether or not every device under it is responding.
- 🔴 Red / grey — offline. The gateway itself is disconnected (and all its devices show offline too).
A gateway reports in every 60 seconds. If we miss three of those in a row it's shown offline even when we never received a disconnect notice — that covers a gateway that loses power or drops off the network abruptly, which previously could keep showing green indefinitely.
If the gateway is online but one of its devices is unreachable, the gateway stays green and the problem is surfaced at the device level instead: the device-count on the gateway card turns amber, the gateway detail page shows a "N device(s) unreachable" badge, and that device shows its own amber dot. This keeps "the gateway is down" and "a device under it is misbehaving" clearly separate — you always know which one to go fix.
Notes:
- The dot is live presence; it is independent of the device's active/inactive status badge.
- A device with reads paused still shows its last presence; look for the Paused badge (see pause device reads).
- Presence is tracked in memory, not the database — it resets if our cache is flushed, and devices re-appear as soon as they publish again.
If a device is unexpectedly offline, see device shows offline.