PE Edge
ThingsBoard PE Edge Documentation
Cloud Professional Edition Community Edition Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Try it now Pricing
Documentation > Integrations > TCP
Getting Started
Installation Architecture API FAQ

On this page

TCP Integration

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

Overview

TCP Integration allows to stream data from devices which use a TCP transport protocol to ThingsBoard Edge and converts payloads of these devices into the ThingsBoard Edge format.

TCP Integration can be started only as Remote Integration. It could be started on the same machine, where TB Edge instance is running, or you can start in on another machine, that has access over the network to the TB Edge instance.

Please review the integration diagram to learn more.

image

Prerequisites

In this tutorial, we will use:

  • ThingsBoard PE Edge;
  • TCP Integration, running externally and connected to the cloud ThingsBoard Edge instance;
  • echo command which intended to display a line of text, and will redirect it’s output to netcat (nc) utility;
  • netcat (nc) utility to establish TCP connections, receive data from there and transfer them;

Let’s assume that we have a sensor which is sending current temperature and humidity readings. Our sensor device SN-002 publishes it’s temperature and humidity readings to TCP Integration on 10560 port to the machine where TCP Integration is running.

For demo purposes we assume that our device is smart enough to send data in 3 different payload types:

  • Text - in this case payload is SN-002,default,temperature,25.7\n\rSN-002,default,humidity,69
  • JSON - in this case payload is
1
2
3
4
5
6
7
8
[
  {
    "deviceName": "SN-002",
    "deviceType": "default",
    "temperature": 25.7,
    "humidity": 69
  }
]
  • Binary - in this case binary payload is \x30\x30\x30\x30\x11\x53\x4e\x2d\x30\x30\x32\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x00\x00\x00 (in HEX string). Here is the description of the bytes in this payload:
    • 0-3 bytes - \x30\x30\x30\x30 - dummy bytes to show how you can skip particular prefix bytes in your payload. These bytes are included for sample purposes;
    • 4 byte - \x11 - payload length. If we convert it to decimal - 17. So our payload in this case is limited to 17 bytes from the incoming TCP frame;
    • 5-10 bytes - \x53\x4e\x2d\x30\x30\x32 - device name. If we convert it to text - SN-002;
    • 11-17 bytes - \x64\x65\x66\x61\x75\x6c\x74 - device type. If we convert it to text - default;
    • 18-21 bytes - \x32\x35\x2e\x37 - temperature telemetry. If we convert it to text - 25.7;
    • 22-24 bytes - \x00\x00\x00 - dummy bytes. We are going to ignore them, because payload size is 17 bytes - from 5 till 21 byte. These bytes are included for sample purposes;

You can select payload type based on your device capabilities and business cases.

On the machine, where remote TCP Integration is running, port 10560 must be opened for incoming connections - nc utility must be able to connect to TCP socket. In case you are running it locally, it should be fine without any additional changes.

Create Converter templates

Converter and Integration templates are created on the Cloud, so please log in as Tenant administrator to cloud instance.

Before creating the Integration template, you need to create an Uplink and Downlink converter templates in Converters templates page. Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard Edge.

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.

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.

Choose device payload type to for decoder configuration:

Now copy & paste the following script to the Decoder function section:

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
/** Decoder **/

// decode payload to string
var strArray = decodeToString(payload);
var payloadArray = strArray.replace(/\"/g, "").replace(/\s/g, "").split(',');

var telemetryKey = payloadArray[2];
var telemetryValue = payloadArray[3]; 

var telemetryPayload = {};
telemetryPayload[telemetryKey] = telemetryValue;

// Result object with device attributes/telemetry data
var result = {
    deviceName: payloadArray[0],
    deviceType: payloadArray[1],
    telemetry: telemetryPayload,
    attributes: {}
  };

/** Helper functions **/

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

return result;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

Now copy & paste the following script to the Decoder function section:

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
/** Decoder **/

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

// Result object with device/asset attributes/telemetry data

var deviceName = data.deviceName;
var deviceType = data.deviceType;
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {},
   telemetry: {
       temperature: data.temperature,
       humidity: data.humidity
   }
};

/** 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;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

Now copy & paste the following script to the Decoder function section:

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
/** Decoder **/

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

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

var deviceName = payloadStr.substring(0,6);
var deviceType = payloadStr.substring(6,13);

// Result object with device/asset attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {},
   telemetry: {
       temperature: parseFloat(payloadStr.substring(13,17))
   }
};

/** 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;

The purpose of the decoder function is to parse the incoming data and metadata to a format that ThingsBoard can consume. deviceName and deviceType are required, while attributes and telemetry are optional. attributes and telemetry are flat key-value objects. Nested objects are not supported.

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.

Create Downlink in Converter templates page as well. To see events select Debug checkbox.

You can customize a downlink according to your configuration. Let’s consider an example where we send an attribute update message. 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;

Create Integration template

Now that the Uplink and Downlink converter templates have been created, it is possible to create an integration. Go to Integration templates section and click Add new integration button. Name it TCP Integration, select type TCP, turn the Debug mode on and from drop-down menus add recently created Uplink and Downlink converters.

As you mentioned Execute remotely is checked and can not be modified - TCP Integration can be only remote type.

Please note down Integration key and Integration secret - we will use these values later in the configuration on the remote TCP Integration itself.

By default, TCP Integration will use 10560 port, but you can change this to any available port in your case.

We leave other options by default, but there is brief description of them:

  • Max number of pending connects on the socket - The maximum queue length for incoming connection indications (a request to connect) is set to the backlog parameter. If a connection indication arrives when the queue is full, the connection is refused;
  • Size of the buffer for inbound socket - the size in KBytes of the socket data receive buffer;
  • Size of the buffer for outbound socket - the size in KBytes of the socket data send buffer;
  • Enable sending of keep-alive messages on connection-oriented sockets - a flag indicating that probes should be periodically sent across the network to the opposing socket to keep the connection alive;
  • Forces a socket to send the data without buffering (disable Nagle’s buffering algorithm) - disables Nagle’s algorithm on the socket which delays the transmission of data until a certain volume of pending data has accumulated.

Choose device payload type for Handler Configuration:

Please select Handler Type as TEXT

In our example we are going to split incoming text payload SN-002,default,temperature,25.7\n\rSN-002,default,humidity,69 into two different messages

  • SN-002,default,temperature,25.7
  • SN-002,default,humidity,69

Newline delimiter (\n\r) will be used to split payload into multiple messages.

image

To parse payload properly, please make sure that next values are set:

  • Max Frame Length - the maximum length of the decoded frame. An exception will be thrown if the length of the frame exceeds this value; Leave it by default for this demo - 128;
  • Strip Delimiter - whether the decoded frame should strip out the delimiter or not. Please check it to drop newline delimiter from the payload;
  • Message Separator - specify it to System Line Separator - in this case newline symbol will be used as delimiter;

Please select Handler Type as JSON

image

Please select Handler Type as BINARY

In our example we are going to parse incoming binary payload \x30\x30\x30\x30\x11\x53\x4e\x2d\x30\x30\x32\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x00\x00\x00 (in HEX).

According to our payload design:

  • 0-3 bytes - \x30\x30\x30\x30 - dummy bytes to show how you can skip particular prefix bytes in your payload. These bytes are included for sample purposes;
  • 4 byte - \x11 - payload length. If we convert it to decimal - 17. So our payload in this case is limited to 17 bytes from the incoming TCP frame;
  • 5-10 bytes - \x53\x4e\x2d\x30\x30\x32 - device name. If we convert it to text - SN-002;
  • 11-17 bytes - \x64\x65\x66\x61\x75\x6c\x74 - device type. If we convert it to text - default;
  • 18-21 bytes - \x32\x35\x2e\x37 - temperature telemetry. If we convert it to text - 25.7;
  • 22-24 bytes - \x00\x00\x00 - dummy bytes. We are going to ignore them, because payload size is 17 bytes - from 5 till 21 byte. These bytes are included for sample purposes;

we need to properly configure handler configuration to get from the incoming payload required data: \x53\x4e\x2d\x30\x30\x32\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37 which equals to SN-002default25.7 in text representation.

image

To parse payload properly, please make sure that next values are set:

  • Max Frame Length - the maximum length of the decoded frame. An exception will be thrown if the length of the frame exceeds this value; Leave it by default for this demo - 128;
  • Length Field Offset - the offset of the length field. In our case length field is 5th byte in the payload \x30\x30\x30\x30 \x11 \x53…. So set it to 4;
  • Length Field Length - the length of the length field. In our case length of the length field is 1 byte …\x30 \x11 \x53…. So set it to 1;
  • Length Adjustment (the compensation value to add to the value of the length field) - the compensation value to add to the value of the length field. In our case we don’t need this compensation, as length field contains correct value - 17 bytes. So leave it 0;
  • Number of first bytes to strip out from the decoded frame - the number of first bytes to strip out from the decoded frame. We need to skip first 5 bytes from the decoded payload, to get our data - \x30\x30\x30\x30\x11 \x53\x4e\x2d\x30…. So set it to 5;

Click Add to save the Integration.

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 cloud. For example, create an integration downlink node and set the ‘Attributes updated’ link to it. When changes are made to device attribute, the downlink message will be sent to the integration.

Assign Integration to Edge

Once converter and integration templates are created, we can assign Integration template to Edge.

  • Click Manage Integrations button of Edge entity
  • Assign Integration to the Edge
  • Login to your ThingsBoard PE Edge instance and open Integrations page

Installing and running external TCP Integration

Please refer to the Remote Integration guide and install TCP Integration service locally or on separate machine.

Please use Integration key and Integration secret from the above section for your TCP Integration configuration.

Once ThingsBoard TCP Integration has been created, the TCP server starts, and then it waits for data from the devices.

Choose device payload type to send uplink message:

The created device with data can be seen in the section Device groups -> All on the Edge:

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 firmware shared attribute:

To make sure that downlink message sent to integration you can check ‘Events’ tab of integration:

Now we’ll need to send again message to TCP integration and see downlink response. Please use the same command that was used before.

An example of sent message and a response from ThingsBoard Edge in the terminal:

Next steps