Introduction

Async.MQTT5 is a C++17 client built on Boost.Asio. This client is designed for publishing or receiving messages from an MQTT 5.0 compatible Broker. Async.MQTT5 represents a comprehensive implementation of the MQTT 5.0 protocol standard, offering full support for publishing or receiving messages with QoS 0, 1, and 2.

Motivation

The MQTT protocol is widely utilised for communication in various real-world scenarios, primarily serving as a reliable communication protocol for data transfer to and from IoT devices. While the MQTT protocol is relatively straightforward, integrating it into an application can be complex, primarily due to the challenging implementation of message retransmission after a disconnect/reconnect sequence. To address these challenges and simplify MQTT integration once and for all, Async.MQTT5 was designed with the following core objectives in mind:

Table 1.1. Core objectives

Objective	Description
"Plug and play" interface that abstracts away MQTT protocol internals, low-level network events, message retransmission and other complexities	Enables developers to publish or receive messages with just a single line of code, significantly reducing the learning curve and development time. Getting started requires basic MQTT knowledge, making the library accessible to developers of all skill levels.
Highly reliable and robust Client that handles network losses, unreliable data transport, network latencies, and other unpredictable events	The Client does not expose connect functions (nor asynchronous connect functions); instead, network connectivity, MQTT handshake, and message retransmission are automatically handled within the Client while strictly adhering to the MQTT specification. This automation eliminates the need for developers to write extensive and error-prone code to handle these scenarios, allowing them to focus on the application's core functionality.
Complete adherence to the Boost.Asio's universal asynchronous model	The interfaces and implementation strategies are built upon the foundations of Boost.Asio. This compatibility enables seamless integration with any other library within the Boost.Asio ecosystem.

When to Use

Async.MQTT5 might be suitable for you if any of the following statements is true:

Your application uses Boost.Asio and requires integrating an MQTT Client.
You require asynchronous access to an MQTT Broker.
You are developing a higher-level component that requires a connection to an MQTT Broker.
You require a dependable and resilient MQTT Client to manage all network-related issues automatically.

It may not be suitable for you if:

You solely require synchronous access to an MQTT Broker.
The MQTT Broker you connect to does not support the MQTT 5 version.

Features

Async.MQTT5 is a library designed with the core belief that users should focus solely on their application logic, not the network complexities.
The library attempts to embody this belief with a range of key features designed to elevate the development experience:

Table 1.2. Features

Feature	Description
Complete TCP, TLS/SSL, and WebSocket support	The MQTT protocol requires an underlying network protocol that provides ordered, lossless, bi-directional connection (stream). Users can customize this stream through a template parameter. The Async.MQTT5 library has been tested with the most used transport protocols: TCP/IP using `boost::asio::ip::tcp::socket`, TLS/SSL using `boost::asio::ssl::stream`, WebSocket/TCP and WebSocket/TLS using `boost::beast::websocket::stream`).
Automatic reconnect and retry mechanism	Automatically handles connection loss, backoffs, reconnections, and message transmissions. Automating these processes enables users to focus entirely on the application's functionality. See Built-in Auto-Reconnect and Retry Mechanism.
Prioritised efficiency	Utilises network and memory resources as efficiently as possible.
Minimal memory footprint	Ensures optimal performance in resource-constrained environments typical of IoT devices.
Completion token	All asynchronous functions are implemented using Boost.Asio's universal asynchronous model and support CompletionToken. This allows versatile usage with callbacks, coroutines, and futures.
Custom allocators	Support for custom allocators allows extra flexibility and control over the memory resources. Async.MQTT5 will use allocators associated with handlers from asynchronous functions to create instances of objects needed in the library implementation.
Per-operation cancellation	All asynchronous operations support individual, targeted cancellation as per Asio's Per-Operation Cancellation. This enables all asynchronous functions to be used in Parallel Operations, which is especially beneficial for executing operations that require a timeout mechanism.
Full implementation of MQTT 5.0 specification	Ensures full compatibility with MQTT 5.0 standard. This latest version introduces essential features that enhance system robustness, including advanced error-handling mechanisms, session and message expiry, and other improvements designed to support modern IoT use cases.
Support for QoS 0, QoS 1, and QoS 2	Fully implements all quality-of-service levels defined by the MQTT protocol to match different reliability needs in message delivery.
Custom authentication	Defines an interface for your custom authenticators to perform `Enhanced Authentication`. In addition to username/password authentication, this customization point enables the implementation of any authentication mechanism supported by the SASL protocol, offering flexibility for advanced security requirements.
High availability	Supports listing multiple Brokers within the same cluster to which the Client can connect. In the event of a connection failure with one Broker, the Client switches to the next in the list.
Offline buffering	Automatically buffers all requests made while offline, ensuring they are sent when the connection is re-established. This allows users to call any asynchronous function freely, regardless of current connection status.

Getting Started

Async.MQTT5 is a header-only library. To use Async.MQTT5 it requires the following:

C++17 capable compiler
Boost 1.82 or later. In addition to Asio, we use other header-only libraries.
OpenSSL. If you require an SSL connection by using boost::asio::ssl::stream.

Async.MQTT5 has been tested with the following compilers:

clang 12.0 - 18.0 (Linux)
GCC 9 - 14 (Linux)
MSVC 14.37 - Visual Studio 2022 (Windows)

Using the Library

Download Boost, and add it to your include path.
If you use SSL, download OpenSSL, link the library and add it to your include path.
Add Async.MQTT5's include folder to your include path.

You can compile the example below with the following command line on Linux:

clang++ -std=c++17 <source-cpp-file> -o example -I<path-to-boost> -Iinclude -pthread

Example

The following example illustrates a scenario of configuring a Client and publishing a "Hello World!" Application Message with QoS 0.

#include <iostream>

#include <boost/asio/detached.hpp>
#include <boost/asio/io_context.hpp>
#include <boost/asio/ip/tcp.hpp>

#include <async_mqtt5.hpp>

int main() {
	boost::asio::io_context ioc;

	async_mqtt5::mqtt_client<boost::asio::ip::tcp::socket> c(ioc);

	c.credentials("<your-client-id>", "<client-username>", "<client-pwd>")
		.brokers("<your-mqtt-broker>", 1883)
		.async_run(boost::asio::detached);

	c.async_publish<async_mqtt5::qos_e::at_most_once>(
		"<topic>", "Hello world!",
		async_mqtt5::retain_e::no, async_mqtt5::publish_props {},
		[&c](async_mqtt5::error_code ec) {
			std::cout << ec.message() << std::endl;
			c.async_disconnect(boost::asio::detached); // disconnect and close the Client
		}
	);

	ioc.run();
}

To see more examples, visit Examples.

Acknowledgements

We thank Christopher Kohlhoff for his outstanding Boost.Asio library, which inspired the design of all interfaces and implementation strategies.