===== What is MQTT =====
... see [[https://en.wikipedia.org/wiki/MQTT|Wikipedia]]
... see [[https://www.hivemq.com/blog/mqtt-essentials-part-1-introducing-mqtt]]
... see [[https://blog.doubleslash.de/mqtt-fuer-dummies/]]
===== MQTT Data Flow by Examples =====
{{ :tut:mqtt:mqttall.svg?600x0 }}
Based on this image the following examples can show typical data flows
==== Example: 1 Publisher, no Subscriber ====
* Client X connected
{{ :tut:mqtt:mqtt1.svg?600x0 }}
If Client X publishes any data with Topic 1 and nobody is listening (nobody has subscriped Topic 1) the data is lost.
(Exception: see Topics with Retain Flag)
==== Example: 1 Publisher, 1 Subscriber ====
* Client A connected
* Client B connected and subscripes Topic 2
{{ :tut:mqtt:mqtt2.svg?600x0 |}}
If Client A publishes any data with Topic 2 and Client B is notified instantly about change of Topic 2.
==== Example: Many Publisher, Many Subscriber ====
* Client A, C, E connected
* Client B connected and subscripes Topic 2
* Client F connected and subscripes Topic 3
{{ :tut:mqtt:mqtt3.svg?600x0 }}
Any Client can publish any data with any Topic at anytime. The subscribing Clients are notified instantly about change of the Topics they subscripes and only that.
==== Example: Many Publisher, 1 Subscriber with Wildcard ====
* Client A, C, E connected
* Client D connected and subscripes Topic with '#'
{{ :tut:mqtt:mqtt4.svg?600x0 }}
Any Client can publish any data with any Topic at anytime. A Client can subcripe with '+' and/or '#' in the Topic name. The Client is notified instantly about any change of all Topics which matches the wildcard Topic name.
==== Example: Request and Answer ====
* Client E connected and subscripes Topic 4
* Client F connected and subscripes Topic 3
{{ :tut:mqtt:mqtt5.svg?600x0 }}
Every Client can be publisher and subscriber. For sneding a request/command one Topic can be used. For the answer an other Topic is used.
Note: This can be solved with only one Tpoic but the publisher would receive his own request/command.
==== Example: QoS-Flag - Quality of Service ====
* Client G connected
* Client H connected and subscripes Topic 5 with QoS
{{ :tut:mqtt:mqtt6.svg?600x0 }}
A Client can publish data with any Topic with flag QoS set. This garantees that the data arrives the broker.
A Client can subscripe with flag QoS set. This garantees that the data arrives the clinet.
^QoS^Meaning^
|0|no garantee (default)|
|1|garantee that data arrives|
|2|garantee that data arrives only once|
Note: Each publisher and each subscriber can user the QoS flag without affecting the others.
==== Example: Remain-Flag ====
* Client Y was connected long time ago
* Client Z connects now and subscripes Topic 6
{{ :tut:mqtt:mqtt7.svg?600x0 }}
**Ages ago:** A Client publish any data with a Topic and Remain flag set. The broker stores the Topic with data in its own database/file. The publishing Client died...
**Now:** An other Client ist started and subscripes a Topic. The Client is notified instantly about the stored data of the Topic
^Remain^Meaning^
|0|fire and forget|
|1|saved on broker|
===== Topic Wording =====
There is no law that you have to name your topics in a special way. So the following names are (principle) correct:
* /MyHome/Kitchen/Temperature
* /MYHOME/KITCHEN/TEMPERATURE
* MyHome/Kitchen/Temperature
* MyHome.Kitchen.Temperature
* MyHomeKitchenTemperature
* MHKT
* /Temperature/Kitchen/MyHome
* 42
But there are some guidelines for names that all clinets can filter and handle subscriptions in an easy way:
* The topic begins with a '/'
* The topic do NOT end with a '/'
* A '/' seperates topic levels
* The topic levels starts with the most commen level
So the recommented name is:
* /MyHome/Kitchen/Temperature
===== Subscription Wildcard Examples =====
==== Exact Match ====
On subscribing **"/MyHome/Kitchen/Temperature"** you get:
* **/MyHome/Kitchen/Temperature**
* /MyHome/Kitchen/Humity
* /MyHome/Kitchen/Fridge/Temperature
* /MyHome/Livingroom/Temperature
* /MyHome/Livingroom/Humity
* /MyGarden/Air/Temperature
* /MyGarden/Pool/Temperature
==== # Wildcard ====
On subscribing **"/#"** you get:
* /MyHome/Kitchen/Temperature
* /MyHome/Kitchen/Humity
* /MyHome/Kitchen/Fridge/Temperature
* /MyHome/Livingroom/Temperature
* /MyHome/Livingroom/Humity
* /MyGarden/Air/Temperature
* /MyGarden/Pool/Temperature
On subscribing **"/MyHome/#"** you get:
* **/MyHome/**Kitchen/Temperature
* **/MyHome/**Kitchen/Humity
* **/MyHome/**Kitchen/Fridge/Temperature
* **/MyHome/**Livingroom/Temperature
* **/MyHome/**Livingroom/Humity
* /MyGarden/Air/Temperature
* /MyGarden/Pool/Temperature
On subscribing **"/MyHome/Kitchen/#"** you get:
* **/MyHome/Kitchen/**Temperature
* **/MyHome/Kitchen/**Humity
* **/MyHome/Kitchen/**Fridge/Temperature
* /MyHome/Livingroom/Temperature
* /MyHome/Livingroom/Humity
* /MyGarden/Air/Temperature
* /MyGarden/Pool/Temperature
==== + Wildcard ====
On subscribing **"/MyHome/+/Temperature"** you get:
* **/MyHome/**Kitchen**/Temperature**
* /MyHome/Kitchen/Humity
* /MyHome/Kitchen/Fridge/Temperature
* **/MyHome/**Livingroom**/Temperature**
* /MyHome/Livingroom/Humity
* /MyGarden/Air/Temperature
* /MyGarden/Pool/Temperature
On subscribing **"/+/+/Temperature"** you get:
* /MyHome/Kitchen**/Temperature**
* /MyHome/Kitchen/Humity
* /MyHome/Kitchen/Fridge/Temperature
* /MyHome/Livingroom**/Temperature**
* /MyHome/Livingroom/Humity
* /MyGarden/Air**/Temperature**
* /MyGarden/Pool**/Temperature**
On subscribing **"/+/+/+/Temperature"** you get:
* /MyHome/Kitchen/Temperature
* /MyHome/Kitchen/Humity
* /MyHome/Kitchen/Fridge**/Temperature**
* /MyHome/Livingroom/Temperature
* /MyHome/Livingroom/Humity
* /MyGarden/Air/Temperature
* /MyGarden/Pool/Temperature