UDP Integration

UDP Integration connects ThingsBoard to devices that communicate over raw User Datagram Protocol (UDP) sockets. It binds to a configured port, receives discrete UDP datagrams from devices, decodes each message through the Uplink Converter, and maps the result to ThingsBoard telemetry and attributes. It also supports downlink — sending response datagrams back to the source device address.

When to use UDP Integration:

• Devices use a custom binary or text protocol over a raw UDP socket.
• Firmware transmits fire-and-forget datagrams to a fixed host and port.
• Low-overhead, connectionless transport is preferred over TCP (e.g., battery-powered sensors, high-frequency telemetry streams).
• You need to bridge an existing UDP-based device protocol with ThingsBoard without re-flashing firmware.

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 your UDP devices use.
• Port 11560 (or whichever port you configure) must be open for incoming UDP traffic on the machine running the UDP 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 UDP datagrams.

In this tutorial, device SN-003 sends temperature and humidity readings to the UDP Integration server on port 11560.

The integration accepts four payload formats. Select the one that matches your device:

SN-003,default,temperature,25.7,humidity,69

{
  "deviceName": "SN-003",
  "deviceType": "default",
  "temperature": 25.7,
  "humidity": 69
}

\x53\x4e\x2d\x30\x30\x33\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39

534e2d30303364656661756c7432352e373639

The decoder function receives the raw UDP datagram body as a payload byte array. 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 UDP and select UDP from the list.
5. Name — enter a converter name, for example UDP 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, "").replace(/\\n/g, "").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 **/

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)),
       humidity: parseFloat(payloadStr.substring(17, 19))
   }
};

/** 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)),
       humidity: parseFloat(payloadStr.substring(17, 19))
   }
};

/** 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 JSON
var data = decodeToJson(payload).reports[0].value;

// Result object with device telemetry data
var result = {
    deviceName: hexToString(data.substring(0, 12)),
    deviceType: hexToString(data.substring(12, 26)),
    telemetry: {
        temperature: parseFloat(hexToString(data.substring(26, 34))),
        humidity: parseFloat(hexToString(data.substring(34, 38)))
    }
};

/** Helper functions **/

// Hexadecimal string to string
function hexToString(hex) {
    return bytesToString(hexToBytes(hex));
}

return result;

/** Decoder **/

// decode payload to JSON
var data = decodeToJson(payload).reports[0].value;

// Result object with device telemetry data
var result = {
    deviceName: hexToString(data.substring(0, 12)),
    deviceType: hexToString(data.substring(12, 26)),
    telemetry: {
        temperature: parseFloat(hexToString(data.substring(26, 34))),
        humidity: parseFloat(hexToString(data.substring(34, 38)))
    }
};

/** Helper functions **/

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

// Hexadecimal string to string
function hexToString(hex) {
    var str = '';
    for (var i = 0; i < hex.length; i += 2) {
        var notNullValue = parseInt(hex.substr(i, 2), 16);
        if (notNullValue) {
            str += String.fromCharCode(notNullValue);
        }
    }
    return str;
}

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

return result;

7. Click Test payload decoder to verify your script. Paste a sample payload matching your format, then click Test and confirm the result contains the expected deviceName, deviceType, and telemetry fields.
8. Click Add to save the converter.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Select UDP as the integration type.
   • Enter a name — for example, UDP 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 UDP 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 11560. This port must be open on the machine running the UDP Integration process.
   • The Execute remotely option is always enabled for UDP. 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 to save the integration.

Set Integration type to UDP, enter a name, and click Next Select existing, choose UDP 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

Port

UDP port the integration listens on for incoming datagrams. Must be unique per integration on a given host. Default: 11560.

Size of the buffer for inbound socket (in KB)

Size of the receive buffer for the inbound UDP socket in kilobytes. Increase this value if datagrams are being dropped under high load. Default: 64.

Enable broadcast

When enabled, the integration socket accepts broadcast UDP packets (destination 255.255.255.255 or a subnet broadcast address). Disable for unicast-only deployments. Enabled by default.

Execute remotely

Execute remotely is always enabled for UDP Integration. Copy the automatically generated Integration key and Integration secret values — credentials required to launch the UDP Integration as a standalone remote process. See Remote Integration for full setup instructions.

Downlink cache

Advanced settings

Defines how the integration interprets the raw datagram bytes before passing them to the converter. Select the type that matches your device protocol:

Refer to the remote integration guide to install and start the UDP Integration service.

Use the Integration key and Integration secret from the integration’s Connection settings when configuring the service.

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 UDP Integration process is running, the UDP socket is bound and ready to receive datagrams. Use netcat in UDP mode (-u) to simulate a device sending data.

Select your payload type:

echo -e 'SN-003,default,temperature,25.7,humidity,69' | nc -u -w5 localhost 11560

echo -e -n '{"deviceName": "SN-003", "deviceType": "default", "temperature": 25.7, "humidity": 69}' | nc -u -w5 localhost 11560

echo -e -n '\x53\x4e\x2d\x30\x30\x33\x64\x65\x66\x61\x75\x6c\x74\x32\x35\x2e\x37\x36\x39' | nc -u -w5 localhost 11560

echo -e -n '534e2d30303364656661756c7432352e373639' | xxd -r -p | nc -u -w5 localhost 11560

Go to Integrations center ⇾ Integrations, open UDP 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 UDP Uplink Converter, and open its Events tab:

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

Go to Entities ⇾ Devices. Device SN-003 is auto-created on the first uplink. Open it and confirm the Latest Telemetry tab shows temperature = 25.7 and humidity = 69.

Downlink allows ThingsBoard to send messages back to devices over UDP — for example, in response to an RPC call or a shared attribute update. The response datagram is sent to the source IP address and port of the most recent uplink datagram received from that device.

The downlink converter transforms a Rule Engine message into the bytes sent back to the device.

1. Go to Integrations center ⇾ Integrations and open the UDP 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:

// Result object with encoded downlink payload
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;

// Result object with encoded downlink payload
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;

Open the UDP integration details 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 configured — 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 UDP integration) and select your UDP 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 UDP 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.

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

1. Go to Entities ⇾ Devices, open SN-003, 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.

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

echo -e 'SN-003,default,temperature,25.7,humidity,69' | nc -w10 -u localhost 11560

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:

{"powerState":"on"}

• 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 — run the 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