TCP Integration

TCP Integration streams data from devices that use a TCP transport protocol to ThingsBoard Edge, converting payloads into telemetry and attributes. It also supports downlink — sending messages back to devices over the same TCP connection.

Prerequisites

In this tutorial we will use:

A ThingsBoard PE Edge instance.
The TCP Integration running as a remote service on port 10560.
The echo command and netcat (nc) utility to simulate a device sending data.

The example device SN-002 publishes temperature and humidity readings to TCP Integration on port 10560. Depending on your device capabilities, you can use one of three payload formats:

SN-002,default,temperature,25.7\r\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

Byte layout:

Bytes	Hex	Value	Description
0–3	`\x30\x30\x30\x30`	—	Dummy prefix (skipped)
4	`\x11`	17	Payload length in bytes
5–10	`\x53\x4e\x2d\x30\x30\x32`	`SN-002`	Device name
11–17	`\x64\x65\x66\x61\x75\x6c\x74`	`default`	Device type
18–21	`\x32\x35\x2e\x37`	`25.7`	Temperature
22–24	`\x00\x00\x00`	—	Dummy suffix (ignored)

Create converter templates

Converter and integration templates are created on the Cloud (ThingsBoard PE server). Log in as Tenant administrator.

Uplink converter

The uplink converter decodes the incoming TCP payload into ThingsBoard telemetry and attributes.

In the Cloud, go to Edge management > Converter templates and click +, then Create new converter. Set type to Uplink and enable Debug mode.

Paste the decoder script for your payload type into the function Decoder field, then click Add.

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

var result = {
    deviceName: payloadArray[0],
    deviceType: payloadArray[1],
    telemetry: telemetryPayload,
    attributes: {}
};

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

return result;

/** Decoder **/

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

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

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

function decodeToJson(payload) {
   var str = decodeToString(payload);
   return JSON.parse(str);
}

return result;

/** Decoder **/

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

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

var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {},
   telemetry: {
       temperature: parseFloat(payloadStr.substring(13, 17))
   }
};

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

return result;

To edit the converter later, open it from the Converter templates page, click the pencil icon, update the script, and click the checkmark to save.

Downlink converter

The downlink converter encodes outbound messages (e.g. attribute updates) into the format sent back to the device.

On the Converter templates page, click +, then Create new converter. Set type to Downlink and enable Debug mode.

Paste the following script into the function Encoder field, then click Add:

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload
// msgType - e.g. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST'
// metadata - key/value pairs with message metadata
// integrationMetadata - key/value pairs defined in the Integration

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

Go to Edge management > Integration templates and click +. Select TCP as the type, name it, and attach the uplink and downlink converters.

In the Connection block, set the Handler Configuration for your payload type:

Handler type: Text
Max Frame Length: 128
Strip Delimiter: enabled (drops the newline delimiter from payload)
Message Separator: System Line Separator

Handler type: JSON

Handler type: Binary
Max Frame Length: 128
Length Field Offset: 4 (the length byte is at position 4: \x30\x30\x30\x30\x11\x53...)
Length Field Length: 1 (one byte encodes the length)
Length Adjustment: 0
Number of first bytes to strip: 5 (skip the 4 dummy bytes + 1 length byte)

Other advanced socket settings (with defaults):

Setting	Description
Max pending connects	Maximum queue length for incoming connection requests. Connections are denied when the queue is full.
Inbound buffer size	Socket receive buffer size in kilobytes.
Outbound buffer size	Socket send buffer size in kilobytes.
Keep-alive messages	Sends periodic keep-alive probes to verify the connection remains active.
Disable Nagle’s algorithm	Sends data immediately without buffering.

Click Add to save the integration template.

Modify Edge Root Rule Chain for downlinks

To send downlink messages from ThingsBoard Edge to devices, add an integration downlink node to the Edge Root Rule Chain.

Assign integration to Edge

Install and run the remote TCP Integration

Use the Integration key and Integration secret from the integration page to configure the remote service.

Docker (Linux / Mac)

Pull the image:

docker pull thingsboard/tb-pe-tcp-udp-integration:4.3.1.1PE

Create a log volume:

mkdir -p ~/.tb-pe-tcp-udp-integration-logs && sudo chown -R 799:799 ~/.tb-pe-tcp-udp-integration-logs

Run the integration (replace placeholders with your values):

docker run -it -p 10560:10560 \
-v ~/.tb-pe-tcp-udp-integration-logs:/var/log/tb-tcp-udp-integration \
-e "RPC_HOST=mytbedge" \
-e "RPC_PORT=9090" \
-e "INTEGRATION_ROUTING_KEY=YOUR_ROUTING_KEY" \
-e "INTEGRATION_SECRET=YOUR_SECRET" \
--name my-tb-pe-tcp-udp-integration \
--network NETWORK_NAME \
--restart always \
thingsboard/tb-pe-tcp-udp-integration:4.3.1.1PE

Parameter	Description
`mytbedge`	Hostname of the ThingsBoard Edge service
`9090`	Integration RPC port (`INTEGRATIONS_RPC_PORT` in tb-edge.yml)
`-p 10560:10560`	Maps local port 10560 to the container port
`YOUR_ROUTING_KEY`	Integration routing key from the integration page
`YOUR_SECRET`	Integration secret from the integration page
`NETWORK_NAME`	Docker network where `mytbedge` runs. Check with `docker network ls`

To detach from the terminal without stopping the container, press Ctrl+p then Ctrl+q.

Useful container commands:

docker attach my-tb-pe-tcp-udp-integration  # reattach to logs
docker stop my-tb-pe-tcp-udp-integration
docker start my-tb-pe-tcp-udp-integration

Send uplink message

Once the TCP Integration is running, the TCP server starts listening on port 10560.

Send a test uplink using echo and nc. Choose the command for your payload type:

Single message:

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

Multiple messages in one connection (split by newline):

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

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

echo -e -n '\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' | nc -q1 -w1 127.0.0.1 10560

On the Edge, go to Integration center > Integrations, open the TCP integration, and select the Events tab. A message with status OK should appear.
Go to Entities > Devices to see the newly created device and its latest telemetry.
To inspect how the Uplink Converter processed the message, go to Integration center > Data converters, open the uplink converter, and select the Events tab.

Send downlink message

On the Edge, go to Entities > Devices, select device SN-002, and open the Attributes tab. Under Shared attributes, click + and add a new attribute — for example, key firmware, value v1.0. Save.
Verify the downlink was sent by opening the integration’s Events tab.

To receive the downlink response, send another uplink using a persistent nc connection (without -q0):

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

Multiple messages:

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

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

echo -e -n '\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' | nc -w60 127.0.0.1 10560

The terminal will show the response returned by ThingsBoard Edge.