The MQTT library on mbed.org also now exists in Eclipse Paho. I intend Paho to be the master copy.
There are two APIs in this library, the largely complete synchronous API in MQTTClient.h, and the unfinished asynchronous API in MQTTAsync.h. In this post I’ll be talking about the synchronous API. I have discussed the major design points previous posts, now I’ll describe how to use the API. The documentation page on mbed can be found here.
The API implementation is intended to avoid system calls to allow it to be easily ported. Its function is limited purely to MQTT rather than networking setup for instance. This does mean that there is some work to use the API on a new OS, but we plan to collect examples in Paho for as many OSes as we can — contributions welcome!
The API is defined as a class template with these parameters:
template<class Network, class Timer, int MAX_MQTT_PACKET_SIZE = 100, int MAX_MESSAGE_HANDLERS = 5>
There are two class parameters, Network and Timer which are needed to provide platform specific implementations of sending and receiving data from the network, and timing, respectively. The third and fourth parameters are limits on the maximum MQTT packet size to be handled and the number of message handling callbacks. For each subscription, a message handling callback is needed, so you can think of this second limit as the maximum number of subscriptions you can have active at one time. Increasing these limits will increase the storage used when allocating the MQTT client object.
The file mbed.h contains an mbed specific implmentation of the Timer class. The file MQTTSocket.h contains an mbed specific network implementation for the Ethernet interface. The only requirements for the network class that you need to supply are the two methods:
int read(unsigned char* buffer, int len, int timeout);
int write(unsigned char* buffer, int len, int timeout);
Where
- buffer
- is the location to write data to, or read data from
- len
is the number of bytes of that datatimeoutis the maximum number of milliseconds for the operation to complete.
The timer class counts down from a value to zero. I chose this way because it is always used for timeouts, so it checks to see whether the time has expired:
bool expired(); // has the time expired?
void countdown_ms(int ms); // start the timer for ms milliseconds
void countdown(int seconds); // start the timer in seconds
int left_ms(); // return the time left in milliseconds
Looking at the mbed example HelloMQTT, you see we have to connect the network interface before calling the MQTT connect:
MQTTEthernet ipstack = MQTTEthernet();
MQTT::Client<MQTTEthernet, Countdown> client = MQTT::Client<MQTTEthernet, Countdown>(ipstack);
int rc = ipstack.connect("m2m.eclipse.org", 1883);
if (rc != 0)
lcd.printf("rc from TCP connect is %d\n", rc);
MQTTPacket_connectData data = MQTTPacket_connectData_initializer;
data.MQTTVersion = 3;
data.clientID.cstring = "mbed-sample";
data.username.cstring = "testuser";
data.password.cstring = "testpassword";
if ( (rc = client.connect(&data)) != 0)
lcd.printf("rc from MQTT connect is %d\n", rc);
and then we can call subscribe, publish, unsubscribe and disconnect methods on the client in the usual sort of way for MQTT APIs.
Examples of how to use this API on Linux is in this
directory on Paho, in the hello.cpp and stdoutsub.cpp programs. The API is already running on Arduino, for which we’ll add an example, and for other platforms and operating systems later.