1MQTT(7)                  Conventions and miscellaneous                 MQTT(7)
2
3
4

NAME

6       mqtt - MQ Telemetry Transport
7

SYNOPSIS

9       MQTT
10

DESCRIPTION

12       MQTT is a lightweight publish/subscribe messaging protocol. It is
13       useful for use with low power sensors, but is applicable to many
14       scenarios.
15
16       This manual describes some of the features of MQTT version 3.1.1/3.1,
17       to assist end users in getting the most out of the protocol. For more
18       complete information on MQTT, see http://mqtt.org/.
19

PUBLISH/SUBSCRIBE

21       The MQTT protocol is based on the principle of publishing messages and
22       subscribing to topics, or "pub/sub". Multiple clients connect to a
23       broker and subscribe to topics that they are interested in. Clients
24       also connect to the broker and publish messages to topics. Many clients
25       may subscribe to the same topics and do with the information as they
26       please. The broker and MQTT act as a simple, common interface for
27       everything to connect to. This means that you if you have clients that
28       dump subscribed messages to a database, to Twitter, Cosm or even a
29       simple text file, then it becomes very simple to add new sensors or
30       other data input to a database, Twitter or so on.
31

TOPICS/SUBSCRIPTIONS

33       Messages in MQTT are published on topics. There is no need to configure
34       a topic, publishing on it is enough. Topics are treated as a hierarchy,
35       using a slash (/) as a separator. This allows sensible arrangement of
36       common themes to be created, much in the same way as a filesystem. For
37       example, multiple computers may all publish their hard drive
38       temperature information on the following topic, with their own computer
39       and hard drive name being replaced as appropriate:
40
41       ·   sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME
42
43       Clients can receive messages by creating subscriptions. A subscription
44       may be to an explicit topic, in which case only messages to that topic
45       will be received, or it may include wildcards. Two wildcards are
46       available, + or #.
47
48       + can be used as a wildcard for a single level of hierarchy. It could
49       be used with the topic above to get information on all computers and
50       hard drives as follows:
51
52       ·   sensors/+/temperature/+
53
54       As another example, for a topic of "a/b/c/d", the following example
55       subscriptions will match:
56
57       ·   a/b/c/d
58
59       ·   +/b/c/d
60
61       ·   a/+/c/d
62
63       ·   a/+/+/d
64
65       ·   +/+/+/+
66
67       The following subscriptions will not match:
68
69       ·   a/b/c
70
71       ·   b/+/c/d
72
73       ·   +/+/+
74
75       # can be used as a wildcard for all remaining levels of hierarchy. This
76       means that it must be the final character in a subscription. With a
77       topic of "a/b/c/d", the following example subscriptions will match:
78
79       ·   a/b/c/d
80
81       ·   #
82
83       ·   a/#
84
85       ·   a/b/#
86
87       ·   a/b/c/#
88
89       ·   +/b/c/#
90
91       Zero length topic levels are valid, which can lead to some slightly
92       non-obvious behaviour. For example, a topic of "a//topic" would
93       correctly match against a subscription of "a/+/topic". Likewise, zero
94       length topic levels can exist at both the beginning and the end of a
95       topic string, so "/a/topic" would match against a subscription of
96       "+/a/topic", "#" or "/#", and a topic "a/topic/" would match against a
97       subscription of "a/topic/+" or "a/topic/#".
98

QUALITY OF SERVICE

100       MQTT defines three levels of Quality of Service (QoS). The QoS defines
101       how hard the broker/client will try to ensure that a message is
102       received. Messages may be sent at any QoS level, and clients may
103       attempt to subscribe to topics at any QoS level. This means that the
104       client chooses the maximum QoS it will receive. For example, if a
105       message is published at QoS 2 and a client is subscribed with QoS 0,
106       the message will be delivered to that client with QoS 0. If a second
107       client is also subscribed to the same topic, but with QoS 2, then it
108       will receive the same message but with QoS 2. For a second example, if
109       a client is subscribed with QoS 2 and a message is published on QoS 0,
110       the client will receive it on QoS 0.
111
112       Higher levels of QoS are more reliable, but involve higher latency and
113       have higher bandwidth requirements.
114
115       ·   0: The broker/client will deliver the message once, with no
116           confirmation.
117
118       ·   1: The broker/client will deliver the message at least once, with
119           confirmation required.
120
121       ·   2: The broker/client will deliver the message exactly once by using
122           a four step handshake.
123

RETAINED MESSAGES

125       All messages may be set to be retained. This means that the broker will
126       keep the message even after sending it to all current subscribers. If a
127       new subscription is made that matches the topic of the retained
128       message, then the message will be sent to the client. This is useful as
129       a "last known good" mechanism. If a topic is only updated infrequently,
130       then without a retained message, a newly subscribed client may have to
131       wait a long time to receive an update. With a retained message, the
132       client will receive an instant update.
133

CLEAN SESSION / DURABLE CONNECTIONS

135       On connection, a client sets the "clean session" flag, which is
136       sometimes also known as the "clean start" flag. If clean session is set
137       to false, then the connection is treated as durable. This means that
138       when the client disconnects, any subscriptions it has will remain and
139       any subsequent QoS 1 or 2 messages will be stored until it connects
140       again in the future. If clean session is true, then all subscriptions
141       will be removed for the client when it disconnects.
142

WILLS

144       When a client connects to a broker, it may inform the broker that it
145       has a will. This is a message that it wishes the broker to send when
146       the client disconnects unexpectedly. The will message has a topic, QoS
147       and retain status just the same as any other message.
148

SEE ALSO

150       mosquitto(8), mosquitto_pub(1), mosquitto_sub(1)
151

AUTHOR

153       Roger Light <roger@atchoo.org>
154
155
156
157Mosquitto Project                 08/19/2020                           MQTT(7)
Impressum