Arduino ThingsBoard SDK

This library provides access to ThingsBoard platform over the MQTT protocol or alternatively over HTTP/S.

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 or PlattformIO. 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/S.

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 a Arduino Uno in combination with a ESP8266.

Supported ThingsBoard Features

Over MQTT:

All possible features are implemented over MQTT

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

Over HTTP\S:

Remaining features have to be implemented by hand with the sendGetRequest or sendPostRequest method, see the ThingsBoard Documentation on how these features could be implemented.

• Telemetry data upload
• Device attribute publish

Example implementations for all base features, mentioned above, 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

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 pgmspace include exists,
// 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>

Dynamic ThingsBoard usage

The received JSON payload, as well as the sendAttributes and sendTelemetry methods use the StaticJsonDocument by default, this furthermore requires the MaxFieldsAmt template argument passed in the constructor. To set the size the buffer should have, where bigger messages will cause not sent / received key-value pairs or failed de-/serialization.

To remove the need for the MaxFieldsAmt template argument in the constructor and ensure the size the buffer should have is always enough to hold the sent or received messages, instead #define THINGSBOARD_ENABLE_DYNAMIC 1 can be set before including the ThingsBoard header file. This makes the library use the DynamicJsonDocument instead of the default StaticJsonDocument.

// If not set otherwise the value is 0 per default,
// set to 1 if the MaxFieldsAmt template argument should not be required.
#define THINGSBOARD_ENABLE_DYNAMIC 1
#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. See Dynamic ThingsBoard Usage above if the usage of MaxFieldsAmt, should be replaced with automatic detection of the needed size.

// 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 second template 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.