Stand with Ukraine flag
Try it now Pricing
Professional Edition
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Getting Started
Devices Library Guides Installation Architecture API FAQ
On this page

HTTP Integration

Doc info icon
ThingsBoard PE Feature

Only Professional Edition supports Platform Integrations feature.
Use ThingsBoard Cloud or install your own platform instance.

Overview

HTTP Integration allows converting existing protocols and payload formats to ThingsBoard message format and is useful in several deployment scenarios:

  • stream device and/or asset data from external system, IoT platform or connectivity provider back-end.
  • stream device and/or asset data from your custom application running in the cloud.
  • connect the existing device with custom HTTP based protocol to ThingsBoard.

Before creating the integration, you need to create an Uplink converter in Data converters. Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard. Click on the “plus” and on “Create new converter”. To view the events, enable Debug. In the function decoder field, specify a script to parse and transform data.

Doc info icon

NOTE
While Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode can significantly increase the disk space used by the database since all the debug data is stored there. It is highly recommended turning the Debug mode off after debugging is complete.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

TBELRecommended
JavaScript

image

Example for the Uplink converter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

// Decode an uplink message from a buffer
// payload - array of bytes
// metadata - key/value object

/** Decoder **/
 
// decode payload to string
// var payloadStr = decodeToString(payload);

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.deviceType;

// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       model: data.model,
       serialNumber: data.param2,
   },
   telemetry: {
       temperature: data.temperature
   }
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

You can change the decoder function while creating the converter or after creating it. If the converter has already been created, then click on the “pencil” icon to edit it. Copy the configuration example for the converter (or your own configuration) and insert it into the decoder function. Save changes by clicking on the “checkmark” icon.

image

Example for the Uplink converter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

// Decode an uplink message from a buffer
// payload - array of bytes
// metadata - key/value object

/** Decoder **/

// decode payload to string
// var payloadStr = decodeToString(payload);

// decode payload to JSON
var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.deviceType;

// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       model: data.model,
       serialNumber: data.param2,
   },
   telemetry: {
       temperature: data.temperature
   }
};

/** Helper functions **/

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

return result;

You can change the decoder function while creating the converter or after creating it. If the converter has already been created, then click on the “pencil” icon to edit it. Copy the configuration example for the converter (or your own configuration) and insert it into the decoder function. Save changes by clicking on the “checkmark” icon.

Now that the Uplink converter has been created, it is possible to create an integration.

Create integration

  • Go to the “Integrations center” section -> “Integrations” page and click “plus” button to create new integration. Name it “HTTP Integration”, select type ‘HTTP’. Click “Next”;

image

  • At this step, you can select a previously created or create a new upnlink converter right in this window. Select the previously created “HTTP Uplink Converter”. Click “Next”;

image

  • At the step of adding a downlink converter, you can also select a previously created or create a new downlink converter. But for now, leave the “Downlink data converter” field empty. Click “Skip”;

image

  • At this step, specify your ‘Base URL’;

  • Please note down ‘HTTP endpoint URL’ we will use this value later;

  • In ‘Advanced settings’ enable “Replace response status from ‘No-Content’ to ‘OK’”;

  • Click “Add” button to save the Integration.

image

To send an uplink message, you need the previously copied ‘HTTP endpoint URL’ from the integration.

Use this command to send the message. Don’t forget to replace $DEVICE_NAME, $DEVICE_TYPE and $YOUR_HTTP_ENDPOINT_URL with corresponding values.

1

curl -v -X POST -d "{\"deviceName\":\"$DEVICE_NAME\",\"deviceType\":\"$DEVICE_TYPE\",\"temperature\":33,\"model\":\"test\"}" $YOUR_HTTP_ENDPOINT_URL -H "Content-Type:application/json"

image


Go to the “Events” tab in your HTTP integration. If you have done everything correctly, you should see one event with the status ‘OK’.

image


When you sent the message, a new device was created. You should receive a notification about it. To view notification, click on the bell icon in the upper right corner of the screen. The notification will contain an action button by clicking which you can go to the details of the new device. Click this button.

image


Here you will see information about the new device. As well as the telemetry which we sent from the device to the ThingsBoard.

image


Learn more about notifications and how to configure them here.

Doc info icon

NOTE
If the “Allow create devices or assets” checkbox is unchecked, when sending a message to the ThingsBoard with any parameters of the device (or asset), if such a device (asset) does not exist, then device (asset) will not be created.

Also, sent and received data can be viewed in the Uplink converter. In the ‘In’ and ‘Out’ blocks of the “Events” tab.


Use the Dashboards to work with data. Dashboards are a modern format for collecting and visualizing data sets. Visibility of data presentation is achieved through a variety of widgets.
ThingsBoard has examples of several types of dashboards that you can use. Learn more about Solution templates here.

image

Enable security option

If necessary, you can specify additional parameters, without which the data will not be included in the integration. To do this, check the Enable security checkbox and click on the Headers filter. Specify an arbitrary value and save the changes.

image

Once the Headers filter has been configured, it will also need to be specified in the uplink message as follows:

1

-H "test-header:secret"

Use this command to send the message with enable security option. Don’t forget to replace $DEVICE_NAME, $DEVICE_TYPE, $YOUR_HTTP_ENDPOINT_URL and $VALUE with corresponding values.

1

curl -v -X POST -d "{\"deviceName\":\"$DEVICE_NAME\",\"deviceType\":\"$DEVICE_TYPE\",\"temperature\":33,\"model\":\"test\"}" $YOUR_HTTP_ENDPOINT_URL -H "Content-Type:application/json" -H "$VALUE"

image

Create downlink converter in the “Data converters” page. To see events enable ‘Debug mode’.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

TBELRecommended
JavaScript

image


Add a converter to the integration. You can customize a downlink according to your configuration. Let’s consider an example where we send an attribute update message. So we should change code in the downlink encoder function under line //downlink data input:

1

data: JSON.stringify(msg)

where msg is the message that we receive and send back to the device.

image


An example of downlink converter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",

    // downlink data
    data: JSON.stringify(msg),

    // Optional metadata object presented in key/value format
    metadata: {
    }
};

return result;

image


Add a converter to the integration. You can customize a downlink according to your configuration. Let’s consider an example where we send an attribute update message. So we should change code in the downlink encoder function under line //downlink data input:

1

data: JSON.stringify(msg)

where msg is the message that we receive and send back to the device.

image


An example of downlink converter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

var result = {

    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",

    // downlink data
    data: JSON.stringify(msg),

    // Optional metadata object presented in key/value format
    metadata: {
    }
};

return result;

Now you need to add the created downlink converter to the integration.

image


To be able to send downlink over integration we need to modify a “Root Rule chain”:

  • Go to the “Rule chains” page and click on the “Root Rule Chain” to open it;
  • Create an ‘integration downlink’ node. Specify your integration in its settings;

image

  • Set the “Attributes updated” and “Post attributes” links from the ‘message type switch’ node to the ‘integration downlink’ node. Apply changes.

image


When the attribute is created or changes are made to the attribute, the downlink message will be sent to the integration.

To see this with an example, we go to the “Devices” page. Select your device and navigate to the “Attributes” tab. Select Shared attributes and click on the “plus” icon to create new attribute. Then set the attribute name, its value (for example, the key name is ‘firmware’, value: ‘01052020.v1.1’) and save the data.

image


Send the uplink message again. We will receive a response from the ThingsBoard in the terminal:

Received data and data that was sent can be viewed in the downlink converter. In the “In” block of the Events tab, we see what data entered and in the “Out” field, the message sent to the device is displayed:

Next steps