Ot/Documentation

Troubleshooting

Most problems come down to one of three links in the chain: the device can't reach WiFi/MQTT, the token doesn't match, or the widget is watching a different field name than the device sends.

Device shows Offline

  • Check the last-seen time on the Devices page. Never means no reading has ever arrived — a connection or token problem. A recent time that keeps aging means the device stopped sending.
  • Match the report interval. Online status expects data within roughly 2–3× the interval you registered (minimum 30 seconds). If your sketch sends every 60s but the device is registered at 10s, it will flicker offline — edit the device and set the interval to match your firmware.
  • Open the Serial Monitor at 115200 baud. The library logs WiFi and MQTT connection progress; stuck at WiFi means SSID/password in secrets.h, stuck at MQTT means the broker host/port.

Device is Online but a widget shows no data

  • Field names must match exactly. A widget watching temp will not plot temperature or Temp. Select the widget in edit mode and check its Sensor field source — the suggestions list shows the field names actually arriving.
  • Confirm the device is assigned to the same project as the dashboard you are viewing — readings route by project.
  • Unassigned devices don't record. A device with no project still shows Online (its data is authenticated), but the readings are discarded until you pick a project in the Assign to project… dropdown on the Devices page.

Readings are rejected

  • A deleted device's token stops working immediately. Re-register the device and flash the new secrets.h.
  • If you regenerated or edited secrets.h by hand, make sure OT_DEVICE_TOKEN and OT_PROJECT_ID are the ones from the wizard download, with no stray spaces.

Alerts didn't fire

  • Check the rule's cooldown — after a trigger, the rule stays quiet for the configured period even if readings keep crossing the threshold.
  • Check the rule's field name matches what the device sends, exactly like widgets.
  • Make sure at least one notification channel (in-app or email) is ticked on the rule.

Still stuck?

Re-run the Quickstart with a bare sketch that sends one hard-coded field — it isolates whether the problem is connectivity or your sensor code.

The example sketch in examples/BasicTelemetry inside the library ZIP is exactly that minimal known-good sketch.
Next: Back to Overview