.. _user/protocols/mqtt:

****
MQTT
****

MQTT (Message Queue Telemetry Transport) is an ISO standard
**publish-subscribe**-based messaging protocol, which is becoming the de-facto
standard protocol for accessing IoT data from the internet.

Overview
========

Publishing means that data is uploaded to a well-defined place (called **topic**)
on a central server (called **message-broker**). Subscribing means that data is
downloaded from a topic of the message broker once it was published there.
Hence, MQTT is an event-driven communication protocol notifying a subscriber
once a data **message** has arrived on its topic.

This article describes the properties of an MQTT client connection to an external
broker. To get information about topic mapping on the internal Connectware MQTT
broker see the article :ref:`user/services/structure/resources/mapping`.

Usage
=====

To send or receive data via MQTT, a connection resource of the protocol ``MQTT``
has to be defined. The most simple configuration requires a host name of the broker
and the port of the broker. The full list of connection parameters which can be
configured is available at :ref:`user/protocols/mqtt_connection`.

To receive data from a broker, an endpoint resource with the property ``subscribe``
has to be defined. In the other direction, to send data to the broker, an endpoint
with the property ``write`` has to be defined. An endpoint can only have one
of the two properties. The properties which define the respective configuration
are listed under :ref:`user/protocols/mqtt_endpoint`.

.. _user/protocols/mqtt_connection:

.. include:: ../protocolSchemas/MqttConnection.rst

.. _user/protocols/mqtt_endpoint:

.. include:: ../protocolSchemas/MqttEndpoint.rst


Output Format on Write
----------------------
The MQTT protocol does not output results to the `/res` endpoint.

Output Format on Read
---------------------
When data is read from MQTT, via a subscription Endpoint, the messages
arriving to the target MQTT server are passed through unmodified.

Input Format on Write
---------------------

When data is written to  MQTT, via a write Endpoint, no special format
is required and data is published to the target MQTT server unmodified.

.. _user/protocols/mqtt/overlapping:

Duplicates on overlapping subscriptions
----------------------------------------
In the case of multiple overlapping topic subscriptions with wildcards, there is
a somewhat unexpected behaviour causing duplicate messages. As an example, if
there is one subscription (such as a
:ref:`user/services/structure/resources/mapping`) to topic ``topic/something``
and another to ``topic/#``, each connected target (Mapping or Endpoint) will
then receive two messages instead of one. This is caused by the behaviour of the
internal MQTT broker and cannot be avoided, as it is an allowed behaviour of the
MQTT 3.1 specification.

Example Configuration
======================

The following example demonstrates how to configure a simple MQTT connection and
endpoint that subscribes to the topic **some/test1**.

Download: :download:`mqtt-test1.yml`

.. literalinclude:: mqtt-test1.yml
  :language: yaml
  :linenos: