Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

luamqtt - Pure-lua MQTT v3.1.1 and v5.0 client

luamqtt logo

License tests Coverage Status Mentioned in Awesome MQTT forthebadge

MQTT ( ) client library for Lua. MQTT is a popular network communication protocol working by "publish/subscribe" model.

This library is written in pure-lua to provide maximum portability.


  • Full MQTT v3.1.1 client-side support
  • Full MQTT v5.0 client-side support
  • Several long-living MQTT clients in one script thanks to ioloop




See flespi forum thread

Source Code


The only main dependency is a luasocket to establishing TCP connection to the MQTT broker. Install it like this:

luarocks install luasocket

On Lua 5.1 it also depends on LuaBitOp (bit) library to perform bitwise operations. It's not listed in package dependencies, please install it manually like this:

luarocks install luabitop

luasec (SSL/TLS)

To establish secure network connection (SSL/TSL) to MQTT broker you also need luasec module, please install it manually like this:

luarocks install luasec

This stage is optional and may be skipped if you don't need the secure network connection (e.g. broker is located in your local network).

Lua versions

It's tested to work on Debian 9 GNU/Linux with Lua versions:

  • Lua 5.1 ... Lua 5.3 (i.e. any modern Lua version)
  • LuaJIT 2.0.0 ... LuaJIT 2.1.0 beta3
  • It may also work on other Lua versions without any guarantees

Also I've successfully run it under Windows and it was ok, but installing luarock-modules may be a non-trivial task on this OS.


As the luamqtt is almost zero-dependency you have to install required Lua libraries by yourself, before using the luamqtt library:

luarocks install luasocket # optional if you will use your own connectors (see below)
luarocks install luabitop  # you don't need this for lua 5.3
luarocks install luasec    # you don't need this if you don't want to use SSL connections

Then you may install the luamqtt library itself:

luarocks install luamqtt

Or for development purposes;

# development branch:
luarocks install luamqtt --dev

# or from the cloned repo:
luarocks make

LuaRocks page


Here is a short version of examples/simple.lua:

-- load mqtt library
local mqtt = require("mqtt")

-- create MQTT client, flespi tokens info:
local client = mqtt.client{ uri = "", username = os.getenv("FLESPI_TOKEN"), clean = true }

-- assign MQTT client event handlers
    connect = function(connack)
        if connack.rc ~= 0 then
            print("connection to broker failed:", connack:reason_string(), connack)

        -- connection established, now subscribe to test topic and publish a message after
        assert(client:subscribe{ topic="luamqtt/#", qos=1, callback=function()
            assert(client:publish{ topic = "luamqtt/simpletest", payload = "hello" })

    message = function(msg)

        -- receive one message and disconnect
        print("received message", msg)

-- run ioloop for client

More examples placed in examples/ directory. Also checkout tests in tests/spec/mqtt-client.lua

Also you can learn MQTT protocol by reading tests/spec/protocol4-make.lua and tests/spec/protocol4-parse.lua tests


Connector is a network connection layer for luamqtt. There is a three standard connectors included:

The luasocket or luasocket_ssl connector will be used by default, if not specified, according secure=true/false option per MQTT client.

In simple terms, connector is a set of functions to establish a network stream (TCP connection usually) and send/receive data through it. Every MQTT client instance may have their own connector.

And it's very simple to implement your own connector to make luamqtt works in your environment.

Bugs & contributing

Please file a GitHub issue if you found any bug.

And of course, any contribution are welcome!


To run tests in this git repo you need busted:

busted -e 'package.path="./?/init.lua;./?.lua;"..package.path' tests/spec/*.lua

There is a script to run all tests for all supported lua versions, using hererocks:


Code coverage

Code coverage may be collected using luacov.

To collect code coverage stats - install luacov using luarocks and then execute:

# collect stats during tests
busted -v -e 'package.path="./?/init.lua;./?.lua;"..package.path;require("luacov.runner")(".luacov")' tests/spec/*.lua

# generate report into file

MQTT version

Currently supported is:

Both protocols has full control packets support.


Standard MIT License, see LICENSE file for full text

Version bump checklist

  • in file ./mqtt/const.lua: change _VERSION table field
  • in file ./openwrt/ change Version: X.Y.Z-P in $PKG_ROOT/control
  • in file ./openwrt/Makefile: change PKG_VERSION:=X.Y.Z and maybe PKG_RELEASE:=1
  • copy file ./luamqtt-scm-1.rockspec to ./rockspecs/luamqtt-X.Y.Z-1.rockspec change local package_version = "scm", local package_version = "X.Y.Z"
  • run ./tests/ and check output for errors
  • run ./tests/ and check output for errors
  • run ./openwrt/ and check output for errors
  • run git commit, git tag vX.Y.Z
  • run git push, git push --tags
  • upload to LuaRocks; luarocks upload ./rockspecs/luamqtt-X.Y.Z-1.rockspec --api-key=ABCDEFGH