MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks. The design principles are to minimise network bandwidth and device resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery. These principles also turn out to make the protocol ideal of the emerging "machine-to-machine" (M2M) or "Internet of Things" world of connected devices, and for mobile applications where bandwidth and battery power are at a premium.
— Official description of MQTT from mqtt.org
This MQTT library implements a subset of the MQTT 3.1.1 standard. Features of this library include:
- Both fully asynchronous and blocking API functions.
- Scalable performance and footprint. The configuration settings allow this library to be tailored to a system's resources.
- Attention
- Currently, this library does not support QoS 2 MQTT messages.
Dependencies
Dependencies of the MQTT library.
Currently, the MQTT library has the following dependencies:
- The linear containers library for maintaining the data structures for managing in-progress MQTT operations.
- The logging library may be used if IOT_LOG_LEVEL_MQTT is not IOT_LOG_NONE.
- The task pool to submit background jobs. The MQTT library does not create or manage any threads, but relies on at least one thread being available in the task pool.
In addition to the components above, the MQTT library also depends on C standard library headers and the platform layer.
Memory requirements
Memory requirements of the MQTT library.
Code size
Code size of the MQTT library.
The following measurements were taken with arm-none-eabi-gcc v9.2.1 (October 2019) with the MQTT library from January 2020. These values are rough estimates not tuned for any specific ARM processor.
Minimal Size Build
No logging, asserts, or diagnostic information. Compiled using the ARM Thumb instruction set (-mthumb) and optimized for size (-Os). Values are in bytes.
| object | text | data | bss |
| iot_mqtt_api | 2703 | 0 | 4 |
| iot_mqtt_network | 884 | 0 | 0 |
| iot_mqtt_operation | 1773 | 0 | 0 |
| iot_mqtt_serialize | 2606 | 4 | 0 |
| iot_mqtt_subscription | 1244 | 0 | 0 |
| iot_mqtt_validate | 444 | 0 | 0 |
| total | 9654 | 4 | 4 |
Debug Build
All logging, asserts, and diagnostic information enabled. Debugging symbols available. Compiled using the ARM Thumb instruction set (-mthumb). Values are in bytes.
| object | text | data | bss |
| iot_mqtt_api | 11897 | 0 | 4 |
| iot_mqtt_network | 5412 | 0 | 0 |
| iot_mqtt_operation | 10484 | 0 | 0 |
| iot_mqtt_serialize | 14454 | 28 | 0 |
| iot_mqtt_subscription | 3885 | 0 | 0 |
| iot_mqtt_validate | 4330 | 0 | 0 |
| total | 50462 | 28 | 4 |
Runtime memory requirements
Runtime memory requirements of the MQTT library.
The values given below do not consider any dependencies, such as the task pool or TLS stack.
Approximate sizes of MQTT objects are given below. Note that the exact size depends on how certain platform types (such as mutexes) are implemented.
| Each MQTT connection | 250 bytes |
| Each MQTT operation | 150 bytes, plus the length of a topic name and message if publishing |
| Each MQTT subscription | 70 bytes, plus the length of the subscription topic filter |
For example, consider an application that does the following:
- Establishes an MQTT connection.
- Subscribes to a topic.
- Publishes a message to a topic.
- Unsubscribes from a topic.
- Closes the connection.
This application is expected to have a peak runtime memory usage of about 600 bytes (not counting any usage by dependencies or the TLS stack).
By default, this memory would be allocated from the heap using the configured memory allocation functions. If IOT_STATIC_MEMORY_ONLY is defined to 1, then the memory will be allocated at compile-time.
