Arduino ThingsBoard SDK

This library provides access to ThingsBoard platform over MQTT protocol.

Examples

The SDK comes with a number of example sketches. See Files --> Examples --> ThingsBoard within the Arduino application. Please review the complete guide for ESP32 Pico Kit GPIO control and DHT22 sensor monitoring available here.

Installation

ThingsBoard SDK can be installed directly from the Arduino Library manager. Following dependencies are installed automatically or must be installed, too:

Installed automatically:

• MQTT PubSub Client — for interacting with MQTT.
• ArduinoJSON — for dealing with JSON files.
• Arduino Http Client — for interacting with ThingsBoard using HTTP.

Needs to be installed manually:

• MbedTLS Library — needed to create hashes for the OTA update (ESP8266 only, already included in ESP32 base firmware).
• WiFiEsp Client — needed when using an Arduino Uno in combiantion with an ESP8266.

Supported ThingsBoard Features

• Telemetry data upload
• Device attribute publish
• Server-side RPC
• Client-side RPC
• Attribute update subscription
• Device provisioning
• Device claiming
• Firmware OTA update

Example implementations for all features can be found in the examples folder. See the according README.md, to see which boards are supported and which functionality the example shows.

Troubleshooting

PubSubClient causing problems with non ESP boards

For boards that do support the C++ Standard Library (STL), but aren't either the ESP32 or the ESP8266 the PubSubClient does not support std::function usage. Meaning the usage of the C++ STL with the ThingsBoard Arduino SDK has to be disabled, luckily this can be done pretty easily simply add a #define THINGSBOARD_ENABLE_STL 0 before including the ThingsBoard header file.

// If not set otherwise the value is 0 or 1 depending on if the given device does support the needed C++ STL functionalities.
// Set to 0 if the board does support the C++ STL, but is neither en ESP32 nor an ESP8266, see https://github.com/knolleary/pubsubclient/pull/993 for more information about the issue
#define THINGSBOARD_ENABLE_STL 0
#include <ThingsBoard.h>

No PROGMEM support causing crashes

All constant variables are per default in flash memory to decrease the memory footprint of the library, if the libraries used or the board itself don't support PROGMEM. This can cause crashes to mitigate that simply add a #define THINGSBOARD_ENABLE_PROGMEM 0 before including the ThingsBoard header file.

// If not set otherwise the value is 1 per default if the ARDUINO plattform is used,
// set to 0 if the board has problems with PROGMEM variables and does not seem to work correctly.
#define THINGSBOARD_ENABLE_PROGMEM 0
#include <ThingsBoard.h>

Not enough space for JSON serialization

The buffer size for the serialized JSON is fixed to 64 bytes. The SDK will not send data, if the size of it is bigger than the size originally passed in the constructor as a template argument (PayLoadSize). Respective logs in the "Serial Monitor" window will indicate the condition:

[TB] Buffer size (64) to small for the given payloads size (83), increase with setBufferSize accordingly

If that's a case, the buffer size for serialization should be increased. To do so, setBufferSize() method can be used or alternatively the bufferSize passed to the constructor can be increased as illustrated below:

// For the sake of example
WiFiEspClient espClient;

// The SDK setup with 64 bytes for JSON buffer
// ThingsBoard tb(espClient);

// The SDK setup with 128 bytes for JSON buffer
ThingsBoard tb(espClient, 128);

void setup() {
  // Increase internal buffer size after inital creation.
  tb.setBufferSize(128);
}

Too much data fields must be serialized

A buffer allocated internally by ArduinoJson library is fixed and is capable for processing not more than 8 fields. If you are trying to send more than that, you will get a respective log showing an error in the "Serial Monitor" window:

[TB] Too many JSON fields passed (26), increase MaxFieldsAmt (8) accordingly

The solution is to use ThingsBoardSized class instead of ThingsBoard. Note that the serialized JSON buffer size must be specified explicitly, as described here.

// For the sake of example
WiFiEspClient espClient;

// The SDK setup with 8 fields for JSON object
// ThingsBoard tb(espClient);

// The SDK setup with 128 bytes for JSON payload and 32 fields for JSON object.
ThingsBoardSized<32> tb(espClient, 128);

Tips and Tricks

To use your own logger you have to create a class and pass it as third parameter Logger to your ThingsBoardSized class instance.

For example:

class CustomLogger {
public:
  static void log(const char *error) {
    Serial.print("[Custom Logger] ");
    Serial.println(error);
  }
};

Your class must have method log with the same prototype as in the example. It will be called, if the library needs to print any log messages.

After that, you can use it in place of regular ThingsBoard class. Note that the serialized JSON buffer size must be specified explicitly, as described here.

// For the sake of example
WiFiEspClient espClient;

// The SDK setup with 8 fields for JSON object
// ThingsBoard tb(espClient);

// The SDK setup with 128 bytes for JSON payload and 32 fields for JSON object.
ThingsBoardSized<32, CustomLogger> tb(espClient, 128);

Have a question or proposal?

You are welcomed in our issues and Q&A forum.

License

This code is released under the MIT License.