TCP Integration

TCP Integration streams data from devices over the TCP transport protocol into ThingsBoard and converts device payloads to the ThingsBoard format. TCP Integration always runs as a remote integration — it can run on the same machine as your ThingsBoard instance or on a separate machine with network access to it.

This tutorial uses:

• A ThingsBoard Professional Edition instance running locally.
• TCP Integration running as a remote integration connected to the ThingsBoard instance. Port 10560 must be open for incoming connections on the machine running TCP Integration.
• The echo command piped to netcat (nc) to send data over TCP.

The example device SN-002 publishes temperature and humidity readings to the TCP Integration on port 10560.

Three payload formats are demonstrated — select the one that matches your device:

SN-002,default,temperature,25.7\nSN-002,default,humidity,69

[
  {
    "deviceName": "SN-002",
    "deviceType": "default",
    "temperature": 25.7,
    "humidity": 69
  }
]

\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

TCP uses a generic uplink converter. The uplink converter receives the raw TCP message bytes as a payload byte array — already framed and stripped by the handler configured in the connection settings. It must return an object with at least deviceName and deviceType. Optionally, it can include telemetry (time-series measurements) and attributes (device properties) as flat key-value maps.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Set Converter type to Uplink (default).
4. Select Integration type: TCP.
5. Enter a converter name: TCP Uplink Converter.
6. Paste the decoder function from the tab below.

Select the tab matching your payload type:

/** Decoder **/

// decode payload to string
var strArray = decodeToString(payload);
var payloadArray = strArray.replaceAll("\"", "").replaceAll("\\n", "").split(',');

var telemetryPayload = {};
for (var i = 2; i < payloadArray.length; i = i + 2) {
    var telemetryKey = payloadArray[i];
    var telemetryValue = parseFloat(payloadArray[i + 1]);
    telemetryPayload[telemetryKey] = telemetryValue;
}

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

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

return result;

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

/** Decoder **/

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

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

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

return result;

/** Decoder **/

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

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) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

return result;

/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(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 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

/** Decoder **/

// decode payload to string
var payloadStr = decodeToString(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) {
   var str = decodeToString(payload);
   var data = JSON.parse(str);
   return data;
}

return result;

7. Optionally, click Test payload decoder to validate.
8. Click Add.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to TCP.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Select existing — choose the TCP Uplink Converter created above.
   • Click Next.
4. Downlink data converter:
   • Click Skip — the downlink converter can be added later.
5. Connection settings:
   • Port — 10560 by default; change if needed.
   • Copy the Integration key and Integration secret — required when configuring the remote TCP Integration service.
   • Select your payload type and configure the frame handler — see Handler configuration below.
6. Click Add to save the integration.

Set Integration type to TCP, enter a name, and click Next Select existing, choose TCP Uplink Converter, and click Next Leave the Downlink data converter empty and click Skip — it can be added later Copy the Integration key and secret, set Handler Configuration to match your payload type, and click Add

Handler configuration

The frame handler controls how TCP reads the incoming byte stream and extracts individual messages. Select the handler matching your payload format:

• Text
• JSON
• Binary

Parameter	Value	Description
Max Frame Length	128	Maximum length of a decoded frame.
Strip Delimiter	enabled	Drops the newline delimiter from the decoded payload.
Message Separator	System Line Separator	Newline (\n) used as the message delimiter.

Port

Integration key and secret

Generated automatically when Execute remotely is enabled. Required when starting the remote TCP Integration service — copy both values before closing the wizard.

Socket options

Downlink cache

Follow the remote integration guide to install and start the TCP Integration service. Use the Integration key and Integration secret from the connection settings step above.

Once the TCP integration is active, the TCP server starts and listens for device connections.

Select your payload type:

• Text
• JSON
• Binary

Send a single message:

echo -e 'SN-002,default,temperature,25.7' | nc -q0 127.0.0.1 10560

Multiple messages (newline-delimited):

echo -e 'SN-002,default,temperature,25.7\nSN-002,default,humidity,69' | nc -q1 -w1 127.0.0.1 10560

To receive a downlink response, keep the connection open:

echo -e 'SN-002,default,temperature,25.7' | nc 127.0.0.1 10560

Multiple messages with open connection:

echo -e 'SN-002,default,temperature,25.7\nSN-002,default,humidity,69' | nc -w60 127.0.0.1 10560

Go to Entities ⇾ Devices. Device SN-002 is auto-created on the first uplink. Open the Latest Telemetry tab to confirm temperature = 25.7.

To send messages from ThingsBoard back to a device, add a downlink converter to the integration and configure a rule chain to forward attribute changes to it.

The downlink converter encodes outgoing ThingsBoard messages into the format expected by the device.

The encoder used in this tutorial:

/** Encoder **/

var data = {};

data.tempFreq = msg.temperatureUploadFrequency;
data.humFreq = msg.humidityUploadFrequency;
data.devSerialNumber = metadata['ss_serialNumber'];

var result = {
    contentType: "JSON",
    data: JSON.stringify(msg),
    metadata: {
        topic: metadata['deviceType'] + '/' + metadata['deviceName'] + '/upload'
    }
};

return result;

/** Encoder **/

var data = {};

data.tempFreq = msg.temperatureUploadFrequency;
data.humFreq = msg.humidityUploadFrequency;
data.devSerialNumber = metadata['ss_serialNumber'];

var result = {
    contentType: "JSON",
    data: JSON.stringify(msg),
    metadata: {
        topic: metadata['deviceType'] + '/' + metadata['deviceName'] + '/upload'
    }
};

return result;

1. Go to Integrations center ⇾ Integrations, open the TCP integration, and click the edit (pencil) icon.
2. In the Downlink data converter field, enter a name and click Create new converter.
3. Paste the encoder script and click Add.
4. Click Apply changes.

Open the TCP integration and click the pencil icon to enter edit mode Enter a name in the Downlink data converter field and click Create new converter Paste the encoder script and click Add Both converters are now set — click Apply changes to save

1. Go to Rule chains and open the Root Rule Chain.
2. Find the Integration Downlink node, drag it onto the canvas, name it TCP integration downlink, select the TCP integration, and click Add.
3. Connect the Message Type Switch node to the Integration Downlink node using the Attributes Updated relation type and click Apply changes.

Drag the Integration Downlink node onto the canvas, name it TCP integration downlink, select TCP Integration, and click Add Connect Message Type Switch to the Integration Downlink node via Attributes Updated, then click Apply changes

1. Go to Entities ⇾ Devices, open device SN-002, and click the Attributes tab.
2. Switch to Shared attributes and click +.
3. Enter an attribute key and value (e.g. key: firmware, value: v1.1) and click Add.

Open device SN-002, go to the Attributes tab, select Shared attributes, and click + Enter key firmware, value v1.1, and click Add Shared attribute firmware = v1.1 saved — the Attributes Updated message triggers the downlink

To receive the downlink response, keep the connection open with -w60 and send an uplink:

echo -e -n '{"deviceName": "SN-002", "deviceType": "default", "temperature": 25.7, "humidity": 69}' | nc -w60 127.0.0.1 10560

To verify the downlink, go to Integrations center ⇾ Data converters, open the downlink converter, and check the Events tab. The In block shows the incoming message from the rule chain; the Out block shows the encoded payload sent to the device. When the TCP connection stays open for an extended time, only one downlink message is delivered immediately — subsequent messages are queued and sent on the next uplink.

In event: ATTRIBUTES_UPDATED message with firmware attribute received from the rule chain Out event: encoded JSON payload with firmware attribute sent to the device

• Integration Overview
• Remote Integrations
• Uplink Converters
• Downlink Converters
• Rule Engine
• ThingsBoard Expression Language (TBEL)