MQTT Topics In ThingsBoard With ESP32-S2: A Complete Guide

Aug 11, 2025 by Henrik Larsen 59 views

How to Set MQTT Topics in ThingsBoard with ESP32-S2

Hey Timmy and other ThingsBoard enthusiasts!

It's fantastic to hear you've successfully connected your Adafruit ESP32-S2 board to ThingsBoard using the example from the ThingsBoard client SDK. That's a great first step! Now, let's dive into the crucial aspect of setting up MQTT Topics. This is key to structuring your data flow and ensuring your device communicates effectively with ThingsBoard.

Understanding MQTT Topics in ThingsBoard

First, let's demystify MQTT Topics. Think of them as addresses or channels where your device sends and receives data. In the context of ThingsBoard, MQTT Topics are the backbone of how your device telemetry, attributes, and commands are routed. Getting these topics right is essential for seamless communication.

When integrating ESP32-S2 with ThingsBoard, you're essentially setting up a system where your device can publish data (like sensor readings) and subscribe to commands (like controlling an actuator). This publish-subscribe model is super efficient for IoT applications, and MQTT is the protocol that makes it all happen.

Key Concepts to Remember:

Publishing: Your ESP32-S2 sends data to a specific MQTT Topic.
Subscribing: Your ESP32-S2 listens for data on a specific MQTT Topic.
Topics: Hierarchical strings that define the route for messages (e.g., v1/devices/me/telemetry).

Diving into ThingsBoard MQTT Topic Structure

Alright, let's get into the nitty-gritty of how ThingsBoard structures its MQTT Topics. This is where we'll define where your ESP32-S2 sends data and where it listens for commands.

ThingsBoard uses a specific format for MQTT Topics to manage device communication efficiently. The basic structure you'll encounter includes topics for telemetry, attributes (both shared and client-side), and RPC commands. Understanding this structure is crucial for setting up your ESP32-S2 correctly.

1. Telemetry Upload:

Topic: v1/devices/me/telemetry
This is the primary topic where your ESP32-S2 will publish sensor data or any other telemetry information. Think of telemetry as real-time data streaming from your device, such as temperature readings, humidity levels, or GPS coordinates.
The payload you send to this topic should be in JSON format. For example:
```
{
  "temperature": 25.5,
  "humidity": 60
}
```
In your ESP32-S2 code, you'll need to format your data into this JSON structure before sending it to the v1/devices/me/telemetry topic. This ensures that ThingsBoard can correctly interpret and store your data.

2. Client Attributes:

Topic (Publish): v1/devices/me/attributes
Topic (Subscribe): v1/devices/me/attributes/response
Client attributes are device-specific settings or configurations that your device can report to ThingsBoard. These might include firmware versions, device names, or configuration parameters. Unlike telemetry, attributes represent the state or properties of your device.
To publish client attributes, your ESP32-S2 sends a JSON payload to the v1/devices/me/attributes topic. For example:
```
{
  "firmwareVersion": "1.0.0",
  "deviceName": "ESP32-S2 Sensor Node"
}
```
ThingsBoard will respond to this request, and your device can subscribe to v1/devices/me/attributes/response to receive confirmation.

3. Shared Attributes:

Topic (Subscribe): v1/devices/me/attributes/shared/request
Shared attributes are settings or configurations that are shared across multiple devices or managed centrally in ThingsBoard. Your ESP32-S2 can subscribe to changes in shared attributes.
When a shared attribute is updated in ThingsBoard, the platform sends a message to the v1/devices/me/attributes/shared/request topic. Your ESP32-S2 should listen to this topic and update its configuration accordingly.

4. RPC Commands:

Topic (Subscribe): v1/devices/me/rpc/request/+
Topic (Publish): v1/devices/me/rpc/response/request_id
RPC (Remote Procedure Call) commands allow ThingsBoard to send commands to your device, such as turning on an LED, adjusting a motor speed, or triggering a specific action. This is a powerful feature for controlling your device remotely.
Your ESP32-S2 subscribes to the v1/devices/me/rpc/request/+ topic, where the + is a wildcard that matches any request ID. When ThingsBoard sends an RPC command, it includes a unique request ID.
The payload of the RPC request contains the method name and any parameters. For example:
```
{
  "method": "setLedState",
  "params": {"state": true}
}
```
Your ESP32-S2 should process the command and then publish a response to the v1/devices/me/rpc/response/request_id topic, replacing request_id with the actual request ID from the incoming message. The response payload can indicate the success or failure of the command.

Practical Steps to Implement MQTT Topics in Your ESP32-S2 Code

Okay, now that we've covered the theory, let's get practical. Here's a step-by-step guide to implementing these MQTT Topics in your ESP32-S2 code.

1. Include Necessary Libraries:

Make sure you have the required libraries in your Arduino IDE. You'll need libraries for WiFi connectivity, MQTT communication, and JSON handling. Popular choices include WiFi, PubSubClient (for MQTT), and ArduinoJson.
```
#include <WiFi.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>
```

2. Define Your WiFi and MQTT Credentials:

You'll need to set up your WiFi credentials (SSID and password) and your ThingsBoard device credentials (access token). These are essential for your ESP32-S2 to connect to your network and authenticate with ThingsBoard.

const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const char* thingsboardServer = "YOUR_THINGSBOARD_SERVER_IP_OR_DOMAIN"; // e.g., "demo.thingsboard.io"
const char* accessToken = "YOUR_DEVICE_ACCESS_TOKEN";

3. Initialize the WiFi and MQTT Client:

In your setup() function, initialize the WiFi connection and set up the MQTT client. This involves connecting to your WiFi network and configuring the MQTT client to communicate with your ThingsBoard instance.

WiFiClient espClient;
PubSubClient client(espClient);

void setup() {
  Serial.begin(115200);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi...");
  }
  Serial.println("Connected to WiFi");
  client.setServer(thingsboardServer, 1883); // Default MQTT port
  client.setCallback(callback); // Function to handle incoming messages
}

4. Implement the MQTT Connection and Reconnection Logic:

You'll need a function to connect to the MQTT broker and resubscribe to topics if the connection is lost. This ensures that your ESP32-S2 stays connected to ThingsBoard and continues to receive commands.

bool reconnect() {
  if (client.connect("ESP32Client", accessToken, NULL)) {
    Serial.println("Connected to ThingsBoard");
    client.subscribe("v1/devices/me/attributes/shared/request");
    client.subscribe("v1/devices/me/rpc/request/+");
    return true;
  } else {
    Serial.print("Failed to connect to ThingsBoard, rc=");
    Serial.println(client.state());
    return false;
  }
}

5. Implement the callback Function to Handle Incoming Messages:

This function is crucial for processing incoming messages from ThingsBoard, such as shared attribute updates and RPC commands. You'll need to parse the topic and payload to determine the type of message and take appropriate action.

void callback(char* topic, byte* payload, unsigned int length) {
  Serial.print("Message arrived [" + String(topic) + "] ");
  for (int i = 0; i < length; i++) {
    Serial.print((char)payload[i]);
  }
  Serial.println();

  // Handle shared attributes
  if (String(topic) == "v1/devices/me/attributes/shared/request") {
    // Parse JSON payload and update device configuration
    // Example using ArduinoJson:
    // StaticJsonDocument<200> doc;
    // deserializeJson(doc, payload, length);
    // ...
  }

  // Handle RPC commands
  if (String(topic).startsWith("v1/devices/me/rpc/request/")) {
    // Parse JSON payload and execute command
    // ...
    // Publish response to v1/devices/me/rpc/response/requestId
    // ...
  }
}

6. Publish Telemetry Data:

In your main loop, you'll want to collect sensor data and publish it to the v1/devices/me/telemetry topic. This involves creating a JSON payload with your sensor readings and sending it to ThingsBoard.

void loop() {
  if (!client.connected()) {
    if (!reconnect()) {
      delay(5000);
      return;
    }
  }
  client.loop();

  // Simulate sensor readings
  float temperature = 20.0 + random(100) / 10.0;
  float humidity = 50.0 + random(50) / 10.0;

  // Create JSON payload
  StaticJsonDocument<200> doc;
  doc["temperature"] = temperature;
  doc["humidity"] = humidity;
  char jsonBuffer[256];
  serializeJson(doc, jsonBuffer);

  // Publish telemetry
  client.publish("v1/devices/me/telemetry", jsonBuffer);
  Serial.println("Published telemetry: " + String(jsonBuffer));

  delay(5000); // Send data every 5 seconds
}

Troubleshooting Common Issues

Alright, let's be real – things don't always go perfectly the first time. Here are some common issues you might encounter and how to troubleshoot them.

1. Connection Problems:

Issue: Your ESP32-S2 isn't connecting to WiFi or ThingsBoard.
Troubleshooting:
- Double-check your WiFi SSID and password.
- Verify your ThingsBoard server address and access token.
- Make sure your ESP32-S2 is within range of your WiFi network.
- Check your ThingsBoard device status to ensure it's not blocked or inactive.

2. Data Not Appearing in ThingsBoard:

Issue: You're sending data, but it's not showing up in your ThingsBoard dashboard.
Troubleshooting:
- Verify that your MQTT Topics are correct (v1/devices/me/telemetry, etc.).
- Check your JSON payload format. It should be valid JSON.
- Use the ThingsBoard device telemetry tab to see if data is being received.
- Check your ThingsBoard server logs for any error messages.

3. RPC Commands Not Working:

Issue: Your ESP32-S2 isn't responding to RPC commands.
Troubleshooting:
- Ensure your ESP32-S2 is subscribed to the correct RPC topic (v1/devices/me/rpc/request/+).
- Check your callback function to see if it's correctly parsing RPC commands.
- Verify that you're publishing a response to the correct topic (v1/devices/me/rpc/response/request_id).
- Use the ThingsBoard RPC debugger to send test commands and monitor the communication.

4. Shared Attributes Not Updating:

Issue: Your ESP32-S2 isn't receiving updates to shared attributes.
Troubleshooting:
- Make sure your ESP32-S2 is subscribed to the shared attributes topic (v1/devices/me/attributes/shared/request).
- Check your callback function to see if it's correctly parsing shared attribute updates.
- Verify that the shared attributes are configured correctly in ThingsBoard.

Conclusion: Mastering MQTT Topics for Seamless IoT Communication

Alright, guys, we've covered a lot! From understanding the basics of MQTT Topics to implementing them in your ESP32-S2 code and troubleshooting common issues, you're now well-equipped to build robust IoT applications with ThingsBoard.

Remember, MQTT Topics are the backbone of communication between your devices and ThingsBoard. By structuring your data flow correctly, you can ensure that your devices send and receive information efficiently and reliably.

So, go ahead, experiment with different topics, and build amazing IoT solutions. If you have any more questions or run into issues, don't hesitate to ask. Happy coding!