Boost.MQTT5: A C++17 MQTT client based on Boost.Asio

Branch	Linux Build	Windows Build	Coverage	Documentation
master				documentation
develop				documentation

Boost.MQTT5 is a professional, industrial-grade C++17 client built on Boost.Asio. This Client is designed for publishing or receiving messages from an MQTT 5.0 compatible Broker. Boost.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 used for communication in various real-world scenarios, primarily 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, Boost.MQTT5 was designed with the following core objectives in mind:

When to Use

Boost.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

Boost.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:

Getting Started

Boost.MQTT5 is a header-only library. To use Boost.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.

Boost.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

1. Download Boost, and add it to your include path.
2. If you use SSL, download OpenSSL, link the library and add it to your include path.
3. Add Boost.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 <boost/mqtt5/mqtt_client.hpp>
#include <boost/mqtt5/types.hpp>

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

#include <iostream>

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

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

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

	c.async_publish<boost::mqtt5::qos_e::at_most_once>(
		"<topic>", "Hello world!",
		boost::mqtt5::retain_e::no, boost::mqtt5::publish_props {},
		[&c](boost::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.

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.

You may merge a Pull Request once you have the sign-off from other developers, or you may request the reviewer to merge it for you.

Credits

Maintained and authored by Mireo.