Skip to content

Paho Lua - MQTT Client Library Encyclopedia

by Kévin KIN-FOO
5 min read

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.

Overview of Paho Lua MQTT Client Library

Paho Lua
Language PHP
License EPL
Website https://www.eclipse.org/paho/
API Style Asynchronous

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

Features Supported by Paho Lua MQTT Client Library

Feature
MQTT 3.1 Yes
MQTT 3.1.1 Yes
LWT Yes
SSL/TLS Yes
Automatic Reconnect No

Advance Features Supported by Paho Lua MQTT Client Library

Feature Yes
QoS 0 Yes
QoS 1 Yes
QoS 2 Yes
Authentication Yes
Throttling No

Installation of Paho Lua MQTT Client Library

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

$ git clone https://git.eclipse.org/r/paho/org.eclipse.paho.mqtt.lua
$ cd org.eclipse.paho.mqtt.lua/
$ luarocks make rocks/paho-mqtt-0.3.0-1.rockspec

You are all set.

Note: tested on Lua 5.1.

How to Connect Paho Lua MQTT Client to an MQTT Broker?

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

local mqtt = require 'paho.mqtt'
local client = mqtt.client.create('broker.mqttdashboard.com')
client:connect('paho-lua-client-sample-identifier')

First step is creating MQTT client, here test.mosquitto.org 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.

local client = mqtt.client.create('broker.mqttdashboard.com')
client:auth('user', 'Pa$$w0rd')
client:connect('paho-lua-client-sample-identifier')

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

How to Publish an MQTT Message Using Paho Lua MQTT Client Library

Once you are connected it is as simple as:


client:publish('topic/sample', 'fancy message')

It publishes a fancy message on topic/sample.

How to Subscribe to An MQTT Message Using Paho Lua MQTT Client Library

local callback = function(topic, payload)
  print(string.format('Hey, %s just received: %s.', topic, payload))
end

-- Connect
local client = mqtt.client.create('broker.mqttdashboard.com', 1883, callback)
client:connect('paho-lua-client-sample-identifier')
client:subscribe({'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.

How to Unsubscribe to An MQTT Message Using Paho Lua MQTT Client Library

You no longer want to get message from a topic? Put it in a table and give it to

client:unsubscribe({'topic/sample'})

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

How to Disconnect From an MQTT Broker While Using Paho Lua?

client:disconnect()

Quite self-explanatory.

Full Example Application of Using Paho Lua MQTT Client Library

local mqtt = require 'paho.mqtt'
local socket = require 'socket'

local stop = false
local callback = function(topic, payload)
  print(string.format('Hey, %s just received: %s.', topic, payload))
  if payload == 'stop' then
    stop = true
  end
end

-- Connect
local client = mqtt.client.create('broker.mqttdashboard.com', 1883, callback)
client:connect('paho-lua-client-sample-identifier')

-- Subscribe to topic
local topic = 'topic/sample'
client:subscribe({topic})

-- Wait for publication
math.randomseed(os.time())
while not stop do

  -- Publish something on topic
  local message = math.random(0, 1) == 0 and 'Go on child' or 'stop'
  client:publish(topic, message)

  -- Wait gently
  client:handler()
  socket.sleep(1)

end

-- Cleaning up
client:unsubscribe({topic})
client:disconnect()
client:destroy()

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

First we connect to broker.mqttdashboard.com 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 https://github.com/KINFOO/

Kévin KIN-FOO

Kévin is doing fine things at Sierra Wireless. He said that he loves his software simple.

  • Kévin KIN-FOO on X
  • Contact Kévin KIN-FOO via e-mail

Related content:

HiveMQ logo
Review HiveMQ on G2