Connect your first device
This guide follows one device from creation to a dashboard widget that updates as readings arrive. Each step ends with something you can check, so you find out where a problem is rather than discovering it at the end.
Before you begin
Select the tenant you want to work in. Have ready:
- the device serial number,
- the readings it reports and the exact key names it uses for them,
- its connection details.
For MQTT you also need a configured broker and the topics used by the device.
Create the device
Open Devices and create a device. Give it a recognisable name and its serial number, select the appropriate device profile, then configure its inputs and outputs.
Keep input names identical to the keys in the telemetry payload. If the device
sends {"temperature": 23.4}, the input must be named temperature. Use the
label field for a friendly display name — labels are what dashboards show,
names are what payloads are matched against.
Input matching is exact. Temperature, temp and temperature are three
different names, and a mismatch is silent — the message arrives, but nothing
is mapped.
Configure its connection
Choose the connection type and save the corresponding settings.
- MQTT — check the selected broker and the publish/subscribe topics. See MQTT connections.
- API — use the device access token and the API URL shown in its overview. See Send data over HTTP.
Map readings to an entity
Create or edit an entity and connect its inputs to the device inputs you want to use. These mappings connect physical readings to the logical asset you will visualise. See entities and mappings.
This step is not cosmetic. Without a connected input, telemetry can be received without producing a history record.
Verify and visualise
Send a sample reading, then open the device’s Messages tab to confirm it arrived. Open your entity or dashboard and configure a widget for the mapped input.
Check that both the value and the timestamp update as new readings arrive. If messages appear in the Messages tab but the chart stays empty, the problem is in the input mappings, not in the chart.
What to check at each stage
| Symptom | Where to look |
|---|---|
| No messages in the Messages tab | Connection: broker, topic, token, serial |
| Messages arrive, history empty | Entity input mappings |
| History fills, widget empty | Widget data source and chart time range |
Next: Devices and I/O explains device status and the I/O panel in more detail.