ThingsBoard is one of the most capable open-source IoT platforms out there. But the first time you try to get a device publishing telemetry over MQTT, the documentation sends you in three different directions of device profiles, transport configurations, topic formats, and credential types. There are a lot of setups before you see a single data point on a dashboard.

This post cuts through that. By the end, you will have a device sending live sensor data to ThingsBoard over MQTT and seeing it in the Latest Telemetry tab. No fluff, just working code.

What You Need Before Starting

A running ThingsBoard instance, Community Edition, is fine. You can use the live demo for a quick look, though a local Docker setup is more reliable for following along since the demo instance has usage limits. You also need mosquitto-clients installed for quick command-line testing and Python 3 with paho-mqtt for the scripting part.

# Install mosquitto client tools

sudo apt install mosquitto-clients

# Install Python MQTT client

pip install paho-mqtt

Step 1: Create a Device and Grab the Access Token

In the ThingsBoard UI, go to Entities → Devices and click the + button to add a new device. Name it something like sensor-01. Once created, click on the device and copy the access token from the credentials tab.

This token is your MQTT username. No password needed. ThingsBoard uses it to identify which device is sending data.

Step 2: Send Your First Telemetry via Command Line

Before writing any code, test the connection with mosquitto_pub. This tells you immediately whether the setup works.

mosquitto_pub -d -q 1 \

  -h "YOUR_THINGSBOARD_HOST" \

  -p 1883 \

  -t "v1/devices/me/telemetry" \

  -u "YOUR_ACCESS_TOKEN" \

  -m '{"temperature": 25.4, "humidity": 62}' 

If you are running ThingsBoard 3.5 or later, you can use the shorter topic format:

mosquitto_pub -d -q 1 \ 

  -h "YOUR_THINGSBOARD_HOST" \ 

  -p 1883 \ 

  -t "v2/t" \ 

  -u "YOUR_ACCESS_TOKEN" \ 

  -m '{"temperature": 25.4, "humidity": 62}'

Both do the same thing. v2/t just saves bandwidth, useful when your device is on a metered cellular connection.

Now go to Entities → Devices → sensor-01 → Latest Telemetry. You should see temperature and humidity with the values you just sent.

Step 3: Continuous Telemetry with Python

A one-shot of publishing proves the connection works. For continuous monitoring, here is a Python script that simulates a sensor publishing every five seconds:

import paho.mqtt.client as mqtt

import json

import time

import random

THINGSBOARD_HOST = "YOUR_THINGSBOARD_HOST"

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

TELEMETRY_TOPIC = "v2/t"

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)

client.username_pw_set(ACCESS_TOKEN)

client.connect(THINGSBOARD_HOST, 1883, 60)

client.loop_start()

try:

    while True:

        payload = {

            "temperature": round(random.uniform(20.0, 35.0), 1),

            "humidity": round(random.uniform(40.0, 80.0), 1)

        }

        client.publish(TELEMETRY_TOPIC, json.dumps(payload), qos=1)

        print(f"Published: {payload}")

        time.sleep(5)

except KeyboardInterrupt:

    client.loop_stop()

    client.disconnect()

Run the script, open the Latest Telemetry tab in ThingsBoard, and watch the values update in real time.

Step 4: Adding Timestamps from the Device

By default, ThingsBoard uses the server to receive time as the timestamp. If your device has a reliable clock and you want exact measurement times, include a ts field in milliseconds:

payload = {

    "ts": int(time.time() * 1000),

    "values": {

        "temperature": 24.8,

        "humidity": 55.3

    }

}

This matters when devices batch data offline and upload it later without client-side timestamps; every reading looks like it arrived at the same moment.

What Comes Next

Once telemetry is flowing, the next steps are setting up rule chains to route data, trigger alerts, and create automation workflows. Then building a dashboard to visualize the data beyond the raw latest telemetry tab. That is where ThingsBoard gets really powerful, but it all starts with getting MQTT telemetry in the door first.

For teams that need help going beyond the basics, custom widgets, multi-tenant architectures, or production-grade ThingsBoard deployments, Promeraki's ThingsBoard development team works with this stack daily.

Running ThingsBoard in production? What tripped you most during the initial MQTT setup authentication, topic structure, or something else entirely?