MQTT Client Library Encyclopedia – Paho Embedded

Guest post by Ian Craggs

Paho Embedded MQTT Client (MQTTClient)
Language C++
API-Style Blocking
License EPL and EDL


The Paho embedded client libraries arose out of the desire to allow the smallest microcontrollers to easily connect to MQTT servers. In this world, there are a large number of operating systems and network APIs, so
it was important that the libraries be as portable as possible. With this in mind I decided, after some
helpful discussions, that the attributes needed by the APIs were:

  • to use very limited and predictable resources: no dynamic memory allocation
  • not to rely on any particular libraries for networking, threading or memory management
  • ANSI standard C, or basic C++ for maximum portability

While I tried to make these APIs as helpful as possible, the constraints of portability and low, predictable
resource use means that they are sometimes less helpful than other MQTT libraries.
Note that I say “APIs”: there is more than one. The two that have been released in Paho so far are:

  1. MQTTPacket: the lowest level library in C, the base on which the other APIs are built. It simply deals with serialization and deserialization of MQTT packets. There are some helper functions for reading packets from and writing them to, the network. It will work just about anywhere a C compiler exists.
  2. MQTTClient: a C++ library first written for the mbed platform. It is written in the conventional language for mbed, C++. It still avoids dynamic memory allocations, and has replaceable classes for OS and network dependent functions. Use of the STL is also avoided. It is based on, and requires, MQTTPacket.

A C version of MQTTClient also exists, and an asynchronous API is planned along with other optional features. For the purpose of this blog, I’m going to confine myself to the MQTTClient API.


MQTT 3.1
MQTT 3.1.1 ok
LWT ok
Automatic Reconnect nok
Disk Persistence nok
QoS 0 ok
QoS 1 ok
QoS 2 ok
Authentication ok
Throttling nok
Offline Message Buffering nok



Because of the variety of microcontroller environments, there is no one install mechanism. The simplest option is to clone the git repository – this contains build scripts for Linux. On mbed, you can import the library into your IDE from An Arduino package is available from the Paho downloads page.

Network and Timer Classes
First of all you need classes which implement network and timer functionality needed by the API for the platform you are building your application on. Examples for Linux, mbed and Arduino are already available. It should be a simple matter to create your own for another environment. The timer class (which counts down, not up) needs to implement the following methods:

and the network class the following:

as a minimum.

Application Setup
Before including the header file, if you want to use QoS 2, you must set:

otherwise the QoS code is omitted to save resources. If you activate QoS 2, then there is another setting:

which is the maximum number of unprocessed, or “in flight” messages that the API can handle. Then we can include the header:


First of all you need to establish the network connection. This is not done within the library, for portability. The mbed example for this is:

We create the client object by passing a network class instance to it:

Note the class names – these are passed as template parameters. MQTT::Client also has two other optional parameters:

which we have not used here. Now we can issue the MQTT connect:

Connect with LWT

Connect with Username / Password



Each subscription has its own callback which receives messages on the subscribed topic.



Similar to connect, the disconnect method just issues the MQTT disconnect. You must close the network connection explicitly.

Using TLS / SSL

To use TLS, you must implement a network class which establishes the secured connection and then reads from and writes to, that secured connection. The main MQTTClient code does not contain any specific TLS code. An example of how to do this is described at:

Example Application

A simple general application (HelloMQTT) for mbed

An application which connects to IBM’s Internet of Things Foundation service

HelloMQTT for Arduino

Linux samples

Author Information

Ian Craggs | IBM
Ian Craggs works for IBM, and has been involved with MQTT for more than 10 years. He wrote the IBM MQTT server Really Small Message Broker which became the inspiration for the Eclipse Mosquitto project. He contributed C client libraries to the Eclipse Paho project at its onset and is now the project leader.


  1. Himanshu says:

    How to get a MQTT C Client library for Windows CE 6.0?

    Is MQTT Communication is possible on Windows CE 6.0 excludinig M2MQTT for .Net Compact Framework 3.5?


    1. sampeper says:

      Hi Himanshu,

      have you created the MQTT lib for windows ce now?


  2. Lyubomyr says:

    The IPStack that You mentioned in this article is for the Ethernet connection according to the library. But it works with esp8266 WiFi also. However there is a WiFistack file included into the library. How shall I use it? Is it better to use it for WiFi connection?

  3. Maunik Patel says:

    I want to send some data from my BeagleBone Black (BBB) to a Cloud Service using MQTT protocol (I have ubuntu 16.04 as my development PC).

    For this project, I have too many confusions regarding MQTT libraries.
    I think, I am missing some very basic things and thats why having too many difficulties in compiling even a single application using MQTT Library.
    It may happen that you have already answered some of my below mentioned question, in this article, but as I am confused a lot, I can’t figure it out, on my own.
    If you can, Please help me, and answer my following questions descriptively, and step-by-step.
    (I am totally New in Embedded Linux)

    Basic Setup:
    1. How to build both of those libraries from source code ?
    2. How to compile an application using those libraries ?
    Particularly for BeagleBone Black:
    1. Should I use Paho C library OR Paho Embedded C Library to support my BBB?
    2. Where should I compile the library ? on my Ubuntu PC OR on BBB itself?
    3. In case the ans. of above question is ‘BBB’, is it possible to cross compile the library and application for BBB, on my Ubuntu PC, and then simply copying and running them to BBB ? (to save memory of BBB)
    Thanks and Regards,
    Maunik Patel

Leave a Reply

Your email address will not be published. Required fields are marked *