| 1 | <?xml version='1.0' encoding='UTF-8'?>
|
| 2 | <?xml-stylesheet type="text/xsl" href="manpage.xsl"?>
|
| 3 |
|
| 4 | <refentry xml:id="mqtt" xmlns:xlink="http://www.w3.org/1999/xlink">
|
| 5 | <refmeta>
|
| 6 | <refentrytitle>mqtt</refentrytitle>
|
| 7 | <manvolnum>7</manvolnum>
|
| 8 | <refmiscinfo class="source">Mosquitto Project</refmiscinfo>
|
| 9 | <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
|
| 10 | </refmeta>
|
| 11 |
|
| 12 | <refnamediv>
|
| 13 | <refname>mqtt</refname>
|
| 14 | <refpurpose>MQ Telemetry Transport</refpurpose>
|
| 15 | </refnamediv>
|
| 16 |
|
| 17 | <refsynopsisdiv>
|
| 18 | <cmdsynopsis>
|
| 19 | <command>MQTT</command>
|
| 20 | </cmdsynopsis>
|
| 21 | </refsynopsisdiv>
|
| 22 |
|
| 23 | <refsect1>
|
| 24 | <title>Description</title>
|
| 25 | <para><command>MQTT</command> is a lightweight publish/subscribe
|
| 26 | messaging protocol. It is useful for use with low power sensors, but
|
| 27 | is applicable to many scenarios.</para> <para>This manual describes
|
| 28 | some of the features of MQTT version 3.1, to assist end users in
|
| 29 | getting the most out of the protocol. For more complete information on
|
| 30 | MQTT, see <uri type="webpage">http://mqtt.org/</uri>.</para>
|
| 31 | </refsect1>
|
| 32 |
|
| 33 | <refsect1>
|
| 34 | <title>Publish/Subscribe</title>
|
| 35 | <para>The MQTT protocol is based on the principle of publishing
|
| 36 | messages and subscribing to topics, or "pub/sub". Multiple clients
|
| 37 | connect to a broker and subscribe to topics that they are interested
|
| 38 | in. Clients also connect to the broker and publish messages to topics.
|
| 39 | Many clients may subscribe to the same topics and do with the
|
| 40 | information as they please. The broker and MQTT act as a simple, common
|
| 41 | interface for everything to connect to. This means that you if you have
|
| 42 | clients that dump subscribed messages to a database, to Twitter,
|
| 43 | Cosm or even a simple text file, then it becomes very simple to add
|
| 44 | new sensors or other data input to a database, Twitter or so on.</para>
|
| 45 | </refsect1>
|
| 46 |
|
| 47 | <refsect1>
|
| 48 | <title>Topics/Subscriptions</title>
|
| 49 | <para>Messages in MQTT are published on topics. There is no need to
|
| 50 | configure a topic, publishing on it is enough. Topics are treated as a
|
| 51 | hierarchy, using a slash (/) as a separator. This allows sensible
|
| 52 | arrangement of common themes to be created, much in the same way as a
|
| 53 | filesystem. For example, multiple computers may all publish their
|
| 54 | hard drive temperature information on the following topic, with their
|
| 55 | own computer and hard drive name being replaced as appropriate:</para>
|
| 56 | <itemizedlist>
|
| 57 | <listitem><para>sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME</para></listitem>
|
| 58 | </itemizedlist>
|
| 59 | <para>Clients can receive messages by creating subscriptions. A
|
| 60 | subscription may be to an explicit topic, in which case only messages
|
| 61 | to that topic will be received, or it may include wildcards. Two
|
| 62 | wildcards are available, <option>+</option> or <option>#</option>.</para>
|
| 63 | <para><option>+</option> can be used as a wildcard for a single level
|
| 64 | of hierarchy. It could be used with the topic above to get information
|
| 65 | on all computers and hard drives as follows:</para>
|
| 66 | <itemizedlist>
|
| 67 | <listitem><para>sensors/+/temperature/+</para></listitem>
|
| 68 | </itemizedlist>
|
| 69 | <para>As another example, for a topic of "a/b/c/d", the following
|
| 70 | example subscriptions will match:</para>
|
| 71 | <itemizedlist mark="circle">
|
| 72 | <listitem><para>a/b/c/d</para></listitem>
|
| 73 | <listitem><para>+/b/c/d</para></listitem>
|
| 74 | <listitem><para>a/+/c/d</para></listitem>
|
| 75 | <listitem><para>a/+/+/d</para></listitem>
|
| 76 | <listitem><para>+/+/+/+</para></listitem>
|
| 77 | </itemizedlist>
|
| 78 | <para>The following subscriptions will not match:</para>
|
| 79 | <itemizedlist mark="circle">
|
| 80 | <listitem><para>a/b/c</para></listitem>
|
| 81 | <listitem><para>b/+/c/d</para></listitem>
|
| 82 | <listitem><para>+/+/+</para></listitem>
|
| 83 | </itemizedlist>
|
| 84 | <para><option>#</option> can be used as a wildcard for all remaining levels of
|
| 85 | hierarchy. This means that it must be the final character in a
|
| 86 | subscription. With a topic of "a/b/c/d", the following example
|
| 87 | subscriptions will match:</para>
|
| 88 | <itemizedlist mark="circle">
|
| 89 | <listitem><para>a/b/c/d</para></listitem>
|
| 90 | <listitem><para>#</para></listitem>
|
| 91 | <listitem><para>a/#</para></listitem>
|
| 92 | <listitem><para>a/b/#</para></listitem>
|
| 93 | <listitem><para>a/b/c/#</para></listitem>
|
| 94 | <listitem><para>+/b/c/#</para></listitem>
|
| 95 | </itemizedlist>
|
| 96 | <para>Zero length topic levels are valid, which can lead to some
|
| 97 | slightly non-obvious behaviour. For example, a topic of "a//topic"
|
| 98 | would correctly match against a subscription of "a/+/topic".
|
| 99 | Likewise, zero length topic levels can exist at both the beginning
|
| 100 | and the end of a topic string, so "/a/topic" would match against a
|
| 101 | subscription of "+/a/topic", "#" or "/#", and a topic "a/topic/"
|
| 102 | would match against a subscription of "a/topic/+" or
|
| 103 | "a/topic/#".</para>
|
| 104 | </refsect1>
|
| 105 |
|
| 106 | <refsect1>
|
| 107 | <title>Quality of Service</title>
|
| 108 | <para>MQTT defines three levels of Quality of Service (QoS). The QoS
|
| 109 | defines how hard the broker/client will try to ensure that a message is
|
| 110 | received. Messages may be sent at any QoS level, and clients may
|
| 111 | attempt to subscribe to topics at any QoS level. This means that the
|
| 112 | client chooses the maximum QoS it will receive. For example, if a
|
| 113 | message is published at QoS 2 and a client is subscribed with QoS 0,
|
| 114 | the message will be delivered to that client with QoS 0. If a second
|
| 115 | client is also subscribed to the same topic, but with QoS 2, then it
|
| 116 | will receive the same message but with QoS 2. For a second example, if
|
| 117 | a client is subscribed with QoS 2 and a message is published on QoS 0,
|
| 118 | the client will receive it on QoS 0.</para>
|
| 119 | <para>Higher levels of QoS are more reliable, but involve higher
|
| 120 | latency and have higher bandwidth requirements.</para>
|
| 121 | <itemizedlist>
|
| 122 | <listitem><para>0: The broker/client will deliver the message once, with no confirmation.</para></listitem>
|
| 123 | <listitem><para>1: The broker/client will deliver the message at least once, with confirmation required.</para></listitem>
|
| 124 | <listitem><para>2: The broker/client will deliver the message exactly once by using a four step handshake.</para></listitem>
|
| 125 | </itemizedlist>
|
| 126 | </refsect1>
|
| 127 |
|
| 128 | <refsect1>
|
| 129 | <title>Retained Messages</title>
|
| 130 | <para>All messages may be set to be retained. This means that the
|
| 131 | broker will keep the message even after sending it to all current
|
| 132 | subscribers. If a new subscription is made that matches the topic of
|
| 133 | the retained message, then the message will be sent to the client. This
|
| 134 | is useful as a "last known good" mechanism. If a topic is only updated
|
| 135 | infrequently, then without a retained message, a newly subscribed
|
| 136 | client may have to wait a long time to receive an update. With a
|
| 137 | retained message, the client will receive an instant update.</para>
|
| 138 | </refsect1>
|
| 139 |
|
| 140 | <refsect1>
|
| 141 | <title>Clean session / Durable connections</title>
|
| 142 | <para>On connection, a client sets the "clean session" flag, which is
|
| 143 | sometimes also known as the "clean start" flag. If clean session is set
|
| 144 | to false, then the connection is treated as durable. This means that
|
| 145 | when the client disconnects, any subscriptions it has will remain and
|
| 146 | any subsequent QoS 1 or 2 messages will be stored until it connects
|
| 147 | again in the future. If clean session is true, then all subscriptions
|
| 148 | will be removed for the client when it disconnects.</para>
|
| 149 | </refsect1>
|
| 150 |
|
| 151 | <refsect1>
|
| 152 | <title>Wills</title>
|
| 153 | <para>When a client connects to a broker, it may inform the broker that
|
| 154 | it has a will. This is a message that it wishes the broker to send when
|
| 155 | the client disconnects unexpectedly. The will message has a topic,
|
| 156 | QoS and retain status just the same as any other message.</para>
|
| 157 | </refsect1>
|
| 158 |
|
| 159 | <refsect1>
|
| 160 | <title>See Also</title>
|
| 161 | <simplelist type="inline">
|
| 162 | <member>
|
| 163 | <citerefentry>
|
| 164 | <refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
|
| 165 | <manvolnum>8</manvolnum>
|
| 166 | </citerefentry>
|
| 167 | </member>
|
| 168 | <member>
|
| 169 | <citerefentry>
|
| 170 | <refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
|
| 171 | <manvolnum>1</manvolnum>
|
| 172 | </citerefentry>
|
| 173 | </member>
|
| 174 | <member>
|
| 175 | <citerefentry>
|
| 176 | <refentrytitle><link xlink:href="mosquitto_sub-1.html">mosquitto_sub</link></refentrytitle>
|
| 177 | <manvolnum>1</manvolnum>
|
| 178 | </citerefentry>
|
| 179 | </member>
|
| 180 | </simplelist>
|
| 181 | </refsect1>
|
| 182 |
|
| 183 | <refsect1>
|
| 184 | <title>Author</title>
|
| 185 | <para>Roger Light <email>roger@atchoo.org</email></para>
|
| 186 | </refsect1>
|
| 187 | </refentry>
|