Qt MQTT Overview

Qt MQTT enables you to create applications and devices that can communicate over the MQ telemetry transport (MQTT) protocol. It fully complies to the MQTT protocol specification.

Publish and Subscribe

MQTT is a machine-to-machine connectivity protocol that operates on the publish-and-subscribe model. An MQTT client is a program or device that uses MQTT to create a network connection to an MQTT server, also called a broker. Once a connection is created, the client can send messages to the broker. The other clients can subscribe to notifications on particular topics sent by the client.

For example, if Client 2 subscribes to messages on Topic A, it receives a notification when Client 1 sends a message on that topic. If Client 3 subscribes to Topic A and Topic B, it receives notifications about messages on both those topics.

Qt MQTT is a client solution that does not include a broker. It is especially suitable for developing telemetry applications for embedded devices. However, Qt MQTT has no external dependencies, and therefore the implemented clients can be run on all supported Qt platforms.


Topics are stored in a hierarchical tree structure. The standard does not specify how the tree should be designed, nor does it provide predefined hierarchy sets. You can freely design the hierarchy as required by your project. The following is an example of a topic hierarchy, where active means all active sensors, whereas house and garage are individual sensors:


Subscribing to Topics Using Wildcards

When clients subscribe to topics, they can use the hash mark (#) and plus sign (+) as wildcards. The hash mark indicates that the client wants to receive notifications on all messages on a topic and its subtopics. For example, if a client subscribes to sensors/house/#, it receives all messages on the house sensor.

The plus sign indicates that a branch on the tree can be skipped over when looking for a matching subtopic. For example, if a client subscribes to sensors/+/temperature, it receives messages on temperature regardless of which sensor sent them. You can use multiple plus signs to skip over multiple branches. For example, house/+/+/temperature could be used to receive messages on the temperature of all rooms in all apartments in a house.


The connections between the clients and the broker are secured by an in-built authentication system that uses user names and passwords. Messages are encrypted by using SSL/TLS at the transport layer. The standardized port number for encrypted MQTT messages is 8883.

Quality of Service

The following quality of service (QoS) levels for messages are defined:

  • At most once (0) means that messages are delivered according to the best efforts of the operating environment, and therefore message loss can occur. This level could be used, for example, with ambient sensor data where it does not matter if an individual reading is lost as the next one will be published soon after.
  • At least once (1) means that messages are assured to arrive but duplicates can occur.
  • Exactly once (2) means that messages are assured to arrive exactly once. This level could be used, for example, with billing systems where duplicate or lost messages could lead to incorrect charges being applied.

Will Messages

A Will Message, also called testament, is a message sent from a client and stored at the broker location. If the connection between the client and broker breaks in an unexpected way, the Will Message will be forwarded to any subscriber of the Will Topic.

Will Messages must be specified at the connecting stage. Hence, it is mandatory to set them before invoking QMqttClient::connectToHost() or QMqttClient::connectToHostEncrypted(). A Will Message has all the properties of a regular message, as well as a Will Topic, QoS level, retained flag, and message payload.

If the client disconnects from the broker in a regular fashion by calling QMqttClient::disconnectFromHost(), the broker will discard the Will Message. If needed, the client is responsible for sending all the required messages before disconnecting.

Retained Messages

Retained messages are stored on the broker side. As future clients connect, they will receive such messages. A typical use case is to store the current health status of the publisher in a retained message. Subscribers will instantly receive a message about the status.

A broker can only store the last retained message sent for a specified topic. If a client publishes a retained message with the QoS level zero, any previously retained message for its topic at the broker must be discarded. The broker should store the last message, but may also discard it. This depends on the implementation of the broker.

© 2017 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.