Stop the war

Stand with Ukraine flag

Support Ukraine

Try it now Pricing
PE Edge
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation > Integrations > HTTP
Getting Started
Installation Architecture API FAQ
On this page

HTTP Integration

Doc info icon

Edge HTTP Integration is implemented in a similar way, as HTTP Integration. The only difference is in the way, how integration is created and provisioned. Please make sure that you have knowledge of HTTP Integration before proceed.

Overview

HTTP Integration allows converting existing protocols and payload formats to ThingsBoard Edge 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 Edge.

Create converter and integration templates

Converter and integration templates are created only on the ThingsBoard Professional Edition. So please use ThingsBoard Cloud or install your own platform instance to log in as Tenant administrator.

Follow the steps below to add the HTTP integration:

  • Go to “Edge management” section -> “Integration templates” page and click “plus” button to add new integration. Select type ‘HTTP’. Name it “Edge HTTP integration”. Then, click “Next”;
Doc info icon

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.

image

  • The next step is create an Uplink data converter.

Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard. For this example, use the code below.

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.

Copy the following script:

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;

Choose “Create new” and paste copied code to the Decoder function section. Click “Next”;

image

Copy the following script:

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;

Choose “Create new” and paste copied code to the Decoder function section. Click “Next”;

image

  • At the next step is create a Downlink converter.

The Downlink converter transforms outgoing RPC message and then the integration sends it to your device. You can customize a downlink according to your configuration. Let’s consider an example where we send an attribute update message. For this example, use the code below.

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.

Copy the following script:

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;

Choose “Create new” and paste copied code to the Encoder function section. Click “Next”;

image

Copy the following script:

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;

Choose “Create new” and paste copied code to the Encoder function section. Click “Next”;

image

  • Finally, we go to the “Connection” page:

    • Enter IP address and port of your Edge instance in the format: ‘host:port’ as ‘Base URL’. Or, you can use placeholder ${{ATTRIBUTE_KEY}} to substitute integration field with attribute value from specific Edge entity. In this example, we will use the placeholder ${{baseUrl}} for ‘Base URL’.
    • Then, click the “Add” button.

image


HTTP integration is created.

We can send a downlink message to the device from Rule chain using the rule node. To be able to send downlink over integration we need to modify “Edge Root Rule chain” on the ThingsBoard PE.

  • Go to the "Edge management" section -> "Rule chain templates" page and click on the "Edge Root Rule Chain" to open it;
  • Create an 'integration downlink' node. Specify your integration in its settings;
  • Set the "Attributes Updated" and "Post attributes" links from the 'message type switch' node to the 'integration downlink' node. When the attribute is created or changes are made to the attribute, the downlink message will be sent to the integration. Apply changes.

Assign Integration to Edge

Once converter and integration templates are created, we can assign Integration template to Edge. Because we are using placeholder ${{baseUrl}} in the integration configuration, we need to add attribute ‘baseUrl’ to edge first. You need to provide IP address and port of your Edge instance as ‘baseUrl’ attribute. Once attribute added, we are ready to assign integration and verify that it’s added.

  • Go to the "Edge management" section -> "Instances" page, click on your edge instance to open "Edge details" window, and navigate to the "Attributes" tab. Click "plus" icon to add new server attribute to Edge;
  • Named baseUrl and set value as your Edge IP:port. After, click "Add" button;
  • Added the server attribute ''baseUrl'' to the edge;
  • Now, click "Manage edge integrations" icon of Edge entity;
  • Click the "+" icon at the top right of the corner. Specify your integration and click "Assign" button to assign it to the Edge;
  • Login to your ThingsBoard Edge instance and open "Integrations center" section -> "Integrations" page. You should see your integration. Click on it;
  • In the "Integration details" window placeholder ${{baseUrl}} will be replaced with the value of the attribute.

To send an uplink message, you need ‘HTTP endpoint URL’ from the integration. Log in to ThingsBoard Edge and go to the “Integrations center” section -> “Integrations” page. Find your HTTP integration and click on it. Find and copy the ‘HTTP endpoint URL’.

Use the command below to send a message. Don’t forget to replace $DEVICE_NAME and $YOUR_HTTP_ENDPOINT_URL with corresponding values.

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

image

Now, navigate to the “Events” tab in your HTTP integration. If you have done everything correctly, you will find an uplink message with the status ‘OK’. To see the message itself, click the three dots in the ‘Message’ column.

image

When you sent the message, a new device was created. The created device with data can be seen in the “Entities” section -> “Devices” page on the Edge:

image

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

Now let’s check downlink functionality. Let’s add a ‘firmware’ shared attribute. Go to the “Devices” page, select your device, and navigate to the “Attributes” tab on the ThingsBoard Edge. Select the “Shared attributes” scope 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

To make sure that downlink message sent to integration you can check “Events” tab of the integration:

image

Now we’ll need to send again message to HTTP integration. Please use the same command that was used before. Don’t forget to replace $DEVICE_NAME and $YOUR_HTTP_ENDPOINT_URL with corresponding values.

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

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