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
An active Ubidots account
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)|endMultiple 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)
**Important note**: Both UDP and TCP support up to 5 connection requests per second under the same IP address. If exceeded, additional connection requests might be disregarded.
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 device 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}|endWhere:
{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.