<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="manpage.xsl"?>

<refentry xml:id="mqtt" xmlns:xlink="http://www.w3.org/1999/xlink">
	<refmeta>
		<refentrytitle>mqtt</refentrytitle>
		<manvolnum>7</manvolnum>
		<refmiscinfo class="source">Mosquitto Project</refmiscinfo>
		<refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>mqtt</refname>
		<refpurpose>MQ Telemetry Transport</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>MQTT</command>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			<command>MQTT</command> is a lightweight publish/subscribe
			messaging protocol. It is useful for use with low power sensors, but
			is applicable to many scenarios.</para> <para>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 <uri type="webpage">https://mqtt.org/</uri>.
		</para>
	</refsect1>

	<refsect1>
		<title>Publish/Subscribe</title>
		<para>
			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,
			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.
		</para>
	</refsect1>

	<refsect1>
		<title>Topics/Subscriptions</title>
		<para>
			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:
		</para>
		<itemizedlist>
			<listitem><para>sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME</para></listitem>
		</itemizedlist>
		<para>
			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, <option>+</option> or <option>#</option>.
		</para>
		<para>
			<option>+</option> 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:
		</para>
		<itemizedlist>
			<listitem><para>sensors/+/temperature/+</para></listitem>
		</itemizedlist>
		<para>
			As another example, for a topic of "a/b/c/d", the following
			example subscriptions will match:
		</para>
		<itemizedlist mark="circle">
			<listitem><para>a/b/c/d</para></listitem>
			<listitem><para>+/b/c/d</para></listitem>
			<listitem><para>a/+/c/d</para></listitem>
			<listitem><para>a/+/+/d</para></listitem>
			<listitem><para>+/+/+/+</para></listitem>
		</itemizedlist>
		<para>
			The following subscriptions will not match:
		</para>
		<itemizedlist mark="circle">
			<listitem><para>a/b/c</para></listitem>
			<listitem><para>b/+/c/d</para></listitem>
			<listitem><para>+/+/+</para></listitem>
		</itemizedlist>
		<para>
			<option>#</option> 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:
		</para>
		<itemizedlist mark="circle">
			<listitem><para>a/b/c/d</para></listitem>
			<listitem><para>#</para></listitem>
			<listitem><para>a/#</para></listitem>
			<listitem><para>a/b/#</para></listitem>
			<listitem><para>a/b/c/#</para></listitem>
			<listitem><para>+/b/c/#</para></listitem>
		</itemizedlist>
		<para>
			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/#".
		</para>
	</refsect1>

	<refsect1>
		<title>Quality of Service</title>
		<para>
			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.
		</para>
		<para>
			Higher levels of QoS are more reliable, but involve higher
			latency and have higher bandwidth requirements.
		</para>
		<itemizedlist>
			<listitem><para>0: The broker/client will deliver the message once, with no confirmation.</para></listitem>
			<listitem><para>1: The broker/client will deliver the message at least once, with confirmation required.</para></listitem>
			<listitem><para>2: The broker/client will deliver the message exactly once by using a four step handshake.</para></listitem>
		</itemizedlist>
	</refsect1>

	<refsect1>
		<title>Retained Messages</title>
		<para>
			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.
		</para>
	</refsect1>

	<refsect1>
		<title>Clean session / Durable connections</title>
		<para>
			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.
		</para>
	</refsect1>

	<refsect1>
		<title>Wills</title>
		<para>
			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.
		</para>
	</refsect1>

	<refsect1>
		<title>See Also</title>
		<simplelist type="inline">
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-7.html">mosquitto</link></refentrytitle>
					<manvolnum>7</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto-8.html">mosquitto</link></refentrytitle>
					<manvolnum>8</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto_pub-1.html">mosquitto_pub</link></refentrytitle>
					<manvolnum>1</manvolnum>
				</citerefentry>
			</member>
			<member>
				<citerefentry>
					<refentrytitle><link xlink:href="mosquitto_sub-1.html">mosquitto_sub</link></refentrytitle>
					<manvolnum>1</manvolnum>
				</citerefentry>
			</member>
		</simplelist>
	</refsect1>

	<refsect1>
		<title>Author</title>
		<para>Roger Light <email>roger@atchoo.org</email></para>
	</refsect1>
</refentry>
