An embedded MQTTv5 client in C++ with minimal footprint, maximal performance.

This repository contains a complete MQTT v5.0 client that's optimized for code size without sacrifying performance. This is, to my knowledge, the smallest (and complete!) MQTT v5.0 client for embedded system with a binary size down to less than 17kB on ESP32 (and less than 75kB on MacOSX). MQTT v5.0 is a more complex protocol than MQTT v3.1.1, with the addition of properties in each packet and authentication subsystem.

If you wonder what MQTT is (or isn't), feel free to consult this page.

For many reasons:

• Many clients around don't support MQTT v5.0 protocol (only limited to version 3.1.1)
• Some are large and/or requires numerous dependencies
• This code is specialized for embedded system with or without an operating system
• Many clients don't build on a linux system making debugging hard
• The license to use them is too restrictive
• Some client rely on a heap and fragment the heap quickly making usage over a long period dangerous

You'll find the client API documentation here.

There are two levels to access this client. The low level implies dealing with packet construction, serialization (without any network code). It's documented here.

The higher level API which is documented here is available when you only need to call methods of the Network::Client::MQTTv5 class (all serialization is done for you).

In all cases, almost all methods avoid allocating memory on the heap (stack is prefered whenever possible). There is only few places where heap allocations are performed and they are documented in there respective documentation.

Typically, user-generated Properties are allocating on the heap (in your code, not here) and user-generated SubscribeTopic are also allocating on the heap (in your code, not here).

An example software is provided that's implementing a complete MQTTv5 client in MQTTc.cpp where you can subscribe/publish to a topic. This file, once built on a Linux AMD64 system takes 80kB of binary space without any dependencies.

There is no lock in this library (except for sending packet to ensure atomicity while publishing a packet). Since any action happens in the eventLoop() function (the messageReceived callback is called there), it's safe to publish in the callback (the code is re-entrant). It's safe to publish from the same thread as the one running the eventLoop() function.

If you publish from a different thread than the event thread, you should enable the MQTTMultithread configuration option (enabled by default). In that case, it's safe to publish from any thread as long as the client isn't destructed. In case of error, the event loop will notify the user code where it's possible to reconnect the client and resume communication safely. Notice that as soon as an error is detected, publishing thread will receive errors and will not publish any packet, nor store them in the packet buffer if QoS is involved. In short, as soon as the communication is in error, any publication is lost, whatever the QoS. When communication resumes, only the packets that were published before the error was detected but not acknowledged by the broker yet will be resent, as specified in the standard.

Please notice that there's a lock for sending packets, so that 2 threads that are publishing simultaneously will be serialized and no interleaved data on the network layer could happen. You must not call the eventLoop() function from multiple threads since there's no lock for protecting data packet receiving.

The implementation for a new platform is very quick.

The only dependencies for this client rely on a Lock class to protect again multithreading access/reentrancy and a ScopedLock RAII class for acquiring and releasing the lock upon scope leaving. A default spinlock class is provided in the minimal implementation.

BSD socket API is used with only minimum feature set (only recv, send, getaddrinfo, select, socket, close/closesocket, setsockopt is required).

The only options used for socket (optional, can be disabled) are: TCP_NODELAY, fcntl/O_NONBLOCK, SO_SNDTIMEO, SO_RCVTIMEO)

Please check the MQTTClient.cpp file for two different examples of platform support (from complete, deterministic, Posix based implementation to simplest embedded system).

There is also a port for ESP32 here.

In addition to the client, the tests folder contains a MQTT packet parser for MQTT v5.0. It's built by default and used like this:

$ # Give it the raw bytes from network communication and it'll dump what it means
$ ./MQTTParsePacket 30 1E 00 18 73 74 61 74 75 73 2F 59 4F 4C 54 79 79 76 75 57 58 50 5A 2F 6C 6F 67 73 00 5B 31 5D
Detected PUBLISH packet
with size: 32
PUBLISH control packet (rlength: 30)
  Header: (type PUBLISH, retain 0, QoS 0, dup 0)
  PUBLISH packet (id 0x0000): Str (24 bytes): status/YOLTyyvuWXPZ/logs
  Properties with length VBInt: 0
  Payload (length: 3)

You can also give it a file containing the capture of the network payload:

$ ./MQTTParsePacket -f capture.dump
Detected PUBLISH packet
with size: 32
PUBLISH control packet (rlength: 30)
  Header: (type PUBLISH, retain 0, QoS 0, dup 0)
  PUBLISH packet (id 0x0000): Str (24 bytes): status/YOLTyyvuWXPZ/logs
  Properties with length VBInt: 0
  Payload (length: 3)