Star

ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

TCP Integration


ThingsBoard PE Feature


Only ThingsBoard Professional Edition supports Platform Integrations feature.

See ThingsBoard PE Installation Options to install ThingsBoard PE.

Overview

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

Please review the integration diagram to learn more.

image

Setup TCP Integration

For messages in string format

Go to Integrations section and click Add new integration button. Name it Demo TCP TEXT Integration Test, select type TCP, turn the Debug mode on and from drop-down menus add recently created Uplink and Downlink converters.

Specify Port: 10562 for Text Channel Inbound Handler which work depends on the so-called Text Delimiter Decoder.

Text Delimiter Decoder that splits the received ByteBufs by one or more delimiters. It is particularly useful for decoding the frames which ends with a delimiter such as NUL or newline characters.
In order for this class to work correctly, we must correctly set the following parameters:

Text Channel Inbound Handler is specific handler class which allows to explicit only handle a ByteBuf type of messages.

For messages in binary format

Go to Integrations section and click Add new integration button. Name it Demo TCP BINARY Integration Test, select type TCP, turn the Debug mode on and from drop-down menus add recently created Uplink and Downlink converters.

Specify Port: 10563 for Binary Channel Inbound Handler which work depends on the so-called Binary Frame Decoder.

Binary Frame Decoder extends LengthFieldBasedFrameDecoder class and receives ByteBufs, reads the first two bytes, then casts them to a long number, which is the length of the message and reads the message byte by its length.</br> In order for this class to work correctly, we must correctly set the following parameters:

Binary Channel Inbound Handler is specific handler class which allows to explicit only handle a ByteBuf type of messages.

A brief description of Socket Channel Options used to configure the server

Then we need to configure the Handler Configuration. Handler Type: TEXT or BINARY.

If TEXT then we will need to set Charset name and Message Separator else if BINARY then we will need to set Message size. We use TEXT so then Charset name is ‘UTF-8’ and Message Separator is System Line Delimiter.

Click Add to save the Integration.

Before setting up an TCP integration, you need to create an Uplink Converter that is a script for parsing and transforming the data received by TCP integration.

To create an Uplink Converter go to Data Converters section and Click Add new data converter —> Create new converter. Name it “TCP Uplink Converter” and select type Uplink. Use debug mode for now.

NOTE Although the Debug mode is very useful for development and troubleshooting, leaving it enabled in production mode may tremendously increase the disk space, used by the database, because all the debugging data is stored there. It is highly recommended to turn the Debug mode off when done debugging.

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

/** Decoder **/

// decode payload to string

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

var result = {
    deviceName: payloadArray[0],
    deviceType: payloadArray[1],
    telemetry: {
      temperature: payloadArray[2],
      humidity: payloadArray[3]
    },
    attributes: {
      boolValue: payloadArray[4],
      serialNumber: payloadArray[5]
    }
  };

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.

In current implementation does not use the the DownLink Converter

Prerequisites to testing TCP Integration

In order to test the work of a TCP integration, in this tutorial we will use:

Let’s suppose that we have a device with some name, let’s say MyDummyDeviceA, and some kind of message, with the following content:

msg: 'MyDummyDeviceA,TCPDevice,45.2,57.3,false,40'

The command to send a message to the TCP server will look like this:

echo MyDummyDeviceA,TCPDevice,45.2,57.3,false,40 | netcat <thingsbord-name-cloud-host> 10562 (or 10563 for BINARY configuration)

We can also send multiple messages in one string, separated by Message Separator (System Line Delimiter). In this case, the command will look like this:

echo MyDummyDeviceA,TCPDevice,45.2,57.3,false,40<lineSeparator>MyDummyDeviceB,TCPDevice,39.2,81.2,true,39 | netcat <thingsbord-name-cloud-host> 10562 (or 10563 for BINARY configuration)

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

Now let’s simulate the device sending a temperature reading to the integration:

echo MyDummyDeviceA,TCPDevice,25.2,57.3,false,40<lineSeparator> | netcat <thingsbord-name-cloud-host> 10562 (or 10563 for BINARY configuration)

Once you go to Device Groups -> All you should find a MyDummyDeviceA device provisioned by the Integration. Click on the device, go to Latest Telemetry tab to see “temperature” key and its value (25.2) and “humidity” key and its value (57.3) there.

Video tutorial

See video tutorial below for step-by-step instruction how to setup TCP Integration.


Next steps