Plugins: TCP Gateway

Receive and parse custom payloads using TCP.

Sergio M avatar
Written by Sergio M
Updated over a week ago

Our new TCP Gateway plugin is designed to serve as an intermediary that routes TCP packets into an HTTPs webhook, so they can be decoded using Python in the plugin's decoder. It facilitates communication between systems that may use different payloads, enabling compatibility and interoperability. The TCP Gateway plugin can also respond custom packets to TCP clients, which can be specified in the plugins's Python code.

This plugin costs $29 per month.


  • An active Ubidots paid license in the Professional plan or above.

Table of contents

1. Setting the plugin up

Go to “Devices” → “Plugins”. Click on the “+” button in the upper right corner and click on the TCP Gateway option.

In order to set up the plugin you need to provide three inputs:

  1. Port: The plugin “listens” to the port you specify here for incoming TCP packets. You can determine which port best aligns with your application's requirements.

  2. Confirmation Character: The server will only send the TCP data to the HTTPs webhook when this confirmation character is received. This character acts as a trigger for transmitting the data. The default character is "\n".

  3. Token: Select an Ubidots token for this plugin. If you’re sending data from hundreds or thousands of devices, make sure your token's rate limit is enough to withstand the traffic.

    After configuring the plugin, your private TCP gateway will take about 3 minutes to be fully provisioned.

  4. Once your gateway is provisioned, you’ll be able to locate the TCP Server IP in the plugin’s description:

  5. Using this IP, and the specified port, ensures that the packets are routed to this plugin’s decoder.

2. Python decoder

The TCP gateway will automatically reply back whatever you return in the decoder function.

By default, the plugin has a decoder that will either respond with:

  • "ok" for a successful execution, indicating an HTTP response with a status code of 200 or 201.

  • Or "error" when the plugin returns an error, indicating an HTTP response with a status code greater than 400.

You can modify this decoder so it replies with different response messages.

TCP sample decoder

import requests

def decoder(args):

# Use this code snippet to decode incoming TCP data.
# As an example, let's assume the TCP device sends this payload (escape character is not included):
# <device_label>,<temp>,<humidity>

# Get token from internal "_parameters" key in args, which contains system-specific args
token = args.get('_parameters', {}).get('_auth_token', None)

# Get payload from args. TCP gateway will send the received payload inside the "data" key
# NOTE: The TCP gateway will automatically detect if the received payload is plan text, or raw bytes.
# If it detects bytes, then the 'data' key will be in base64, so you'd have to decode it.

tcp_payload = args.get('data', '')

# Split values and prepare payload
tcp_payload_array = tcp_payload.split(',')
msg = "Could not decode payload"
return msg

payload = {
"temperature": tcp_payload_array[1],
"humidity": tcp_payload_array[2]

# Send data to Ubidots
res = send_data(tcp_payload_array[0], payload, token)

# Use response to decide what is sent back to the TCP client.
# The TCP gateway will automatically reply back whatever you return in this function.
# For example, send "ok" or "error" depending on the status code received when sending data to Ubidots:

status_code = res.status_code

if 200 <= status_code < 300:
msg = "ok"
elif 400 <= status_code < 500:
msg = "error"

return msg

3. Troubleshooting

You can test the plugin using Netcat, like in this example:

nc 5555

You would have to replace the first number,, with your TCP server IP and the second one, 5555, with the port you chose.

Others also found helpful:

Did this answer your question?