1. ¿Qué es MQTT?

MQTT es especialmente útil para enviar datos a tus dispositivos. Imagina una aplicación de IoT que necesita enviar mensajes de enlace descendente a miles de dispositivos. En el caso de HTTP, cada dispositivo tendría que hacer continuamente solicitudes GET al servidor para ver si hay nuevos datos disponibles para ellos. Eso significaría miles de solicitudes innecesarias por segundo, y no es completamente una interacción en tiempo real, ya que depende de la frecuencia de sondeo.

Con MQTT, los dispositivos pueden suscribirse o “escuchar” a la nube y solo recibir notificaciones cuando hay nuevos datos para ellos. De esta manera, la conexión entre el dispositivo y la nube se mantiene abierta, pero los datos solo viajan cuando es necesario, ahorrando batería, ancho de banda de la red y mejorando la experiencia en tiempo real.

Para interactuar con un broker MQTT, tu dispositivo, pasarela o aplicación debe admitir este protocolo. Lee las instrucciones del fabricante para asegurarte de que sea compatible.

Una buena forma de aprender sobre MQTT y las cargas útiles compatibles es experimentar con clientes o bibliotecas existentes, como:

Paho: El proyecto Eclipse Paho proporciona clientes MQTT de código abierto para C/C++, Python, Java, Javascript, Go y C#.
MQTT.fx: Un cliente MQTT basado en JavaFX.
MQTT Lens: Una extensión de Google Chrome que se conecta a un broker MQTT y puede publicar y suscribirse a temas MQTT. Si estás utilizando esta herramienta para probar la API MQTT de Ubidots, entonces ingresa cualquier texto aleatorio en el campo de contraseña de la conexión, ya que parece que no permite contraseñas en blanco.
MQTT Inspector: Una aplicación general de prueba de MQTT para iOS (iPhone y iPad).

2. Características Generales

Estas son las características generales del broker MQTT de Ubidots. Para obtener más información, lee nuestra documentación técnica de MQTT.

Característica	Descripción	Soportado
Autenticación TLS	Comunicación encriptada usando claves PEM.	SÍ
Calidad de Servicio (QoS)	0, como máximo una vez: Este nivel no garantiza la entrega del mensaje, se etiquetaría como QoS de mejor esfuerzo del servidor. 1, al menos una vez: Este nivel garantiza que el mensaje se entregue al menos una vez al receptor. El receptor responde con un paquete pub-ack, si este paquete pub-ack no se recibe, el remitente envía nuevamente el mensaje. 2, exactamente una vez: Garantiza que el mensaje se reciba solo una vez por el receptor. Es el QoS de intercambio de paquetes más lento, ya que requiere dos flujos de solicitud/respuesta.	SÍ, solo hasta QoS=1. Si necesitas QoS = 2, por favor ponte en contacto con nosotros para implementar un broker MQTT dedicado para ti.
Última Voluntad (LWT)	Mensajes que son enviados por el broker una vez que la conexión con el cliente ha sido interrumpida (cuando el cliente se ha desconectado).	NO* *Si necesitas LWT, por favor ponte en contacto con nosotros para implementar un broker MQTT dedicado para ti.
Sesiones persistentes	Las sesiones persistentes son una forma de hacer que el broker guarde información relevante sobre el cliente en caso de que la conexión se pierda. Una vez que la conexión se restablezca, el broker tendrá la información de la conexión de inmediato.	NO* (Configurar el indicador cleanSession en false no tendrá efecto). Una vez que la conexión se haya perdido, el cliente debe establecer nuevamente los parámetros de conexión. *Si necesitas sesiones persistentes, por favor ponte en contacto con nosotros para implementar un broker MQTT dedicado para ti.
Clientes inactivos	Conexión de clientes MQTT que no reciben ningún paquete.	La conexión de clientes inactivos suscritos al broker se cerrará después de 90 minutos. *Si necesitas sesiones más largas, por favor ponte en contacto con nosotros para implementar un broker MQTT dedicado para ti.
Dirección IP fija	La dirección IP del broker, que es útil cuando el firmware del cliente no tiene capacidades de resolución DNS.	Consulta la dirección IP actual del broker aquí. Recomendamos encarecidamente implementar rutinas DNS en lugar de IPs fijas, ya que estas pueden cambiar en el futuro. Si necesitas una IP fija, por favor ponte en contacto con nosotros para implementar un broker MQTT dedicado para ti.

3. Autenticación

Obtén más información sobre la autenticación MQTT en nuestra documentación oficial de la API.

Nuestro broker MQTT está disponible en la siguiente URL:

industrial.api.ubidots.com

Puerto: 1883

Para interactuar con él, necesitarás un token. La forma más fácil de obtener el tuyo es haciendo clic en "Credenciales de API", que se encuentra en el botón desplegable de la cuenta en tu cuenta de Ubidots.

Para conectarse a nuestro broker MQTT, usa tu token de Ubidots como el nombre de usuario de MQTT y deja el campo de contraseña en blanco.

Nombre de usuario → Token de Ubidots.
Contraseña → Dejar en blanco.

Si la conexión es exitosa, deberías poder publicar y suscribirte a temas MQTT, de lo contrario, el broker devolverá un error y desconectará al cliente.

4. Publicar

Obtén más información sobre la publicación MQTT en nuestra documentación oficial de la API.

Para enviar valores a varias variables, debes enviar un mensaje PUBLISH con el tema:

/v1.6/devices/{LABEL_DEVICE}

A esta URL:

mqtt://industrial.api.ubidots.com

La carga útil debe ser un diccionario JSON donde cada clave corresponda a la etiqueta única de cada variable, y cada valor puede ser cualquiera de los siguientes:

Un número flotante o entero. Por ejemplo:

{"temperature": 10, "humidity": 50}

Un objeto JSON que contenga el "valor", "timestamp" y "contexto" del punto de datos. Por ejemplo:

{"temperature": {"value":10, "timestamp": 1464661369000, "context":{"lat":-6.2, "lng":75.4, "my-key":"hello there"}}, "humidity": 50}

Una lista de objetos JSON, cada uno conteniendo la clave "valor", y opcionalmente el "timestamp" y "contexto" del punto de datos. Por ejemplo:

{"temperature":[{"value": 10, "timestamp":1464661369000}, {"value": 12, "timestamp":1464661369999}], "humidity": 50}

4.1. Publicar valores a una variable

Una vez que el cliente MQTT esté autenticado correctamente, deberías poder publicar valores en el broker. Para enviar un valor al broker, debes enviar un mensaje PUBLISH con el tema:

/v1.6/devices/{LABEL_OF_DEVICE}/{LABEL_OF_VARIABLE}

A esta URL:

mqtt://industrial.api.ubidots.com

El cuerpo de la solicitud POST puede ser:

Un objeto JSON que contenga la clave "valor", y opcionalmente el "timestamp" y el "contexto" del punto de datos. Por ejemplo:

{"value":10}

{"value":10, "timestamp": 1464661369000, "context":{"lat":-6.2, "lng":75.4}}

Una lista de objetos JSON, cada uno conteniendo la clave "valor", y opcionalmente el "timestamp" y "contexto" del punto de datos:

[{"value": 10, "timestamp":1464661369000}, {"value": 12, "timestamp":1464661369999}]

5. Suscribirse

Obtén más información sobre suscripciones MQTT en nuestra documentación oficial de la API.

5.1. Suscribirse a una variable

Una vez que el cliente MQTT esté autenticado correctamente, deberías poder suscribirte a una variable para recibir notificaciones cuando reciba datos.

Para suscribirse a una variable, envía un mensaje SUBSCRIBE a esta URL:

mqtt://industrial.api.ubidots.com

Con el tema:

/v1.6/devices/{LABEL_DEVICE}/{LABEL_VARIABLE}/lv

Esto devolverá el último valor de la variable como un solo valor flotante. Esto facilita su análisis en microcontroladores.

NOTA: El tema de suscripción debe estar todo en minúsculas.

Alternativamente, puedes usar este tema:

/v1.6/devices/{LABEL_DEVICE}/{LABEL_VARIABLE}

Esto devolverá un documento JSON con la siguiente estructura:

{    "value": valor,    "timestamp": timestamp,    "context": contexto,    "id": id_valor}

NOTA: El tema de suscripción debe estar todo en minúsculas.

6. Ejemplos

6.1. Ejemplo de autenticación MQTT en Node.js

var mqtt = require("mqtt");var client  = mqtt.connect('mqtt://industrial.api.ubidots.com', {username:'c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5', password:""});

6.2. Node.js: Publicar datos a un dispositivo

var mqtt = require("mqtt");var client  = mqtt.connect('mqtt://industrial.api.ubidots.com', {username:'c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5', password:""});var variablesPublish = {"temperature": 10, "luminosity": {"value":10}, "wind_speed": [{"value": 11, "timestamp":10000}, {"value": 12, "timestamp":13000}]};var json = JSON.stringify(variablesPublish);client.publish("/v1.6/devices/label_ds", json, {'qos': 1, 'retain': false},    function (error, response) {        console.log(response);    });

6.3. Node.js: Publicar datos a una sola variable

var mqtt = require("mqtt");var client  = mqtt.connect('mqtt://industrial.api.ubidots.com', {username:'c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5', password:""});client.publish("/v1.6/devices/label_ds/label_var",'{"value": 10.3}', {'qos':1, 'retain':false},function(err, response){  console.log(response);});

6.4. Node.js: Suscripción a una variable

var mqtt = require("mqtt");var client  = mqtt.connect('mqtt://industrial.api.ubidots.com', {username:'c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5', password:""});client.subscribe({"/v1.6/devices/label_ds/variable_label": 1}, function(err, granted) {  console.log(granted);});client.on('message', function(topic, message, packet) {    //aquí puedes procesar actualizaciones del broker});

6.5. Node.js: Suscripción al último valor de una variable

var mqtt = require("mqtt");var client  = mqtt.connect('mqtt://industrial.api.ubidots.com', {username:'c74qFmzI7ikTmZ3dFvF3e2hPEmCfu5', password:""});client.subscribe({"/v1.6/devices/label_ds/variable_label/lv": 1}, function(err, granted) {  console.log(granted);});client.on('message', function(topic, message, packet) {    //aquí puedes procesar actualizaciones del broker});