ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform. Open documentation for releases before 2.0
ThingsBoard Professional Edition with White-labeling and Platform Integrations Learn More

Platform Integrations


ThingsBoard PE Feature


Only ThingsBoard Professional Edition supports Platform Integrations feature.

See Get ThingsBoard PE to install ThingsBoard PE.

Overview

ThingsBoard Platform integrations feature was designed for two primary use cases / deployment options:

Both use cases have few things in common. There is a server-side component in the deployment topology that prevents direct access to device and provides set of APIs to interact with the device in the field instead. The payload format of the device is not well defined. Often two devices that have similar sensors have different payload formats depending on a vendor or even software version.

The job of ThingsBoard Integration is to provide secure and reliable API bridge between core platform features (telemetry collection, attributes and RPC calls) and specific third-party platform APIs.

How it works?

At the moment ThingsBoard supports two main integration protocols: HTTP and MQTT. For example, SigFox Backend uses HTTP to push data to ThingsBoard or any other system. On the other hand, AWS IoT, IBM Watson and Azure Event Hub allows to subscribe to the data feed from devices via MQTT. Similar, some LoRaWAN and NB IoT platforms allow both HTTP and MQTT interfaces.

Once message arrives from External Platform to ThingsBoard it passes validation according to platform specific payload format and security rules. Once message is validated ThingsBoard Integration invokes assigned Uplink Data Converter to extract sub-set of meaningful information out of the incoming message. The message is basically transformed from device and platform specific payload to the format that ThingsBoard uses.

Since TB PE v2.0, Rule Engine is also able to push Downlink messages to the integrations. The example of such message may be:

The most common use cases are:

Once message is pushed by the rule engine, ThingsBoard invokes assigned Downlink Data Converter and transforms the rule engine message to the specific data format that is used by the Integration.


image

Data Converters

Data Converters is a part of the Platform Integrations feature. There are Uplink and Downlink data converters.

The main function of Uplink Data Converter is to parse payload of the incoming message and transform it to format that ThingsBoard uses.

Uplink Converter is basically a user defined function with the following signature:

function Decoder(payload, metadata);
Payload

Payload is one of the following content types: JSON, TEXT, Binary(Base64) and is specific to your Integration type.

Default Uplink Converter is dummy, but contains few helper functions to transform incoming payload:

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   // covert payload to string.
   var str = decodeToString(payload);
   // parse string to JSON
   return JSON.parse(str);
}

There are also btoa and atob functions available to decode Binary(Base64) payload.

Metadata

Metadata is a key-value map with some integration specific fields. You can configure additional metadata for each integration in the integration details. For example, you can put device type as an additional Integration metadata parameter and use it to automatically assign corresponding device type to new devices.

Converter output

Converter output should be a valid JSON document with the following structure:

{
    "deviceName": "Device A",
    "deviceType": "thermostat",
    "attributes": {
        "model": "Model A",
        "serialNumber": "SN-111",
        "integrationName": "Test integration"
    },
    "telemetry": {
        "temperature": 42,
        "humidity": 80
    }
}

NOTE: The only mandatory parameters in the output JSON are deviceName and deviceType.

Converter may also output array of device values and/or contain timestamps in the telemetry values. For example:

[
    {
        "deviceName":"SN-111",
        "deviceType":"thermostat",
        "attributes":{
            "model":"Model A"
        },
        "telemetry":[
            {
                "ts":1527863043000,
                "values":{
                    "battery":3.99,
                    "temperature":27.05
                }
            },
            {
                "ts":1527863044000,
                "values":{
                    "battery":3.98,
                    "temperature":27.06
                }
            }
        ]
    },
    {
        "deviceName":"SN-333",
        "deviceType":"thermostat",
        "attributes":{
            "model":"Model A"
        },
        "telemetry":{
            "ts":1527863041000,
            "values":{
                "battery":3.99,
                "temperature":27.05
            }
        }
    }
]
Example

Let’s assume a complex example where payload is encoded in hex “value” field and there is a timestamp associated with each record. First two bytes of “value” field contain battery and second two bytes contain temperature. See payload example and metadata on a screen shoot below:

image

The full source code of javascript function used in converter is available here.

See video tutorial below for step-by-step instruction how to setup Uplink Data Converter.


The main function of Downlink Data Converter is to transform the incoming rule engine message and its metadata to the format that is used by corresponding Integration.

Downlink Converter is basically a user defined function with the following signature:

function Decoder(msg, metadata, msgType, integrationMetadata);

Where

Converter output

Converter output should be a valid JSON document with the following structure:

{
    "contentType": "JSON",
    "data": "{\"tempFreq\":60,\"firmwareVersion\":\"1.2.3\"}",
    "metadata": {
        "topic": "temp-sensor/sensorA/upload"
    }
}

Where

Example

Let’s assume an example where temperature and humidity upload frequency attributes are updated via ThingsBoard REST API and you would like to push this update to an external MQTT broker (TTN, Mosquitto, AWS IoT, etc). You may also want to include the “firmwareVersion” attribute value that was configured long time ago and is not present in this particular request. The topic to push the update should contain the device name.

image

The full source code of javascript function used in converter is available here.

In order to invoke the downlink processing by the integration, tenant administrator should configure the rule chain similar to the one below:

image

The full rule chain configuration is available here.

Most of the integrations are able to process downlink messages to devices asynchronously. For example, each message pushed by the rule engine to MQTT based integration is immediately pushed to the corresponding external MQTT broker.

However, some integrations, like SigFox or generic HTTP integration are not able to push message asynchroniously. These integrations, due to the nature of underlying HTTP protocol, are only able to push downlink information synchronously in reply to uplink message request. In this case, the last downlink message originated by rule engine will be stored in the queue until the new uplink message arrives for particular device.

Debug mode

This feature allows to persis:

It enables rapid development of converters and configuration of integrations. This feature allows to validate your configuration setup and should be used only for debug purposes, since it dramatically impacts performance.

Platform Integrations vs IoT Gateway

Experienced ThingsBoard users may notice that functionality of Integrations feature partially overlap with functionality of IoT Gateway. However, there are key differences between these two systems/features:

As you can see, both systems are important and applicable in different use cases.

Feature Roadmap

Usage statistics

We plan to log statistics for amount of messages processed by each integration with possible limitations of messages processed on a tenant / system levels.

More integrations and protocols

We plan to provide specific integrations for different platforms, and also for different communication protocols, like gRPC.

More data converters

We plan to collect and maintain data converters for most popular devices on the market to simplify integration path even more. Please note that you can share your converters with community and send them to us to make part of official ThingsBoard distributive.

Contact us to suggest missing feature for your use case.

Next Steps

Explore guides and video tutorials related to specific integrations: