Mientras que nuestra REST API proporciona una buena manera de acceder a todos tus recursos (dispositivos, variables y valores) programáticamente, a veces solo necesitas enviar datos desde tu dispositivo utilizando un protocolo simple y más ligero como TCP o UDP. Por eso hemos diseñado un formato de carga útil simple que puedes usar para enviar o recuperar datos de tus dispositivos a Ubidots utilizando estos protocolos.
Requisitos
1. Fundamentos de TCP/UDP
El Protocolo de Control de Transmisión, TCP, es uno de los protocolos de transporte de datos más populares, soportado por defecto en la mayoría de los dispositivos de hardware habilitados para internet. Su principal ventaja radica en el tamaño de los paquetes, que suele ser menor que los paquetes enviados utilizando HTTP (de hecho, HTTP utiliza TCP como capa de transporte). TCP es "orientado a conexión", lo que significa que implementa un método de confirmación para garantizar que los datos han sido recibidos.
El Protocolo de Datagramas de Usuario, UDP, también es un protocolo muy popular, a diferencia de TCP, es "sin conexión". Esto significa que no implementa ningún método de confirmación para garantizar que los datos han sido recibidos. Esto puede ser una ventaja en aplicaciones donde la simplicidad y la velocidad son más importantes que la fiabilidad. Los protocolos de Ubidots TCP y UDP son similares en el sentido de que comparten la estructura de endpoint y port.
URL - Endpoint
industrial.api.ubidots.com
Puerto: NoTLS/TLS
9012/9812
2. Enviar datos a través de TCP o UDP
Dispositivo único
{USER_AGENT}|POST|{TOKEN}|{DEVICE_LABEL}(:{DEVICE_NAME})@{GLOBAL_TIMESTAMP}=>[VAR_LABEL:VALUE([$CONTEXT_KEY=CONTEXT_VAL]...)](@VARIABLE_TIMESTAMP)|endMúltiples dispositivos
{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}: Obligatorio. Un identificador de tu elección que permite identificar el tipo de aplicación, sistema operativo, proveedor de software o versión de software del agente de usuario de software que realiza la solicitud. Es una buena práctica incluir una versión en caso de que estés envolviendo estas solicitudes dentro de una biblioteca. Ejemplos: ESP8266/1.0, Particle/1.2.{TOKEN}: Obligatorio. Tu Token de cuenta de Ubidots{DEVICE_LABEL}: Obligatorio. La etiqueta del dispositivo para publicar valores. Si no existe, Ubidots la creará. Ten en cuenta que no se permiten espacios en blanco ni letras mayúsculas. Ejemplos: estación-meteorológica, sala-de-estar{DEVICE_NAME}: Opcional. El nombre del dispositivo para publicar valores. Si no se establece ninguno, el nombre del dispositivo será el mismo que la etiqueta del dispositivo. Este parámetro es útil cuando tienes como etiqueta del dispositivo tu MAC y deseas mostrar a los usuarios finales un nombre amigable. Ten en cuenta que no se permiten espacios en blanco. Ejemplos: estación-meteorológica, sala-de-estar-piso-1, granja-1{GLOBAL_TIMESTAMP}: Opcional. Marca de tiempo Unix. Si se establece, cualquier valor de variable sin marca de tiempo utilizará este tiempo para almacenar valores. Debe estar en milisegundos. Si no se establece, Ubidots creará automáticamente el valor con la marca de tiempo actual en UTC. Ejemplo: 1594765274000 (14 de julio de 2020 10:21:14 PM){VARIABLE_LABEL}: Obligatorio. La etiqueta de la variable que contiene el punto. Si no existe, Ubidots creará una. Puedes enviar múltiples variables separándolas por comas. Ejemplos: temperatura, velocidad-del-viento, humedad.{VALUE}: Obligatorio. Valor del punto. Puedes usar un punto para establecer números de punto flotante. Ejemplos: 3.0015, 2{CONTEXT_KEY}: Opcional. Si se establece, debes especificar un valor de contexto. Puedes agregar tantas claves de contexto como desees separándolas con un carácter '$'. Ejemplos: lat, lng, nombre, número-de-orden, ciudad.{CONTEXT_VALUE}: Opcional. El valor de la clave de contexto. Ejemplos (basados en los ejemplos de claves de contexto anteriores): -6.2, 75.4, 2348, "Copenhague".{VARIABLE_TIMESTAMP}: Opcional. Marca de tiempo Unix. Si se establece, la variable utilizará esta marca de tiempo para almacenar puntos. Este parámetro tiene precedencia sobre la marca de tiempo global. Debe estar en milisegundos. Si no, Ubidots creará automáticamente el valor con la marca de tiempo actual en UTC. Ejemplos: 1594765274000 (14 de julio de 2020 10:21:14 PM)
**Nota importante**: Tanto UDP como TCP soportan hasta 5 solicitudes de conexión por segundo bajo la misma dirección IP. Si se excede, las solicitudes de conexión adicionales pueden ser ignoradas.
Ejemplos
Aquí algunos ejemplos para crear dispositivos con diferentes tipos de datos:
Crear múltiples dispositivos con una variable
Agente de usuario: Particle/1.0
Dispositivo 1: estación-meteorológica1
Variable: temperatura, Valor: 2
Dispositivo 2: estación-meteorológica1
Variable: temperatura, Valor:22
Solicitud:particle/1.0|POST|TOKEN|estación-meteorológica1=>temperatura:2,humedad:23.2;estación-meteorológica2=>temperatura:22,humedad:30|end
Actualizar un solo dispositivo con dos variables, donde una de ellas contiene datos GPS
Agente de usuario: mbed/1.2
Dispositivo: estación-meteorológica1
Variable: temperatura, Valor: 2
Contexto: latitud:6.2, longitud: -76.3
Solicitud:mbed/1.2|POST|TOKEN|dispositivo=>estación-meteorológica:14,posicion:1$lat=6.2$lng=-76.3|end
Actualizar dos variables, cada una con una marca de tiempo definida por el usuario
Agente de usuario: microchip/1.0
Dispositivo : estación-meteorológica
Variable: temperatura, Valor:2
Marca de tiempo: 1492641596000
Solicitud:microchip/1.0|POST|TOKEN|estación-meteorológica=>temperatura:14@1492641596000,humedad:12@1492631497000|end
Crear un dispositivo con y variable usando el Nombre del dispositivo.
Agente de usuario: Particle/1.0
Nombre del dispositivo: Estación Meteorológica
Variable: temperatura, Valor: 2
Solicitud:particle/1.0|POST|TOKEN|estación-meteorológica:Estación Meteorológica@1492641596000=>temperatura:27|end
Pruebas
Una forma rápida de probar esto es usando "netcat" desde un shell de Unix:
UDP
nc -u industrial.api.ubidots.com 9012Microchip/1.0|POST|TOKEN|dispositivo-udp=>temperatura:20$lat=-6.2$lng=-73.991180,humedad:10|end
Ten en cuenta que la variable Temperatura tiene las propiedades lat y lng, que puedes usar más tarde para mostrar la ubicación del dispositivo en un widget de mapa:
TCP
nc industrial.api.ubidots.com 9012Microchip/1.0|POST|TOKEN|dispositivo-tcp=>temperatura:2@1594844773,humedad:23.2;estación-meteorológica2=>temperatura:22,humedad:30|end
3. Recibir el último valor a través de TCP o UDP
Carga útil
{USER_AGENT}|LV|{TOKEN}|{DEVICE_LABEL}:{VARIABLE_LABEL}|endDonde:
{USER_AGENT}: Obligatorio. Un identificador de tu elección que permite identificar el tipo de aplicación, sistema operativo, proveedor de software o versión de software del agente de usuario de software que realiza la solicitud. Es una buena práctica incluir una versión en caso de que estés envolviendo estas solicitudes dentro de una biblioteca. Ejemplos: ESP8266/1.0, Particle/1.2{TOKEN}: Obligatorio. Tu Token de cuenta de Ubidots.{DEVICE_LABEL}: Obligatorio. La etiqueta del dispositivo para publicar valores. Si no existe, Ubidots la creará. Ten en cuenta que no se permiten espacios en blanco ni letras mayúsculas. Ejemplos: estación-meteorológica, sala-de-estar.{VARIABLE_LABEL}: Obligatorio. La etiqueta de la variable que contiene el punto. Si no existe, Ubidots creará una. Puedes enviar múltiples variables separándolas por comas. Ejemplos: temperatura, velocidad-del-viento, humedad.
Ejemplos
Aquí hay un ejemplo para obtener el último valor de una variable con la etiqueta del dispositivo "estación-meteorológica" y la etiqueta de variable "temperatura"
Microchip/1.0|LV|TOKEN|estación-meteorológica:temperatura|end
Pruebas
Una forma rápida de probar esto es usando "netcat" desde un shell de Unix:
UDP
nc -u industrial.api.ubidots.com 9012 Microchip/1.0|LV|TOKEN|estación-meteorológica:temperatura|end
TCP
nc industrial.api.ubidots.com 9012 Microchip/1.0|LV|TOKEN|estación-meteorológica:temperatura|end
NOTA: No dudes en contactar a ventas de Ubidots para solicitar un protocolo personalizado (es decir, TCP/UDP/SMS/CoAP) con capacidad asignada privadamente bajo tu propia URL.