Proposal for yet another MQTT library for Boost
Dear Boost Developers, I'd like to propose a MQTT library to the Boost Libraries. Repository link: https://github.com/redboltz/async_mqtt Document link: https://redboltz.github.io/async_mqtt/doc/5.0.0/index.html Here is characteristics of async_mqtt: - C++17 or later is required. - async_mqtt supports Boost.Asio style completion tokens. - e.g. use_future, deferred, use_awaitable, callback functions, etc - Not only MQTT client but also MQTT server is supported. - User can use this library to develop MQTT broker. - Sample MQTT broker application is included. - Both MQTT v3.1.1 and v5.0 are supported. - In addition, undetermined protocol version is supported for server implementation. In this case, the protocol version is decided when you receive CONNECT packet. - Continuous packet sending - Users can send the next MQTT packets before the previous sending is not completed (completion handler is not invoked yet). - Auto acquiring/mapping topic alias is supported. - In addition, when resending a PUBLISH packet after reconnecting, the topic alias is removed and the original topic is restored. It is required by MQTT v5.0 spec. - Packet based send()/recv() APIs. - MQTT has various packets and some of their fields are optional. In order to keep simple APIs, async_mqtt uses packet based APIs. - See https://redboltz.github.io/async_mqtt/doc/5.0.0/tutorial/send_recv.html - Layered archtecture - async_mqtt can have predefined TCP, TLS, WS, WSS, and user defined underlying layer. Users can access the underlying layer using next_layer() member function of MQTT endpoint. So you can configure any layers by yourself. e.g. tcp_no_delay, set send/recv buffer size, etc - See https://redboltz.github.io/async_mqtt/doc/5.0.0/tutorial/create_endpoint.htm... - High performance - See https://redboltz.github.io/async_mqtt/doc/5.0.0/performance.html Background I have developed another mqtt library mqtt_cpp https://github.com/redboltz/mqtt_cpp since 2015. It is widely used but has some limitations. For example: - The functions are directly mapped to packets(publish, subscribe, etc), so optional features are not designed cleanly. - Due to set_publish_hander / on_publish style handler design, Completion Token cannot be supported. Based on this 9years experience, I designed the new MQTT library. This is async_mqtt. I would appreciate if you could endorse this library. Regards, Takatoshi Kondo
I have looked over your documentation, and I think I'd prefer mireo's API for clients. Your library seems more low-level, which is not ideal for simple clients. However, support for a server is a different story. I think there might be space for two libraries, mireo/async-mqtt5 as the easy-to-use client, and your library as the low-level one for fine-tuning and servers. I would be very interested how you and the mireo team see any potential overlap/synergy/conflict with those two mqtt libraries. On Mon, Apr 29, 2024 at 11:42 PM Takatoshi Kondo via Boost <boost@lists.boost.org> wrote:
Dear Boost Developers,
I'd like to propose a MQTT library to the Boost Libraries.
Repository link: https://github.com/redboltz/async_mqtt Document link: https://redboltz.github.io/async_mqtt/doc/5.0.0/index.html
Here is characteristics of async_mqtt: - C++17 or later is required. - async_mqtt supports Boost.Asio style completion tokens. - e.g. use_future, deferred, use_awaitable, callback functions, etc - Not only MQTT client but also MQTT server is supported. - User can use this library to develop MQTT broker. - Sample MQTT broker application is included. - Both MQTT v3.1.1 and v5.0 are supported. - In addition, undetermined protocol version is supported for server implementation. In this case, the protocol version is decided when you receive CONNECT packet. - Continuous packet sending - Users can send the next MQTT packets before the previous sending is not completed (completion handler is not invoked yet). - Auto acquiring/mapping topic alias is supported. - In addition, when resending a PUBLISH packet after reconnecting, the topic alias is removed and the original topic is restored. It is required by MQTT v5.0 spec. - Packet based send()/recv() APIs. - MQTT has various packets and some of their fields are optional. In order to keep simple APIs, async_mqtt uses packet based APIs. - See https://redboltz.github.io/async_mqtt/doc/5.0.0/tutorial/send_recv.html - Layered archtecture - async_mqtt can have predefined TCP, TLS, WS, WSS, and user defined underlying layer. Users can access the underlying layer using next_layer() member function of MQTT endpoint. So you can configure any layers by yourself. e.g. tcp_no_delay, set send/recv buffer size, etc - See https://redboltz.github.io/async_mqtt/doc/5.0.0/tutorial/create_endpoint.htm... - High performance - See https://redboltz.github.io/async_mqtt/doc/5.0.0/performance.html
Background
I have developed another mqtt library mqtt_cpp https://github.com/redboltz/mqtt_cpp since 2015. It is widely used but has some limitations. For example: - The functions are directly mapped to packets(publish, subscribe, etc), so optional features are not designed cleanly. - Due to set_publish_hander / on_publish style handler design, Completion Token cannot be supported.
Based on this 9years experience, I designed the new MQTT library. This is async_mqtt.
I would appreciate if you could endorse this library.
Regards, Takatoshi Kondo
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
No dia 29 de abr. de 2024, às 17:42, Takatoshi Kondo via Boost <boost@lists.boost.org> escreveu:
Dear Boost Developers,
I'd like to propose a MQTT library to the Boost Libraries.
I’m endorsing the lib, but more generally I’m endorsing the presence in Boost of an MQTT client/server facility, which connects to the point raised by Klemens on having a conversation on the merits/synergies of the two current proposals. Joaquín M López Muñoz
Hi Klemens, Joaquin Thanks you for the feedbacks: https://github.com/redboltz/async_mqtt/blob/main/example/ep_cpp20coro_mqtt_c... This is the code that demonstrates simple MQTT client using async_mqtt with C++20 corutine. Underlying parts (name resolution, TCP, TLS, WS handshaking) are intentionally exclude from async_mqtt. Because users might want to customize the layers. It is similar as Boost.Beast design https://github.com/boostorg/beast/blob/develop/example/websocket/client/coro... I think that sending MQTT packet is simple too. However, I think that it is not a big difference. The biggest difference between async-mqtt5 and async_mqtt is the meaning of CompletionHandler. I guess that Klemens pointed is that. Am I understanding correctly? async_mqtt send() function's CompletionHandler is invoked when the underlying async_write is completed. async-mqtt5 sending functions (async_subscribe, async_unsubscribe, and async_publish) CompletionHandler is invoked the corresponding acknolege MQTT packet (SUBACK, UNSUBACK, PUBACK, PUBCOMP) is received. async_mqtt recv() function's CompletionHandler is invoked when any MQTT packet is receied, in addition when connection error is happened. async-mqtt5 async_receive() function's CompletionHandler is invoked when MQTT PUBLISH packet is received. As Klemens pointed out, async-mqtt5 easier to use than async_mqtt for casual usecases thanks to its higher level APIs. I guess that the high level APIs can be implemented on async_mqtt's comparatively low level APIs.I will consider what is the good abstraction for higher level APIs, based on your feedback. Thanks, Takatoshi Kondo 2024年4月30日(火) 2:12 Joaquín M López Muñoz via Boost <boost@lists.boost.org>:
No dia 29 de abr. de 2024, às 17:42, Takatoshi Kondo via Boost <boost@lists.boost.org> escreveu:
Dear Boost Developers,
I'd like to propose a MQTT library to the Boost Libraries.
I’m endorsing the lib, but more generally I’m endorsing the presence in Boost of an MQTT client/server facility, which connects to the point raised by Klemens on having a conversation on the merits/synergies of the two current proposals.
Joaquín M López Muñoz
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Hi Klemens, Joaquin I just added a high level MQTT client APIs layer based on the existing packet based endpoint. The document is updated. See https://redboltz.github.io/async_mqtt/doc/latest/index.html The new high level client is https://redboltz.github.io/async_mqtt/doc/latest/tutorial/client.html It has start(), subscribe(), unsubscribe(), publish(), recv(), disconnect() APIs. And the CompletionHandler is called when the corresponding packet is received from the broker, not when packet sending is completed. So users can choose client or endpoint. For casual usecases, client can be used. For detailed operation, endpoint can be used. A code example for users is https://github.com/redboltz/async_mqtt/blob/main/example/cl_cpp20coro_mqtt.c... Implementation code is https://github.com/redboltz/async_mqtt/blob/main/include/async_mqtt/client.h... You can see the actual behavior as follows: ``` git clone https://github.com/redboltz/async_mqtt.git cd async_mqtt mkdir build cd build cmake -DASYNC_MQTT_BUILD_EXAMPLES=ON .. make cl_cpp20coro_mqtt example/cl_cpp20coro_mqtt async-mqtt.redboltz.net 1883 ``` Regards, Takatoshi Kondo 2024年4月30日(火) 12:31 Takatoshi Kondo <redboltz@gmail.com>:
Hi Klemens, Joaquin Thanks you for the feedbacks:
https://github.com/redboltz/async_mqtt/blob/main/example/ep_cpp20coro_mqtt_c... This is the code that demonstrates simple MQTT client using async_mqtt with C++20 corutine.
Underlying parts (name resolution, TCP, TLS, WS handshaking) are intentionally exclude from async_mqtt. Because users might want to customize the layers. It is similar as Boost.Beast design https://github.com/boostorg/beast/blob/develop/example/websocket/client/coro...
I think that sending MQTT packet is simple too.
However, I think that it is not a big difference.
The biggest difference between async-mqtt5 and async_mqtt is the meaning of CompletionHandler. I guess that Klemens pointed is that. Am I understanding correctly?
async_mqtt send() function's CompletionHandler is invoked when the underlying async_write is completed. async-mqtt5 sending functions (async_subscribe, async_unsubscribe, and async_publish) CompletionHandler is invoked the corresponding acknolege MQTT packet (SUBACK, UNSUBACK, PUBACK, PUBCOMP) is received.
async_mqtt recv() function's CompletionHandler is invoked when any MQTT packet is receied, in addition when connection error is happened. async-mqtt5 async_receive() function's CompletionHandler is invoked when MQTT PUBLISH packet is received.
As Klemens pointed out, async-mqtt5 easier to use than async_mqtt for casual usecases thanks to its higher level APIs. I guess that the high level APIs can be implemented on async_mqtt's comparatively low level APIs.I will consider what is the good abstraction for higher level APIs, based on your feedback.
Thanks, Takatoshi Kondo
2024年4月30日(火) 2:12 Joaquín M López Muñoz via Boost <boost@lists.boost.org>:
No dia 29 de abr. de 2024, às 17:42, Takatoshi Kondo via Boost <boost@lists.boost.org> escreveu:
Dear Boost Developers,
I'd like to propose a MQTT library to the Boost Libraries.
I’m endorsing the lib, but more generally I’m endorsing the presence in Boost of an MQTT client/server facility, which connects to the point raised by Klemens on having a conversation on the merits/synergies of the two current proposals.
Joaquín M López Muñoz
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
participants (3)
-
Joaquín M López Muñoz -
Klemens Morgenstern -
Takatoshi Kondo