Paho Embedded - MQTT Client Library Encyclopedia
|Paho Embedded MQTT Client (MQTTClient)
|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:
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.
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.
|Offline Message Buffering
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 https://developer.mbed.org. An Arduino package is available from the Arduino Libraries 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:
#define MAX_INCOMING_QOS2_MESSAGES 10
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 here.
- A simple general application (HelloMQTT) for mbed
- An application which connects to IBM’s Internet of Things Foundation service
- HelloMQTT for Arduino
- Linux samples
About Ian Craggs
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.Contact HiveMQ