Este artículo se basa en la documentación oficial de UbiFunction, que se puede encontrar en nuestro Centro de Desarrollo. |
Requisitos
Cuenta Ubidots: de prueba o con licencia
Al menos una UbiFunction ya creada (NOTA: si aún no tienes una, sigue este artículo primero)
1. Introducción
MQTT + UbiFunctions te permite publicar datos a través de una UbiFunction creada en tu cuenta y hacer posible integrar dispositivos que transmiten sobre este protocolo pero envían cargas útiles JSON cuyo formato no es compatible con nuestro broker MQTT nativo o API de Ingestión de Datos HTTP, o simplemente si se requiere procesamiento de datos adicional antes de enviarlos a Ubidots.
Como UbiFunctions actúa como un middleware aquí, solo se acepta el método MQTT Publish. En consecuencia, todos los mensajes de suscripción serán rechazados.
A continuación se muestran los ajustes de MQTT necesarios para invocar una UbiFunction sobre el protocolo MQTT:
Configuraciones de MQTT | Valor |
Host |
También se encuentra en algunos clientes MQTT como:
|
Port | 1883 para MQTT simple. |
Topic |
|
Username | Tu nombre de usuario de la cuenta |
Password | Token válido de tu cuenta de Ubidots. |
ClientID | Cualquier cadena aleatoria. Preferiblemente más larga de 15 caracteres |
Protocol | tcp
Nota: Algunos clientes MQTT ofrecen la posibilidad de conectarse usando websockets (mostrado como "ws://" o "wss://"), esto no es compatible. |
2. Estructura del tema
Para activar una UbiFunction a través de MQTT, el tema de la publicación debe seguir la estructura:
/prv/<username>/<function-label>, donde,
<username>: Tu nombre de usuario de la cuenta de Ubidots.<function-label>: Nombre de la UbiFunction pero todo en minúsculas y espacios reemplazados por guiones.
El tema base corresponde a la ruta de la URL del Endpoint HTTPS de la UbiFunction, como se ve en la imagen a continuación:
Avanzado: Los temas admiten niveles adicionales, separados por una barra diagonal ("/"), más allá de los utilizados para identificar la UbiFunction dentro de la cuenta. La estructura es:
/prv/<username>/<function-label>/<level-1>/···/<level-N>, donde
<level-N>es cualquier cadena codificada en UTF-8 adicional que quieras agregar al tema
Los temas tienen las siguientes limitaciones:
Longitud: 1500 caracteres
Niveles: 10
3. Argumentos de UbiFunction
Al activar una UbiFunction a través del protocolo MQTT, recibirás un objeto JSON en la variable args de la función main. El JSON tendrá esta estructura:
{
"topic": "<topic>",
"payload": "<payload>",
"from_client_id": "<client_id>",
}
Donde las claves corresponden de la siguiente manera:
Clave | Tipo | Descripción del valor |
topic | Cadena | El tema de publicación multinivel |
payload | Cadena | La carga útil enviada por el dispositivo en el mensaje de publicación. |
from_client_id | Cadena | El ID de cliente utilizado en la conexión MQTT. |
4. Certificados TLS
Ubidots admite SSL V1.1, TLS V1.2 y V1.3. Puedes descargar nuestros certificados raíz en diferentes formatos:
Archivo PEM: Cadena de certificados con dos certificados raíz de nuestras autoridades certificadoras (CAs).
Archivo DER: Igual que el archivo PEM, con una codificación alternativa.
Archivo CRT: Igual que el archivo PEM, con una extensión diferente. A menudo se denomina .crt, .cert o .cer.
5. Ejemplos
Puerto 1883:
mosquitto_pub \
-p 1883 \
-h functions.ubidots.com \
-t "/prv/<username>/<function-name>" \
-m '{"token": "TOKEN", "device": "device-label", "variable-label": value}' \
-u "<username>" \
-P "TOKEN" \
-q 1 -d
Puerto 8883:
mosquitto_pub \
-p 8883 \
-h functions.ubidots.com \
-t "/prv/<username>/<function-name>" \
-m '{"token": "TOKEN", "device": "device-label", "variable-label": value}' \
-u "<username>" \
-P "TOKEN" \
-q 1 -d \
--cafile /Users/user/Documents/Ubidots/roots.pem