Qt MQTT Descripción general
Qt MQTT te permite crear aplicaciones y dispositivos capaces de comunicarse a través del protocolo de transporte de telemetría MQ (MQTT). Cumple plenamente con la especificación del protocolo MQTT.
Publicación y suscripción
MQTT es un protocolo de conectividad de máquina a máquina que funciona según el modelo de publicación y suscripción. Un cliente MQTT es un programa o dispositivo que utiliza MQTT para establecer una conexión de red con un servidor MQTT, también denominado «broker». Una vez establecida la conexión, el cliente puede enviar mensajes al broker. Los demás clientes pueden suscribirse a las notificaciones sobre temas concretos enviadas por el cliente.

Por ejemplo, si el Cliente 2 se suscribe a los mensajes del Tema A, recibe una notificación cuando el Cliente 1 envía un mensaje sobre ese tema. Si el Cliente 3 se suscribe al Tema A y al Tema B, recibe notificaciones sobre los mensajes de ambos temas.
Qt MQTT es una solución de cliente que no incluye un broker. Resulta especialmente adecuada para desarrollar aplicaciones de telemetría para dispositivos embebidos. Sin embargo, Qt MQTT no tiene dependencias externas, por lo que los clientes implementados pueden ejecutarse en todas las plataformas Qt compatibles.
Temas
Los temas se almacenan en una estructura de árbol jerárquica. El estándar no especifica cómo debe diseñarse el árbol, ni proporciona conjuntos jerárquicos predefinidos. Puedes diseñar libremente la jerarquía según lo requiera tu proyecto. A continuación se muestra un ejemplo de jerarquía de temas, donde «activo» se refiere a todos los sensores activos, mientras que «casa» y «garaje» son sensores individuales:
sensors/active
sensors/house/temperature
sensors/house/bedroom/light
sensors/house/livingroom/light
sensors/garage/temperature
sensors/garage/lightSuscripción a temas mediante comodines
Cuando los clientes se suscriben a temas, pueden utilizar el símbolo de almohadilla (#) y el signo más (+) como comodines. El símbolo de almohadilla indica que el cliente desea recibir notificaciones sobre todos los mensajes de un tema y sus subtemas. Por ejemplo, si un cliente se suscribe a «sensors/house/#», recibirá todos los mensajes relacionados con el sensor «house ».
El signo más indica que se puede omitir una rama del árbol al buscar un subtema coincidente. Por ejemplo, si un cliente se suscribe a «sensors/+/temperature», recibirá mensajes sobre la temperatura independientemente del sensor que los haya enviado. Se pueden utilizar varios signos más para omitir varias ramas. Por ejemplo, «house/+/+/temperature» podría utilizarse para recibir mensajes sobre la temperatura de todas las habitaciones de todos los apartamentos de una casa.
Suscripciones compartidas
Las suscripciones compartidas describen un conjunto de suscriptores a un filtro de tema. En lugar de que todos los suscriptores reciban un mensaje, solo lo recibe uno. Esto permite el equilibrio de carga entre varios clientes. El formato de una suscripción compartida es:
$share/{sharename}/{topicfilter}Por ejemplo, si el Cliente 1 y el Cliente 2 deben compartir una suscripción al tema «sensors/house/temperature», el filtro de tema al que suscribirse es:
$share/poolAB/sensors/house/temperatureNo está definido en qué orden distribuye el servidor los mensajes. Se trata de una opción específica del servidor.
Para saber si un servidor admite suscripciones compartidas, consulta también QMqttServerConnectionProperties::sharedSubscriptionSupported().
Alias de temas
Estructurar los temas en forma de árbol ayuda a separar los canales de datos y a proporcionar un orden lógico de la información. Sin embargo, esto puede dar lugar a que se utilicen nombres de temas muy largos durante la publicación de mensajes, lo que aumenta el tamaño de cada mensaje.
La versión del protocolo MQTT 5.0 introdujo los alias de temas para evitarlo. En lugar de la cadena del tema, se envía un valor entero. Para crear una asignación inicial entre el cliente y el servidor, tanto la cadena del tema como el alias deben formar parte de un mensaje. A partir de entonces, solo se utiliza el ID con un tema vacío.
Esta asignación se puede modificar en cualquier momento utilizando un alias de tema con otra cadena de tema. Tenga en cuenta que esta asignación no se aplica necesariamente a otras conexiones, como las conexiones del servidor a otros clientes. Cada conexión debe crear esta asignación manualmente.
Qt MQTT proporciona un mecanismo automatizado para ayudar a reducir las tasas de datos. Una vez que QMqttClient establece una conexión, se almacena la información sobre los alias de tema admitidos por el servidor. Posteriormente, los alias de tema se utilizan en el orden en que se publican los mensajes, hasta que se estén utilizando todos los alias disponibles. El usuario siempre puede modificar esta asignación utilizando QMqttPublishProperties::setTopicAlias() durante la publicación.
Cuando QMqttClient se suscribe a un tema, el servidor también puede utilizar alias de temas, dependiendo del valor de QMqttConnectionProperties::maximumTopicAlias() establecido por el cliente. El cliente asigna automáticamente los alias de temas y reenvía de forma transparente los mensajes al usuario incluyendo la cadena completa del tema.
Seguridad
Las conexiones entre los clientes y el broker están protegidas por un sistema de autenticación integrado que utiliza nombres de usuario y contraseñas. Los mensajes se cifran mediante SSL/TLS en la capa de transporte. El número de puerto estandarizado para los mensajes MQTT cifrados es el 8883.
Calidad de servicio
Se definen los siguientes niveles de calidad de servicio (QoS) para los mensajes:
- «Como máximo una vez» (0) significa que los mensajes se entregan según las mejores capacidades del entorno operativo y, por lo tanto, puede producirse la pérdida de mensajes. Este nivel podría utilizarse, por ejemplo, con datos de sensores ambientales, en los que no importa si se pierde una lectura concreta, ya que la siguiente se publicará poco después.
- «Al menos una vez» (1) significa que se garantiza la llegada de los mensajes, pero pueden producirse duplicados.
- «Exactamente una vez» (2) significa que se garantiza que los mensajes lleguen exactamente una vez. Este nivel podría utilizarse, por ejemplo, con sistemas de facturación en los que los mensajes duplicados o perdidos podrían dar lugar a la aplicación de cargos incorrectos.
Mensajes «Will»
Un «mensaje Will», también denominado «testamento», es un mensaje enviado desde un cliente y almacenado en el servidor intermediario. Si la conexión entre el cliente y el servidor intermediario se interrumpe de forma inesperada, el mensaje Will se reenviará a cualquier suscriptor del tema Will.
Los mensajes «Will» deben especificarse en la fase de conexión. Por lo tanto, es obligatorio configurarlos antes de invocar QMqttClient::connectToHost() o QMqttClient::connectToHostEncrypted(). Un mensaje «Will» tiene todas las propiedades de un mensaje normal, además de un tema «Will», un nivel de calidad de servicio (QoS), un indicador de retención y la carga útil del mensaje.
Si el cliente se desconecta del broker de forma habitual llamando a QMqttClient::disconnectFromHost(), el broker descartará el mensaje «Will». Si es necesario, el cliente es responsable de enviar todos los mensajes requeridos antes de desconectarse.
Mensajes retenidos
Los mensajes retenidos se almacenan en el bróker. A medida que se conecten futuros clientes, recibirán dichos mensajes. Un caso de uso típico es almacenar el estado de salud actual del editor en un mensaje retenido. Los suscriptores recibirán al instante un mensaje sobre dicho estado.
Un broker solo puede almacenar el último mensaje retenido enviado para un tema específico. Si un cliente publica un mensaje retenido con un nivel de calidad de servicio (QoS) cero, cualquier mensaje retenido anteriormente para ese tema en el broker deberá descartarse. El broker debería almacenar el último mensaje, pero también podría descartarlo. Esto depende de la implementación del broker.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.