Connect your first device

This page connects one device that logs in with an access token. It takes about five minutes. You can use the real device, or a computer with an MQTT client or curl that stands in for it. For LoRaWAN sensors, follow Connect your first LoRaWAN sensor instead; for licensed devices, see Adding and claiming devices.

What you need

• The Admin or Owner role (permission to create devices and manage device credentials).
• An MQTT 3.1.1 client with TLS, or curl. The examples use mosquitto_pub, the client the device page also shows.
• Outgoing access to TCP port 8883 (MQTT over TLS) or 443 (HTTPS).

1. Add the device

1. Open Devices in the IoT menu.
2. Select New device. The drawer asks What are you adding? when several ways are offered; choose Other device (“Any other device: give it a name and a profile, and it gets an access token.”).
3. Fill in the form:

Field	What to enter
Name	A name unique in your organisation, for example boiler-07. Required, up to 128 characters.
Label	Optional free text, for example Boiler room, north.
Device profile	Keep The default profile for now. You can move the device to another profile later.
This device is a gateway	Leave it off. Turn it on only for a device that reports for other devices.

1. Select Create device.

The drawer shows New secret: Copy it now: it is shown once and cannot be read back. with the device’s Access token, and a Connection details card that already carries the token in its example lines.

If no token is shown, your organisation has switched off Issue an access token for new devices (Devices > ⋯ > Settings). The device is then created without a credential; see Device credentials.

2. Read the connection details

The Connection details card lists:

Item	Meaning
MQTT broker	The host and port the device connects to.
Security	TLS (mqtts): the server certificate is a public one, or plain MQTT when the profile allows it.
Login	Username = the access token, password empty, any client ID
Telemetry topic and Attributes topic	Where the device publishes.
Commands (subscribe)	Where the device listens for commands.
HTTPS telemetry and Header	The address and header for devices that use HTTPS instead.
Example message (JSON), Send it with mosquitto_pub, Send it with curl	Lines you can copy and run.

Later, administrators find the same card on the device’s Credentials tab (with a placeholder instead of the token).

3. Send a message over MQTT

Log in with the token as the username and an empty password, then publish a JSON object to v1/telemetry with QoS 1:

mosquitto_pub -h <broker host> -p 8883 \
  --capath /etc/ssl/certs \
  -u "<ACCESS_TOKEN>" \
  -i boiler-07 \
  -q 1 \
  -t v1/telemetry \
  -m '{"temperature": 21.5, "humidity": 40}'

• Use the host name shown on the card. TLS needs the name, not an IP address.
• The client ID can be any 1 to 64 characters from A–Z a–z 0–9 . _ : -.
• Hermetry stores each key as its own series and stamps the values with the time it received them.

3b. Or send it over HTTPS

curl -X POST "https://<device host>/api/v1/telemetry" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.5, "humidity": 40}'

An answer 200 with an empty body means the message was accepted. See Device HTTP API.

4. Check that it arrived

1. Open Devices and select the device’s name.
2. The Connection column and the device header show Online while an MQTT session is open (on the default profile’s Live connection rule). An HTTP-only device on that rule never shows online; see Connection status and activity.
3. Open the Telemetry tab. The Latest values table lists temperature and humidity with their time.
4. Tick a numeric key and use Chart to see its trend over the Last hour up to the Last 7 days.

Send a few more messages with other values to see the chart move.

If nothing arrives

Symptom	Likely cause
The client says “bad username or password” (CONNACK 4).	The token is wrong, or it was rotated.
The client says “not authorised” (CONNACK 5).	The device is disabled, or the profile does not allow this login type or this network, or requires TLS. The reason is written to the device’s Log tab.
The connection on port 1883 is refused.	The profile requires TLS. Use port 8883.
The TLS handshake fails.	You connected by IP address, or your client has no CA bundle. Use the host name and the system’s CA store.
HTTP answers 401.	The Authorization: Bearer header is missing or the token is wrong.
The device shows online but no value appears.	The payload is not a JSON object, or a key breaks the key rules (for example it starts with _ or fw_). See MQTT topics and payload reference.

More causes are listed in A device does not connect and Data does not arrive.

What you did

• You created a device on the default profile, which requires TLS and accepts access tokens.
• The device logged in with its token and published telemetry.
• Each message counts toward your organisation’s monthly message quota. See Message quota and usage.

Next step

Build your first dashboard.