TCP Integration

TCP Integration connects ThingsBoard to devices that communicate over raw TCP sockets. It listens on a configured port, frames the incoming byte stream into discrete messages, decodes each message through the Uplink Converter, and maps the result to ThingsBoard telemetry and attributes. It also supports downlink — sending messages back to devices over the same TCP connection.

When to use TCP Integration:

• Devices use a custom binary or text protocol over a raw TCP socket.
• Firmware already opens a TCP connection to a configurable host and port.
• You need a persistent, connection-oriented channel for both telemetry and commands.

Before creating the integration, ensure:

• You have access to a ThingsBoard Professional Edition instance with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• You know the payload format and framing protocol your TCP devices use.
• Port 10560 (or whichever port you configure) must be open for incoming TCP connections on the machine running the TCP Integration process. The remote process also needs outbound access to ThingsBoard’s gRPC port 9090.
• The echo command piped to netcat (nc) is available for sending test data over TCP.

In this tutorial, device SN-002 sends temperature and humidity readings to the TCP Integration server on port 10560.

The integration accepts three payload formats:

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

The decoder function receives the raw TCP message bytes as a payload byte array — already extracted from the byte stream by the handler configured in the Connection settings, with framing bytes stripped. 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.

For the full decoder function reference — all input parameters and output fields — see Uplink data converter.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.

In the Add data converter dialog:

3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter TCP and select TCP from the list.
5. Name — enter a converter name, for example TCP Uplink Converter.
6. Main decoding configuration — paste the decoder function from the appropriate tab below, then continue with step 7.

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 the script against a sample payload.
8. Click Add.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Select TCP as the integration type.
   • Enter a name — for example, TCP integration.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the TCP Uplink Converter created in the previous step, or click Create new to define the decoder inline.
   • Click Next.
4. Downlink data converter:
   • Click Skip for now. You can add a downlink converter later.
5. Connection settings:
   • Set the Port — default is 10560. This port must be open on the machine running the TCP Integration process.
   • The Execute remotely option is always enabled for TCP. Copy the Integration key and Integration secret — you will need them to start the remote integration process.
   • Configure the Handler Configuration — select the message framing strategy that matches your device protocol. See Handler Configuration below.
   Read more about each parameter in Connection Settings.
6. Click Add.

Select TCP as the integration type, enter a name, and click Next Select an existing uplink converter or create a new one, then click Next Skip the downlink converter for now — you can add it later Set the port, copy the Integration key and secret, select the Handler Configuration, and click Add

Port

The TCP port the integration server will bind to. Default: 10560. The port must be open on the machine running the TCP Integration process and must not be shared with another integration in the same ThingsBoard tenant environment.

Max number of pending connects on the socket

The maximum length of the queue for incoming connections that have not yet been accepted. Default: 128. Increase this value under high connection concurrency.

Size of the buffer for inbound / outbound socket (in KB)

The socket receive and send buffer sizes in kilobytes. Default: 64 KB each. Increase for high-throughput devices that send large payloads.

Enable sending of keep-alive messages on connection-oriented sockets

When enabled, the OS sends TCP keep-alive probes to detect dead connections. Disabled by default. Enable when devices maintain long-lived connections that may silently drop.

Forces a socket to send the data without buffering (disable Nagle’s algorithm)

When enabled, sends each write immediately rather than batching small packets. Enabled by default. Disable only if you send many small messages in rapid succession and want to reduce the number of TCP segments.

Execute remotely

Always enabled for TCP Integration. Shows the Integration key and Integration secret — credentials required to launch the TCP Integration as a standalone remote process. See Remote Integration for full setup instructions.

Advanced settings

Because TCP is a stream protocol with no built-in message boundaries, the integration must be told how to split the stream into individual messages. Select the handler that matches your device protocol:

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.

After the integration is created, send a test uplink and confirm that ThingsBoard received the message, decoded it correctly, and provisioned the device.

Once the TCP Integration process is running, the TCP server starts and listens for device connections. Use netcat (nc) to simulate a device sending data.

Select your payload type:

• Text
• JSON
• Binary

Send a message:

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

Multiple messages (newline-delimited):

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

To receive a downlink response, keep the connection open:

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

Multiple messages with open connection:

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

Go to Integrations center ⇾ Integrations, open TCP integration, and click the Events tab. Each successfully processed uplink appears as a row with status OK.

To inspect converter processing, go to Integrations center ⇾ Data converters, click TCP Uplink Converter, and open its Events tab:

• In — what the integration received (the raw payload bytes)
• Out — what the converter returned
• Error — error text, if any

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

Downlink allows ThingsBoard to send messages back to devices over TCP — for example, in response to an RPC call or a shared attribute update. The message is delivered over the same TCP connection the device used to send its last uplink.

The downlink converter transforms a Rule Engine message into the bytes sent back to the device. The integration appends a \n newline after every downlink payload — device-side parsers should expect and strip this trailing byte.

1. Go to Integrations center ⇾ Integrations and open the TCP integration.
2. Click the pencil icon to enter edit mode.
3. In the Downlink data converter field, click Create new.
4. Enter a name, paste the encoder script shown below, then click Add.
5. Click Apply changes.

Select your script language:

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

Open the TCP integration and click Toggle edit mode (pencil button, top right) Click Create new in the Downlink data converter field Enter a name, paste the encoder script, then click Add Downlink converter assigned — click Apply changes to save

To send downlinks through the integration, modify the Root Rule Chain:

1. Go to Rule chains and open the Root Rule Chain.
2. Find the integration downlink node in the node library panel on the left. Drag it onto the canvas.
3. In the node configuration dialog, enter a name (e.g. Downlink to TCP integration) and select your TCP integration. Click Add.
4. Connect the message type switch node to the newly created integration downlink node using the Post attributes and Attributes Updated relation types to trigger downlinks whenever shared attributes are created or updated.
5. Apply the changes.

Open the Root Rule Chain, locate the integration downlink node in the node palette and drag it onto the rule chain canvas. Enter a node name, select the target TCP Integration, and click Add. Connect the message type switch node to the newly created integration downlink node using the Post attributes and Attributes Updated relation types to trigger downlinks whenever shared attributes are created or updated.

Open a persistent TCP connection to receive the downlink and keep it open:

nc localhost 10560

Then type uplink manually and press Enter:

SN-002,default,temperature,25.7

Do not close the terminal.

Trigger a downlink by adding a shared attribute to the device:

1. Go to Entities ⇾ Devices, open SN-002, and navigate to the Attributes tab.
2. Select Shared attributes, click + to add a new attribute.
3. Set the key (e.g. powerState) and value (e.g. on).
4. Click Add.

The Rule Engine routes the attribute creation message to the Integration Downlink node, which encodes it and sends it to the device. The terminal will print:

john@doe:~$ nc localhost 10560
SN-002,default,temperature,25.7
{"powerState":"on"}

To inspect the exchange, open the downlink converter’s Events tab:

• In shows the Rule Engine message
• Out shows the encoded payload sent to the device
• Metadata shows additional context

• Integrations Overview — how ThingsBoard connects to external platforms and how uplink/downlink flow works
• Uplink Data Converter — full decoder function reference: input parameters, output fields, and scripting patterns
• Downlink Data Converter — full encoder function reference for sending commands to devices
• Remote Integration — install and run the TCP Integration as a standalone process outside the ThingsBoard server
• TBEL scripting reference — built-in functions and operators for writing converter scripts
• Rule Engine — how uplink messages are processed after the converter runs