TCP Integration

TCP Integration lets devices send data to ThingsBoard over raw TCP connections. The integration runs a TCP server and splits the incoming byte stream into messages. An uplink data converter transforms each message into device or asset data, including telemetry and attributes. ThingsBoard can also send a downlink message back over the device’s open connection.

Use TCP Integration when:

• Devices use a custom text or binary protocol over raw TCP.
• Device firmware already connects to a configurable host and port.
• Devices keep a long-lived connection and must receive commands over it.

1. Receive data. A device opens a TCP connection to the remote integration and sends data. The handler (Text, JSON, or Binary) splits the byte stream into separate messages.
2. Decode the payload. The uplink converter identifies the device or asset in each message and extracts attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard can create an entity that does not exist yet.
4. Send downlink data (optional). The downlink converter encodes the Rule Engine message, and the integration writes it to the device’s open connection, followed by \n. If the device is not connected, the downlink waits for its next uplink.

• Access to ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• A host for the remote integration. Devices must reach it on the TCP port (default 10560), and it needs outbound access to ThingsBoard’s gRPC port 9090.
• The payload format and framing your devices use.
• nc (netcat) to send test data.

Create the uplink converter, assign it to a new TCP integration, start the remote integration, and send a test message.

Sample Payloads

This guide uses device SN-002, which sends temperature and humidity in one of three formats. Pick one format and use the matching decoder, handler, and test command throughout.

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 uplink converter reads one framed message and maps it to ThingsBoard entities and data. TCP Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select TCP.

4. Name — enter a name, for example TCP Uplink Converter.

5. Main decoding configuration — the editor is pre-filled with the default decoder template for JSON payloads. Replace it with the decoder for your payload format below and, if needed, adapt the field names to your device. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • Text
   • JSON
   • Binary
   • TBEL (Recommended)
   • JavaScript

   /** 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: {}
   };
   

   ▼Expand

   Each call receives one record. Position 0 is the device name, position 1 the device type, then telemetry key–value pairs.

   To adapt:

   • Another delimiter — replace split(','), for example with split(';').
   • Name or type at another position — change the payloadArray[0] and payloadArray[1] indexes.
   • Fixed telemetry keys — replace the loop with explicit assignments: telemetryPayload['temperature'] = parseFloat(payloadArray[2]);.
   • Attributes instead of telemetry — move the fields to attributes.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

Built-in helpers:

For more parsing patterns, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. The dialog opens with pre-filled Metadata rows, Payload content type set to JSON, and a sample JSON payload. Replace the payload with a message in your format. For the Text decoder, set Payload content type to Text and enter:

SN-002,default,temperature,25.7

Click Test. The Output panel shows:

{
  "deviceName": "SN-002",
  "deviceType": "default",
  "telemetry": {
    "temperature": 25.7
  },
  "attributes": {}
}

Check that deviceName is set and telemetry holds the expected keys. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select TCP.
   • Name — enter a name, for example TCP integration.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose TCP Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands to the device.
5. Connection:
   • Port — keep 10560 or enter your own.
   • Handler Type — select the handler that matches your payload format. See Handler Configuration.
   • Copy the Integration key and Integration secret. You need them to run the remote integration.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

TCP has no message boundaries, so the handler defines how the byte stream is split into messages. Select it in Handler Type (default: Binary).

Install and start the TCP integration service with the Integration key and Integration secret from the connection step. Follow the remote integration guide. Once the process connects, it opens the TCP port.

Send a message to the integration port, then confirm that ThingsBoard decoded it and created the device.

Run the command for your payload format on the remote integration host (localhost). From another machine, replace localhost with that host’s address. nc -q0 closes the connection right after sending; -q1 -w1 waits 1 second.

• Text
• JSON
• Binary

One record:

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

Two newline-separated records:

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

No output means the message was delivered.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK.
• Converter events — open TCP Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the framed message, Out shows the decoded result, and Error shows any error.
• Device — go to Devices & assets ⇾ Devices. The integration has created SN-002. Open it and confirm temperature = 25.7 on the Latest telemetry tab.

ThingsBoard sends a downlink over the open connection on which the device sent its last uplink, and appends \n to every downlink payload. If that connection is closed, the downlink is held and sent right after the device’s next uplink. The device must therefore keep the connection open to receive commands immediately.

The downlink converter turns a Rule Engine message into the bytes sent to the device. For the full encoder reference, see Downlink data converter.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and TCP integration type are preselected.
3. Enter a name, for example TCP Downlink Converter.
4. Main encoding configuration opens with a default encoder. Use the encoder shown below or your own.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add, then Apply changes.

Encoder used in this guide:

/** Encoder **/

// Encode downlink data from the incoming Rule Engine message.
// msg: JSON message payload.
// msgType: message type, e.g. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata: key-value pairs containing additional message data.
// integrationMetadata: key-value pairs configured in the integration.

var result = {
    // Specify the response body format: JSON, TEXT, or BINARY.
    contentType: "JSON",

    // Serialize the incoming message and use it as the TCP payload.
    data: JSON.stringify(msg),

    // Add optional metadata when required by the integration.
    metadata: {}
};

return result;

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

1. Go to Data processing ⇾ 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 a connection, send an uplink, then update a shared attribute to queue a downlink. The steps below use the Text handler; for another handler, send the matching payload from Sample Payloads.

1. Open a connection and keep it open:

   nc localhost 10560

2. Type an uplink and press Enter. Keep the terminal open.

   SN-002,default,temperature,25.7

3. Go to Devices & assets ⇾ Devices, select your device, and open the Attributes tab.

4. Select Shared attributes and click +.

5. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add. ThingsBoard sends the downlink.

To test from a single command, keep the connection open for 60 seconds with -w60 and add the attribute during that time:

• Text
• JSON
• Binary

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

• Terminal — the open connection prints the downlink:

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

• Converter events — open the downlink converter’s Events tab. In shows the Rule Engine message, and Out shows the payload sent to the device.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — install and run the TCP integration service.
• UDP Integration — the connectionless counterpart for datagram devices.
• TBEL — built-in functions and syntax for converter scripts.
• Rule Engine — how messages are processed after decoding.