MQTT Protocol

Article by:
Date Published:
Last Modified:
WarningThis page is in notes format, and may not be of the same quality as other pages on this site.

1. Overview

MQTT is a lightweight publish/subscribe communications protocol that uses TCP/IP (and other secondary transport mechanisms). It is designed for remote sensors to communicate with controlling devices. The specification is under a royalty-free licence. Interesting features of the protocol include the one-to-many messaging service (publish/subscribe), the Last Will/Testament feature, and the three qualities of service. You can read more about it here.

mqtt logo
Figure 1. The MQTT logo. Image from, acquired 2021-03-30.

2. History

MQTT was initially released in a partnership between IBM and Arcom in 1998. As of 2021-03, the latest version is v5.0.

3. MQTT Brokers

Mosquitto is a very popular open-source MQTT broker.

Online test/sandbox brokers:

  • <>

3.1. Mosquitto

3.1.1. Installation


Mosquitto can be installed on Windows by downloading the pre-compiled binaries. The x64 version will be installed in a path similar to C:\Program Files\Mosquitto. You will likely want to add that directory path to your system path so that you can call mosquitto from the command line.

3.1.2. Running

If you have added the installation directory to your system path, you can invoke mosquitto with:


By default the above command will start a MQTT broker listening on port 1883 (the default port for non-encrypted traffic). The broker will not run as a daemon, so you can stop the broker with Ctrl-C (or equivalent). It also uses the following defaults:

  • No authentication

You can listen to all system topics by subscribing to $SYS/#.

If you are experiencing problems when running mosquitto, you might want to run in verbose mode -v to print debug information, as by default very little information is printed to the command-line:

$ mosquitto -v

1883 is the default port for unencrypted traffic. 8883 is the default port for traffic encrypted with SSL/TLS.

3.1.3. Common Errors

Client <client-name> disconnected due to protocol error.: Can be due to the client requesting TLS/SSL encryption on the non-encrypted 1883 port.

ssl3_read_bytes:tlsv1 alert unknown ca: Broker does not recognize the CA sent by the connecting client.

3.1.4. Creating Password Files

mosquitto_passwd is a utility provided alongside mosquitto which can generate password files for mosquitto. These password files control user access to the broker.

4. MQTT Clients

Paho is a popular MQTT client for Desktop and server machines running Windows, Linux or macOS. It’s API is reasonably well documented at

You can install Paho the standard way using pip:

pip install paho-mqtt

The Paho library can then be imported into your Python files with:

import paho.mqtt.client as mqtt

To request that the client creates the connection by supplying a username and password, call username_pw_set() on the client before calling connect():

client.username_pw_set('admin', 'password')
client.connect_async(self.broker_address, 1883, 60)

4.1. MQTT Clients For Embedded Devices

There are a number of MQTT clients designed for embedded devices, these include:

  • The embedded Paho MQTT client: Embedded version of the popular Paho MQTT client. It is released as two separate APIs:

  • MQTTPacket: Low-level C library that deals with the serialization/deserialization of MQTT packets.

  • MQTTClient: Higher-level C++ library first written for the mbed platform. Depends on MQTTPacket.

  • arduino-mqtt: Arduino wrapper around the lwmqtt MQTT client. Also available for PlatformIO. This one is pretty popular and is recommended in the AWS IoT tutorials.

  • coreMQTT: MQTT client maintained by the FreeRTOS group (however, the library does not depend on FreeRTOS to operate).



Related Content:


comments powered by Disqus