Provided by: mosquitto_0.12-1_i386 bug

NAME

       mqtt - MQ Telemetry Transport

SYNOPSIS

       mqtt

DESCRIPTION

       mqtt  is  a  publish/subscribe  messaging  protocol  intended  that  is
       designed to be lightweight.  It  is  useful  for  use  with  low  power
       sensors, but is applicable to many scenarios.

       This  manual  describes  some  of  the features of mqtt version 3.1, to
       assist end users in getting the most  out  of  it.  For  more  complete
       information on mqtt, see http://mqtt.org/.

PUBLISH/SUBSCRIBE

       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, pachube 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.

TOPICS/SUBSCRIPTIONS

       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:

       · sensors/COMPUTER_NAME/temperature/HARDDRIVE_NAME

       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, + or #.

       +  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:

       · sensors/+/temperature/+

       As  another  example,  for  a topic of "a/b/c/d", the following example
       subscriptions will match:

       · a/b/c/d

       · +/b/c/d

       · a/+/c/d

       · a/+/+/d

       · +/+/+/+

       The following subscriptions will not match:

       · a/b/c

       · b/+/c/d

       · +/+/+

       # 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:

       · a/b/c/d

       · #

       · a/#

       · a/b/#

       · a/b/c/#

       · +/b/c/#

QUALITY OF SERVICE

       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.

       Higher levels of QoS are more reliable, but involve higher latency  and
       have higher bandwidth requirements.

       · 0:   The  broker/client  will  deliver  the  message  once,  with  no
         confirmation.

       · 1: The broker/client will deliver the message  at  least  once,  with
         confirmation required.

       · 2: The broker/client will deliver the message exactly once by using a
         four step handshake.

RETAINED MESSAGES

       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.

CLEAN SESSION / DURABLE CONNECTIONS

       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.

WILLS

       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.

SEE ALSO

       mosquitto(8) mosquitto_pub(1) mosquitto_sub(1)

AUTHOR

       Roger Light <roger@atchoo.org>

                                 25 July 2011                          mqtt(7)