1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
/******************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the QtMqtt module.
**
** $QT_BEGIN_LICENSE:COMM$
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** $QT_END_LICENSE$
**
******************************************************************************/
/*!
\page mqtt-overview.html
\title Qt MQTT Overview
\brief Provides insight into the MQTT protocol and the Qt MQTT module.
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.
\section1 Publish and Subscribe
\l{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
\e 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.
\image mqtt.png
For example, if \e {Client 2} subscribes to messages on \e {Topic A}, it
receives a notification when \e {Client 1} sends a message on that topic.
If \e {Client 3} subscribes to \e {Topic A} and \e {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.
\section1 Topics
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 \e active
means all active sensors, whereas \e house and \e garage are individual
sensors:
\badcode
sensors/active
sensors/house/temperature
sensors/house/bedroom/light
sensors/house/livingroom/light
sensors/garage/temperature
sensors/garage/light
\endcode
\section1 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 \e sensors/house/#, it receives all
messages on the \e 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
\e sensors/+/temperature, it receives messages on \e temperature regardless
of which sensor sent them. You can use multiple plus signs to skip over
multiple branches. For example, \e house/+/+/temperature could be used to
receive messages on the temperature of all rooms in all apartments in a
house.
\section1 Security
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.
\section1 Quality of Service
The following quality of service (QoS) levels for messages are defined:
\list
\li \e {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.
\li \e {At least once (1)} means that messages are assured to arrive but
duplicates can occur.
\li \e {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.
\endlist
\section1 Will Messages
A \e {Will Message}, also called \e 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 \e {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.
\section1 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 \e{must} be
discarded. The broker \e{should} store the last message, but \e{may}
also discard it. This depends on the implementation of the broker.
*/
|
