Ot/Documentation

Devices & Tokens

A device is one physical board that sends readings. Each device belongs to you, is optionally assigned to a project, and authenticates with a token that only it holds.

Registering a device

On the Devices page, Add Device opens a four-step wizard:

StepWhat you do
1 · DetailsName the device, pick the board type (ESP32, ESP8266, …), choose how it reaches Ot (wireless or tethered), set its report interval, and optionally assign it to a project — you can leave it unassigned and attach one later.
2 · DownloadsDownload secrets.h (credentials), the OtTelemetry Arduino library ZIP, and a ready-made sketch.
3 · FirmwareReview the firmware template with your broker settings already filled in, then flash it to the board.
4 · VerificationThe wizard listens for your device's first reading. Flash and power the board — the step completes by itself when its first data arrives, proving the whole chain works. You can also finish later and flash when ready.

Your secrets.h looks like this — fill in the WiFi values yourself:

cpp
// secrets.h - Ot platform credentials configuration
#define OT_WIFI_SSID   "YOUR_WIFI_NAME"
#define OT_WIFI_PASS   "YOUR_WIFI_PASSWORD"
#define OT_DEVICE_TOKEN "ot_tok_..."   // generated at registration
#define OT_PROJECT_ID   "proj_..."     // the project this device reports to

Treat the token like a password

The token authorizes writing telemetry as this device. If it leaks, delete the device and register a new one to rotate credentials. Never commit secrets.h to a public repository.

Tethered devices and the browser bridge

Boards without a radio (Arduino Uno, Nano) — or any board on the bench — can report in tethered mode: the sketch just prints field,value lines over serial (for example moisture,412), and a browser tab forwards each line to Ot. No WiFi code, no MQTT library, and no token in firmware.

  • The bridge opens from two places: the USB icon next to a tethered device on the Devices page, and the Bridge button on the project dashboard. Use the dashboard one to stream and watch your widgets update on the same screen.
  • On the dashboard, collapsing the bridge panel does not stop the stream — a pulsing dot on the Bridge button shows it is still forwarding. Leaving the page or closing the tab does stop it.
  • Readings go through the same pipeline as wireless data — they land in the same charts and fire the same alert rules.
  • The bridge uses the Web Serial / Web Bluetooth APIs, which work in Chrome or Edge on desktop (over HTTPS or localhost).

Registering without a project

A device does not need a project to exist. You can register it, verify the hardware, and attach a project later — the Assigned Project column on the Devices page shows an Assign to project… dropdown for any unassigned device.

Unassigned devices don't record data

Readings from an unassigned device are still authenticated — the device shows Online and wizard verification completes — but the readings themselves are discarded, because readings live inside a project. Assign a project to start recording; data sent before the assignment is not recovered.

Online and offline status

Ot does not rely on the device announcing itself. A device is considered Online when its most recent reading arrived within its grace window — roughly 2–3× its report interval, with a minimum of 30 seconds. If data stops arriving, the device flips to Offline automatically, and the Devices page shows how long ago it was last seen.

  • A device reporting every 10 seconds shows offline after about 30 seconds of silence.
  • A device reporting every 5 minutes is allowed several missed intervals before it is marked offline.
  • The Devices page refreshes itself every 15 seconds, so status changes appear without reloading.
Set the report interval during registration to match your sketch's delay(). If your firmware sends every 60 seconds but the device is registered at 10 seconds, it will flicker offline between reports.

Managing devices

  • Each row on the Devices page shows the status dot, board (with a USB icon for tethered devices), assigned project, and last-seen time.
  • Unassigned devices show an Assign to project… dropdown right in the list; assigned devices link to their project dashboard.
  • Tethered devices have a USB action button that reopens the browser bridge at any time.
  • Deleting a device invalidates its token immediately — the bridge drops any further messages from it.
Next: Arduino Library