'\" t
|
.\" Title: mqtt
|
.\" Author: [see the "Author" section]
|
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
.\" Date: 06/18/2019
|
.\" Manual: Conventions and miscellaneous
|
.\" Source: Mosquitto Project
|
.\" Language: English
|
.\"
|
.TH "MQTT" "7" "06/18/2019" "Mosquitto Project" "Conventions and miscellaneous"
|
.\" -----------------------------------------------------------------
|
.\" * Define some portability stuff
|
.\" -----------------------------------------------------------------
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
.\" http://bugs.debian.org/507673
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
.ie \n(.g .ds Aq \(aq
|
.el .ds Aq '
|
.\" -----------------------------------------------------------------
|
.\" * set default formatting
|
.\" -----------------------------------------------------------------
|
.\" disable hyphenation
|
.nh
|
.\" disable justification (adjust text to left margin only)
|
.ad l
|
.\" -----------------------------------------------------------------
|
.\" * MAIN CONTENT STARTS HERE *
|
.\" -----------------------------------------------------------------
|
.SH "NAME"
|
mqtt \- MQ Telemetry Transport
|
.SH "SYNOPSIS"
|
.HP \w'\fBMQTT\fR\ 'u
|
\fBMQTT\fR
|
.SH "DESCRIPTION"
|
.PP
|
\fBMQTT\fR
|
is a lightweight publish/subscribe messaging protocol\&. It is useful for use with low power sensors, but is applicable to many scenarios\&.
|
.PP
|
This manual describes some of the features of MQTT version 3\&.1\&.1/3\&.1, to assist end users in getting the most out of the protocol\&. For more complete information on MQTT, see
|
http://mqtt\&.org/\&.
|
.SH "PUBLISH/SUBSCRIBE"
|
.PP
|
The MQTT protocol is based on the principle of publishing messages and subscribing to topics, or "pub/sub"\&. Multiple clients connect to a broker and subscribe to topics that they are interested in\&. Clients also connect to the broker and publish messages to topics\&. Many clients may subscribe to the same topics and do with the information as they please\&. The broker and MQTT act as a simple, common interface for everything to connect to\&. This means that you if you have clients that dump subscribed messages to a database, to Twitter, Cosm or even a simple text file, then it becomes very simple to add new sensors or other data input to a database, Twitter or so on\&.
|
.SH "TOPICS/SUBSCRIPTIONS"
|
.PP
|
Messages in MQTT are published on topics\&. There is no need to configure a topic, publishing on it is enough\&. Topics are treated as a hierarchy, using a slash (/) as a separator\&. This allows sensible arrangement of common themes to be created, much in the same way as a filesystem\&. For example, multiple computers may all publish their hard drive temperature information on the following topic, with their own computer and hard drive name being replaced as appropriate:
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME
|
.RE
|
.PP
|
Clients can receive messages by creating subscriptions\&. A subscription may be to an explicit topic, in which case only messages to that topic will be received, or it may include wildcards\&. Two wildcards are available,
|
\fB+\fR
|
or
|
\fB#\fR\&.
|
.PP
|
\fB+\fR
|
can be used as a wildcard for a single level of hierarchy\&. It could be used with the topic above to get information on all computers and hard drives as follows:
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
sensors/+/temperature/+
|
.RE
|
.PP
|
As another example, for a topic of "a/b/c/d", the following example subscriptions will match:
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/b/c/d
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
+/b/c/d
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/+/c/d
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/+/+/d
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
+/+/+/+
|
.RE
|
.PP
|
The following subscriptions will not match:
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/b/c
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
b/+/c/d
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
+/+/+
|
.RE
|
.PP
|
\fB#\fR
|
can be used as a wildcard for all remaining levels of hierarchy\&. This means that it must be the final character in a subscription\&. With a topic of "a/b/c/d", the following example subscriptions will match:
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/b/c/d
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
#
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/#
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/b/#
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
a/b/c/#
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
+/b/c/#
|
.RE
|
.PP
|
Zero length topic levels are valid, which can lead to some slightly non\-obvious behaviour\&. For example, a topic of "a//topic" would correctly match against a subscription of "a/+/topic"\&. Likewise, zero length topic levels can exist at both the beginning and the end of a topic string, so "/a/topic" would match against a subscription of "+/a/topic", "#" or "/#", and a topic "a/topic/" would match against a subscription of "a/topic/+" or "a/topic/#"\&.
|
.SH "QUALITY OF SERVICE"
|
.PP
|
MQTT defines three levels of Quality of Service (QoS)\&. The QoS defines how hard the broker/client will try to ensure that a message is received\&. Messages may be sent at any QoS level, and clients may attempt to subscribe to topics at any QoS level\&. This means that the client chooses the maximum QoS it will receive\&. For example, if a message is published at QoS 2 and a client is subscribed with QoS 0, the message will be delivered to that client with QoS 0\&. If a second client is also subscribed to the same topic, but with QoS 2, then it will receive the same message but with QoS 2\&. For a second example, if a client is subscribed with QoS 2 and a message is published on QoS 0, the client will receive it on QoS 0\&.
|
.PP
|
Higher levels of QoS are more reliable, but involve higher latency and have higher bandwidth requirements\&.
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
0: The broker/client will deliver the message once, with no confirmation\&.
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
1: The broker/client will deliver the message at least once, with confirmation required\&.
|
.RE
|
.sp
|
.RS 4
|
.ie n \{\
|
\h'-04'\(bu\h'+03'\c
|
.\}
|
.el \{\
|
.sp -1
|
.IP \(bu 2.3
|
.\}
|
2: The broker/client will deliver the message exactly once by using a four step handshake\&.
|
.RE
|
.SH "RETAINED MESSAGES"
|
.PP
|
All messages may be set to be retained\&. This means that the broker will keep the message even after sending it to all current subscribers\&. If a new subscription is made that matches the topic of the retained message, then the message will be sent to the client\&. This is useful as a "last known good" mechanism\&. If a topic is only updated infrequently, then without a retained message, a newly subscribed client may have to wait a long time to receive an update\&. With a retained message, the client will receive an instant update\&.
|
.SH "CLEAN SESSION / DURABLE CONNECTIONS"
|
.PP
|
On connection, a client sets the "clean session" flag, which is sometimes also known as the "clean start" flag\&. If clean session is set to false, then the connection is treated as durable\&. This means that when the client disconnects, any subscriptions it has will remain and any subsequent QoS 1 or 2 messages will be stored until it connects again in the future\&. If clean session is true, then all subscriptions will be removed for the client when it disconnects\&.
|
.SH "WILLS"
|
.PP
|
When a client connects to a broker, it may inform the broker that it has a will\&. This is a message that it wishes the broker to send when the client disconnects unexpectedly\&. The will message has a topic, QoS and retain status just the same as any other message\&.
|
.SH "SEE ALSO"
|
\fBmosquitto\fR(8), \fBmosquitto_pub\fR(1), \fBmosquitto_sub\fR(1)
|
.SH "AUTHOR"
|
.PP
|
Roger Light
|
<roger@atchoo\&.org>
|
