boostorg/mqtt5
1
0
Fork 1
mirror of https://github.com/boostorg/mqtt5.git synced 2025-07-29 20:17:37 +02:00
Code Issues Packages Projects Releases Wiki Activity

README.md revisited

Browse Source 
Summary:
related to T15263
If accepted, the changes will be applied to 01_intro.qbk in this commit.
This revision addresses most of the Peter Tucan's suggestions about README/Introduction.

Reviewers: ivica

Reviewed By: ivica

Subscribers: iljazovic, miljen

Differential Revision: https://repo.mireo.local/D32287
This commit is contained in:
Korina Šimičević
2024-11-21 13:24:57 +01:00
parent edb94108b6
commit 913d8a102d
2 changed files with 202 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
README.md
View File

@ -7,38 +7,65 @@ Branch | Windows/Linux Build | Coverage | Documentation |
Async.MQTT5 is a professional, industrial-grade C++17 client built on [Boost.Asio](https://www.boost.org/doc/libs/1_82_0/doc/html/boost_asio.html). 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.
Our clear intention is to include the Async.MQTT5 library into [Boost](https://www.boost.org/). We are actively working on it.
~~Our clear intention is to include the Async.MQTT5 library into [Boost](https://www.boost.org/). We are actively working on it.~~\
As of October 2024, the Async.MQTT5 library has been **conditionally ACCEPTED** into [Boost](https://www.boost.org/).
Motivation
---------
The [MQTT](https://mqtt.org/) 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 itself is relatively straightforward, integrating it into an application can be complex, especially due to the challenging implementation of message retransmission after a disconnect/reconnect sequence.
The [MQTT](https://mqtt.org/) 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, Async.MQTT5 was designed with the following core objectives in mind:
The aim of Async.MQTT5 is to provide a very simple asynchronous C++ interface for application developers. The internal Client's implementation manages network and MQTT protocol details. Notably, 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.
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. |
The Async.MQTT5 interface aligns seamlessly with the Boost.Asio asynchronous model. The Client's asynchronous functions are compatible with all completion tokens supported by Boost.Asio.
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:
- **Complete TCP, TLS/SSL, and WebSocket support**
- **User-focused simplicity**: Providing an interface that is as simple as possible without compromising functionality.
- **Prioritised efficiency**: Utilising network and memory resources as efficiently as possible.
- **Minimal memory footprint**: Ensuring optimal performance in resource-constrained environments typical of IoT devices.
- **Automatic reconnect**: Automatically attempt to re-establish a connection in the event of a disconnection.
- **Fully Boost.Asio compliant**: The interfaces and implementation strategies are built upon the foundations of Boost.Asio. Boost.Asio and Boost.Beast users will have no issues understanding and integrating Async.MQTT5. Furthermore, Async.MQTT5 integrates well with any other library within the Boost.Asio ecosystem.
- **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](https://www.boost.org/doc/libs/1_82_0/doc/html/boost_asio/overview/core/cancellation.html).
- **Completion Token**: All asynchronous functions support CompletionToken, allowing for versatile usage with callbacks, coroutines, futures, and more.
- **Full implementation of MQTT 5.0 specification**
- **Support for QoS 0, QoS 1, and QoS 2**
- **Custom authentication**: Async.MQTT5 defines an interface for your own custom authenticators to perform Enhanced Authentication.
- **High availability**: Async.MQTT5 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**: While offline, it automatically buffers all the packets to send when the connection is re-established.
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](https://spacetime.mireo.com/async-mqtt5/async_mqtt5/auto_reconnect.html). |
**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](https://www.boost.org/doc/libs/1_82_0/doc/html/boost_asio/overview/core/cancellation.html). This enables all asynchronous functions to be used in [Parallel Operations](https://www.boost.org/doc/libs/1_86_0/doc/html/boost_asio/overview/composition/parallel_group.html), 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](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html). 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](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901256). 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. |
Using the library
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 such as Beast, Spirit, and more.
- **OpenSSL**. If you require an SSL connection by using [boost::asio::ssl::stream](https://www.boost.org/doc/libs/1_82_0/doc/html/boost_asio/reference/ssl__stream.html).
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
---------
1. Download [Boost](https://www.boost.org/users/download/), and add it to your include path.
@ -49,9 +76,10 @@ 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
Usage and API
Example
---------
The following example illustrates a simple scenario of configuring a Client and publishing a
The following example illustrates a scenario of configuring a Client and publishing a
"Hello World!" Application Message with `QoS` 0.
```cpp
@ -77,7 +105,7 @@ int main() {
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
c.async_disconnect(boost::asio::detached); // disconnect and close the Client
}
);
@ -106,31 +134,6 @@ The source file is located at [example/hello_world_over_tcp.cpp](https://github.
You can edit the [example/CMakeLists.txt](https://github.com/mireo/async-mqtt5/blob/master/example/CMakeLists.txt) file to compile the source file of your choice.
By default, it will compile [example/hello_world_over_tcp.cpp](https://github.com/mireo/async-mqtt5/blob/master/example/hello_world_over_tcp.cpp).
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 a 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.
Requirements
---------
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 such as Beast, Spirit, and more.
- **OpenSSL**. Only if you require an SSL connection by using [boost::asio::ssl::stream](https://www.boost.org/doc/libs/1_82_0/doc/html/boost_asio/reference/ssl__stream.html).
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)
Contributing
---------

208
doc/qbk/01_intro.qbk
View File

@ -15,42 +15,165 @@ offering full support for publishing or receiving messages with QoS 0, 1, and 2.
[heading 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 itself is relatively straightforward, integrating it into an application can be complex,
especially due to the challenging implementation of message retransmission after a disconnect/reconnect sequence.
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, __Self__ was designed with the following core objectives in mind:
The aim of __Self__ is to provide a very simple asynchronous C++ interface for application developers.
The internal Client's implementation manages network and MQTT protocol details.
Notably, 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.
[table:objectives 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.
]
]
]
The __Self__ interface aligns seamlessly with the __Asio__ asynchronous model.
The Client's asynchronous functions are compatible with all completion tokens supported by __Asio__.
[heading When to Use]
__Self__ might be suitable for you if any of the following statements is true:
* Your application uses __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.
[heading Features]
__Self__ is a library designed with the core belief that users should focus solely on their application logic, not the network complexities. [br]
The library attempts to embody this belief with a range of key features designed to elevate the development experience:
* [*Complete TCP, TLS/SLL, and WebSocket support]
* [*User-focused simplicity]: Providing an interface that is as simple as possible without compromising functionality.
* [*Prioritised efficiency]: Utilising network and memory resources as efficiently as possible.
* [*Minimal memory footprint]: Ensuring optimal performance in resource-constrained environments typical of IoT devices.
* [*Automatic reconnect]: Automatically attempt to re-establish a connection in the event of a disconnection.
* [*Fully Boost.Asio compliant]: The interfaces and implementation strategies are built upon the foundations of __Asio__. [br]
__Asio__ and __Beast__ users will have no issues understanding and integrating __Self__. [br]
Furthermore, __Self__ integrates well with any other library within the Boost.Asio ecosystem.
* [*Custom allocators]: Support for custom allocators allows extra flexibility and control over the memory resources. [br]
__Self__ 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 __ASIO_PER_OP_CANCELLATION__.
* [*Completion Token]: All asynchronous functions support __CompletionToken__, allowing for versatile usage with callbacks, coroutines, futures, and more.
* [*Full implementation of MQTT 5.0 specification]
* [*Support for QoS 0, QoS 1, and QoS 2]
* [*Custom authentication]: __Self__ defines an interface for your own custom authenticators to perform Enhanced Authentication.
* [*High availability]: __Self__ supports listing multiple Brokers within the same cluster to which the Client can connect. [br]
In the event of a connection failure with one Broker, the Client switches to the next in the list.
* [*Offline buffering]: While offline, it automatically buffers all the packets to send when the connection is re-established.
[table:features 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 [link async_mqtt5.auto_reconnect 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 __ASIO_PER_OP_CANCELLATION__.
This enables all asynchronous functions to be used in [@boost:/doc/html/boost_asio/overview/composition/parallel_group.html 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 [@https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html 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_AUTH__.
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.
]
]
]
[heading Getting Started]
__Self__ is a header-only library.
To use __Self__ it requires the following:
* [*C++17 capable compiler]
* [*Boost 1.82 or later]. In addition to Asio, we use other header-only libraries such as Beast, Spirit, and more.
* [*OpenSSL]. If you require an SSL connection by using [asioreflink ssl__stream ssl::stream].
__Self__ has been tested with the following compilers:
* clang 12.0 - 18.0 (Linux)
* GCC 9 - 14 (Linux)
* MSVC 14.37 - Visual Studio 2022 (Windows)
[heading Using the Library]
# Download [@https://www.boost.org/users/download/ Boost], and add it to your include path.
# If you use SSL, download [@https://www.openssl.org/ 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
[heading Example]
The following example illustrates a simple scenario of configuring a Client and publishing a
The following example illustrates a scenario of configuring a Client and publishing a
"Hello World!" Application Message with `QoS` 0.
[!c++]
@ -76,7 +199,7 @@ The following example illustrates a simple scenario of configuring a Client and
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
c.async_disconnect(boost::asio::detached); // disconnect and close the Client
}
);
@ -102,35 +225,6 @@ The source file is located at [ghreflink example/hello_world_over_tcp.cpp exampl
You can edit the [ghreflink example/CMakeLists.txt example/CMakeLists.txt] file to compile the source file of your choice.
By default, it will compile [ghreflink example/hello_world_over_tcp.cpp example/hello_world_over_tcp.cpp].
[heading When to use]
__Self__ might be suitable for you if any of the following statements is true:
* Your application uses __Asio__ and requires integrating a 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.
[heading Requirements]
__Self__ is a header-only library.
To use __Self__ it requires the following:
* [*C++17 capable compiler]
* [*Boost 1.82 or later]. In addition to Asio, we use other header-only libraries such as Beast, Spirit, and more.
* [*OpenSSL]. Only if you require an SSL connection by using [asioreflink ssl__stream ssl::stream].
__Self__ has been tested with the following compilers:
* clang 12.0 - 18.0 (Linux)
* GCC 9 - 14 (Linux)
* MSVC 14.37 - Visual Studio 2022 (Windows)
[heading Acknowledgements]
We thank [@https://github.com/chriskohlhoff Christopher Kohlhoff] for his outstanding __Asio__ library,
which inspired the design of all interfaces and implementation strategies.