MQTT Client Library Encyclopedia – Paho Lua

Guest post by Kévin KIN-FOO

Language Lua
API-Style Asynchronous
License EPL


Paho Lua Client library implements client-side subset of the MQTT protocol specification 3.1. An advantage of using Lua is that only a text editor is required for rapid development of simple MQTT client applications on many platforms. Cross compilation issues are avoided.

Initially part of Aiko Platform, this library is now part of Eclipse Paho project.


MQTT 3.1
MQTT 3.1.1 nok
LWT nok
Automatic Reconnect nok
QoS 0 ok
QoS 1 nok
QoS 2 nok
Authentication ok
Throttling nok



As I am writing easiest way to install Paho Lua Client is from sources using LuaRocks.

You are all set.

Note: tested on Lua 5.1.


This section shows the API usage how to connect with the library to a MQTT broker.

First step is creating MQTT client, here is used as broker host. As port is not specified, 1183 is used by default.
Then you can simply call client:connect() with a client identifier of your choice.

Connect with Username / Password

Authentication is just one additional line.

Calling client:auth() before client:connect() enables to set username and password.


Once you are connected it is as simple as:

It publishes a fancy message on topic/sample.


You can subscribe on several topics by providing them to client:subscribe() in a table.
Once something arrives on topic, callback defined at connection is called.


You no longer want to get message from a topic? Put it in a table and give it to client:unsubscribe().


Quite self-explanatory.

Full Example Application

What we are doing here is publishing random strings on topic/sample forever until being told to “stop”.

First we connect to on default port 1883. At connection, we define a callback to handle received messages.

Then we subscribe to topic/sample topic.

Now we publish a string on topic we just subscribed to, client:handler() checks for received messages. When there is one, callback(topic, message) is called to deal with it. We repeat this relentlessly.

Once this message is string “stop”, we stop looping, unsubscribe from topic/sample.

To clean all this, we disconnect from server and destroy our client to free allocated memory.

You can also find this example code at

Author Information

Kévin KIN-FOO | Sierra Wireless
I am doing fine things at Sierra Wireless. I love my software simple.


  1. Benjamin Cabé says:

    Great post!
    I think the Lua client supports LWT so you may want to update the table at the beginning!

    1. Hi Benjamin,

      thanks for the heads up! We updated the table to reflect your suggestion.

      All the best,
      Dominik from the HiveMQ Team

Leave a Reply

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