MQTT 3.1.1 client library
Return to main page ↑
MQTT Documentation

MQTT 3.1.1 client library.

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

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.
Currently, this library does not support QoS 2 MQTT messages.


Dependencies of the MQTT library.

MQTT direct dependencies

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:

  1. Establishes an MQTT connection.
  2. Subscribes to a topic.
  3. Publishes a message to a topic.
  4. Unsubscribes from a topic.
  5. 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.