While our REST API provides a good way to access all of your resources (devices, variables, and values) programmatically, sometimes you just need to send data from your device using a simple and lighter protocol like TCP or UDP. That's why we have designed a simple payload format that you can use to send or retrieve data to/from your devices to Ubidots using these protocols.

Requirements

Table of Contents

  1. TCP/UDP Basics
  2. Send data over TCP/UDP
  3. Retrieve the last value of a variable over TCP or UDP

1. TCP/UDP Basics

The Transmission Control Protocol, TCP, is one of the most popular data transport protocols, supported by default in most internet-enabled hardware devices. Its main advantage comes in the packet size, usually lower than packets sent using HTTP (in fact, HTTP uses TCP as the transport layer). TCP is "connection-oriented", meaning that implements a confirmation method to guarantee that data has been received.

The User Datagram Protocol, UDP, is also a very popular protocol, unlike TCP, it is "connection-less". This means it does not implement any confirmation method to guarantee that data has been received. This can be an advantage in applications where simplicity and speed are more important than reliability. TCP and UDP Ubidots’ protocols are similar in the sense that they share the structure of endpoint and port.

URL - Endpoint

industrial.api.ubidots.com

Port: NoTLS/TLS

9012/9812

2. Send data over TCP or UDP:

Single device

{USER_AGENT}|POST|{TOKEN}|{DEVICE_LABEL}(:{DEVICE_NAME})@{GLOBAL_TIMESTAMP}=>[VAR_LABEL:VALUE([$CONTEXT_KEY=CONTEXT_VAL]...)](@VARIABLE_TIMESTAMP)|end

Multiple devices

{USER_AGENT}|POST|{TOKEN}|{DEVICE_LABEL_1}(:{DEVICE_NAME_1})(@{GLOBAL_TIMESTAMP})=>[VAR_LABEL:VALUE([$CONTEXT_KEY=CONTEXT_VAL]...)](@VARIABLE_TIMESTAMP)]; ... ;{DEVICE_LABEL_N}(:{DEVICE_NAME_N})(@{GLOBAL_TIMESTAMP})=>[VAR_LABEL:VALUE([$CONTEXT_KEY=CONTEXT_VAL]...)](@VARIABLE_TIMESTAMP)|end
  • {USER_AGENT}: Mandatory. An identifier of your choice that allows to identify the application type, operating system, software vendor or software version of the requesting software user agent. It's a good practice to include a version in case you're wrapping these requests within a library. Examples: ESP8266/1.0, Particle/1.2.
  • {TOKEN} : Mandatory. Your Ubidots account Token
  • {DEVICE_LABEL}: Mandatory. The device label to publish values. If it does not exist, Ubidots will create it. Please keep in mind that blank spaces or capital letter are not allowed. Examples: weather-station, living-room
  • {DEVICE_NAME}: Optional. The device name to publish values. If there isn’t set any, the device name will be the same as the device label. This parameter is useful when you have as device label your device MAC and you wish to show to final users a friendly name. Keep in mind that blank spaces are not allowed. Examples: weather-station, living-room-floor-1, farm-1
  • {GLOBAL_TIMESTAMP}: Optional. Unix timestamp. If set, any variable value without timestamp will use this time to store values. It must be in milliseconds. If it is not set, Ubidots will automatically create the value with the actual timestamp in UTC. Example: 1594765274000 (July 14, 2020 10:21:14 PM)
  • {VARIABLE_LABEL}: Mandatory.The variable label that contains the dot. If it does not exist, Ubidots will create one. You may send multiple variables splitting them by commas. Examples: temperature, wind-speed, humidity.
  • {VALUE}: Mandatory. Dot value. You can use a dot to set float numbers. Examples: 3.0015, 2
  • {CONTEXT_KEY}: Optional. If set, you must specify a context value. You can add as many context key as you wish splitting them with a '$' char. Examples: lat, lng, name, order-number, city.
  • {CONTEXT_VALUE}: Optional. The context key value. Examples (based on the examples of context keys above): -6.2, 75.4, 2348, "Copenhagen".
  • {VARIABLE_TIMESTAMP}: Optional.Unix timestamp. If any set, the variable will use this timestamp to store dots. This parameter has precedence among the global timestamp. It must be in milliseconds. If not, Ubidots automatically create the value with the actual timestamp in UTC. Examples: 1594765274000 (July 14, 2020 10:21:14 PM)

Examples

Here some examples to create device with different types of data:


Create multiple devices with one variable


User Agent: Particle/1.0
Device 1: weather-station1
Variable: temperature, Value: 2
Device 2: weather-station1
Variable: temperature, Value:22

Request:
particle/1.0|POST|TOKEN|weather-station1=>temperature:2,humidity:23.2;weather-station2=>temperature:22,humidity:30|end

Update a single device with two variables, where one of them contains GPS data


User Agent: mbed/1.2
Device: weather-station1
Variable: temperature, Value: 2
Context: latitude:6.2, longitude: -76.3

Request:
mbed/1.2|POST|TOKEN|device=>weather-station:14,position:1$lat=6.2$lng=-76.3|end

Update two variables, each with a user-defined timestamp


User Agent: microchip/1.0
Device : weather-station
Variable: temperature, Value:2
Timestamp: 1492641596000

Request:
microchip/1.0|POST|TOKEN|weather-station=>temperature:14@1492641596000,humidity:12@1492631497000|end

Create a devices with and variable using the device Name.

User Agent: Particle/1.0
Device Name: Weather Station
Variable: temperature, Value: 2

Request:
particle/1.0|POST|TOKEN|weather-station:Weather Station@1492641596000=>temperature:27|end

Testing

A quick way to test this is using "netcat" from a Unix shell:

UDP

nc -u industrial.api.ubidots.com 9012
Microchip/1.0|POST|TOKEN|device-udp=>temperature:20$lat=-6.2$lng=-73.991180,humidity:10|end

Please note that the Temperature variable has the lat and lng properties, which you can later use to display the device location in a map widget:

TCP

nc industrial.api.ubidots.com 9012
Microchip/1.0|POST|TOKEN|device-tcp=>temperature:2@1594844773,humidity:23.2;weather-station2=>temperature:22,humidity:30|end

3. Receive the last value over TCP or UDP:

Payload

{USER_AGENT}|LV|{TOKEN}|{DEVICE_LABEL}:{VARIABLE_LABEL}|end

Where:

  • {USER_AGENT}: Mandatory. An identifier of your choice that allows to identify the application type, operating system, software vendor or software version of the requesting software user agent. It's a good practice to include a version in case you're wrapping these requests within a library. Examples: ESP8266/1.0, Particle/1.2
  • {TOKEN} : Mandatory. Your Ubidots account Token
  • {DEVICE_LABEL}: Mandatory. The device label to publish values. If it does not exist, Ubidots will create it. Please keep in mind that blank spaces or capital letter are not allowed. Examples: weather-station, living-room
  • {VARIABLE_LABEL}: Mandatory.The variable label that contains the dot. If it does not exist, Ubidots will create one. You may send multiple variables splitting them by commas. Examples: temperature, wind-speed, humidity.

Examples

Here is an example to get the last value from a variable with the device label "weather-station" and variable label "temperature"

Microchip/1.0|LV|TOKEN|weather-station:temperature|end

Testing

A quick way to test this is using "netcat" from a Unix shell:

UDP

nc -u industrial.api.ubidots.com 9012 
Microchip/1.0|LV|TOKEN|weather-station:temperature|end

TCP

nc industrial.api.ubidots.com 9012 
Microchip/1.0|LV|TOKEN|weather-station:temperature|end

NOTE: Feel free to contact Ubidots sales to request a custom protocol (i.e. TCP/UDP/SMS/CoAP) with privately allocated capacity under your own URL.


Other users also found useful...

Did this answer your question?