# Python/MQTT
## Objective

This tutorial will guide you to work with MQTT protocol in Python by using Paho MQTT client library (paho-mqtt). This tutorial is specifically for anyone who intends to use a third party library for MQTT to send and receive data between devices. The Python programming skills required for this tutorial is very basic. This tutorial will also cover a short introduction to ThingsBoard, a free-for-testing IoT platform, which you can use as a MQTT broker to test your MQTT client's program.
As using 3rd lib paho-mqtt, this tutorial will not include any details explanation to implement MQTT client from TCP socket API as its lower level. However, user need to have some basic knowledge on MQTT protocol before proceeding with this tutorial.

## Introduction

MQTT is a publish/subscribe communication protocol which runs on port 1883. For MQTT official document, refer to MQTT v3.1.1.
A MQTT system must includes a broker, and the client(s) connect to that broker. The MQTT broker acts as a post office which the MQTT clients connect to. MQTT clients can be subscribers and publisher. A subscriber subscribes to a topic on the MQTT broker while the publisher publishes message to a topic on the broker. For example:
* MQTT client A is a subscriber and subscribes to topic "data" of a local MQTT broker at 127.0.0.1:1883
* MQTT client B is a publisher and publish message "Hello, World !" to topic "data" of this local MQTT broker
* MQTT client A then receives the published message "Hello, World !" from client B.
For the local MQTT broker for testing, in this tutorial, we use Mosquitto. Install (on Linux):
After installing successfully, local MQTT broker Mosquitto runs on port 1883 by default.
Then, we install paho-mqtt as the MQTT client:

## Publish and subscribe to a local MQTT broker

For both publisher and subscriber, we connects to the MQTT broker with the connect function:
* keepalive: maximum period in seconds allowed between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker
In paho-mqtt, the maximum packet size is 256MB
MQTT client A publishes text message to a MQTT broker
MQTT client B subscribes to topic "test/message" to get the published message of MQTT client A:
Use userdata
A process works both as publisher and subscriber:
Use paho.mqtt
subscribe.py
publish.py
Both subscribe.py and publish.py can't both use import paho.mqtt.client as mqtt, if using this, subscriber or publisher will not be able to receive message.

## Publish and subscribe to a cloud MQTT broker

There are multiple free-for-testing cloud MQTT brokers, such as Eclipse.org and ThingsBoard (which we will discuss later). In this part, we will test the publish, subscribe feature with the Eclipse MQTT broker located at mqtt.eclipse.org
Publisher:
Subscriber:
callback: work every time when a message is published
simple: only work one time, receive one message then stops

## Publish and subscribe with publish and subscribe class

publish.py
subscribe.py

## Working with ThingsBoard

ThingsBoard is a IoT platform which can be use for free testing with multiple communication protocols like HTTP, MQTT, WebSocket,... or using for enterprise purpose. In this tutorial, we will use the ThingsBoard live demo server MQTT broker to testing.
At first, we need to know how to setup authentication for a MQTT client with username and password in paho-mqtt:

### Telemetry

MQTT client sends increasing number to ThingsBoard livedemo MQTT broker

### Map widget

Simply send the valid latitude and longitude value as JSON field to client.publish

### RPC
#### Control GPIO on Basic GPIO panel

Control 3 GPIO on Basic GPIO panel and save its previous setup status (i.e Able to display the previous setup status when dashboard is reloaded)

#### Control multiple devices by multithread

To control multiple devices, use multithread.
Features:
* Control 2 devices on ThingsBoard with MQTT client
* Print out the received message with specific device name that publishes that MQTT message
Program: thingsboard_basic_gpio_panel_multiple_devices.py

#### Control a GPIO with mode selection in Basic GPIO panel

Basic GPIO panel includes 2 GPIO, RELAY and MODE.
* If MODE is MANUAL (0): Control RELAY normally
* If MODE is AUTOMATION (1): RELAY can't be control and keep its previously set value
Program: thingsboard_basic_gpio_panel_mode_selection.py

## Conclusion

Congratulation ! You have reached the end of the tutorial. The tutorial is very basic for hobbyist and inexperience developers who will gain enough basic knowledge with MQTT with paho-mqtt library to work on their hobbyist projects. Hobbyist will need to investigate more on the paho-mqtt library API based on their projects' features.
For developers and students who want to deep dive into the MQTT protocols, please start by implementing the whole MQTT client publish and subscribe program from the raw TCP socket API. The whole protocol descriptions for that implementation can be found in MQTT v3.1.1.